1use serde::{Deserialize, Serialize};
4use crate::finance::div_round_bankers;
5use crate::record::{q_hash_str, InstantBridge, NQuin, SensitivityClass};
6
7#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
9#[serde(rename_all = "snake_case")]
10pub enum AgreementAuthority {
11 Commissioned, OpenBounty, CooperativeMandate, StewardAuthorised, UnsolicitedNoAgreement,
12}
13
14#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
16#[serde(rename_all = "snake_case")]
17pub enum CompensationClass {
18 ContractedService, AcceptedBounty, ConditionalPoolShare, ReimbursableExpense, VoluntaryCommonsGift,
19}
20
21#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
23pub struct RequestAndAgreement {
24 pub id: String, pub project_id: String, pub contributor_did: String,
25 pub authorised_by_did: Option<String>, pub authority: AgreementAuthority,
26 pub compensation_class: CompensationClass, pub max_authorised_effort_minutes: u32,
27 pub max_authorised_expense_cents: i64, pub rate_cents_per_hour: i64, pub created_at_unix: u32,
28}
29
30impl RequestAndAgreement {
31 pub const fn is_commissioned_guarantee(&self) -> bool {
33 matches!(self.authority, AgreementAuthority::Commissioned | AgreementAuthority::StewardAuthorised)
34 && matches!(self.compensation_class, CompensationClass::ContractedService | CompensationClass::ReimbursableExpense)
35 && self.authorised_by_did.is_some()
36 }
37
38 pub fn compile_to_quins(&self, out: &mut [NQuin]) -> usize {
40 emit_stage_quins(&self.id, &self.project_id, "hro:RequestAndAgreement", self.rate_cents_per_hour as u64, self.created_at_unix, out)
41 }
42}
43
44#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
46pub struct ActivityAndResources {
47 pub id: String,
48 pub project_id: String,
49 pub contributor_did: String,
50 pub agreement_id: Option<String>,
51 pub work_item_id: Option<String>,
52 pub effort_minutes: u32,
53 pub reimbursable_expense_cents: i64,
54 pub capital_advanced_cents: i64,
55 pub occurred_at_unix: u32,
56 #[serde(default, skip_serializing_if = "Option::is_none")]
57 pub occurred_at_instant: Option<InstantBridge>,
58}
59
60impl ActivityAndResources {
61 pub fn compile_to_quins(&self, out: &mut [NQuin]) -> usize {
63 emit_stage_quins(&self.id, &self.project_id, "hro:ActivityAndResources", self.effort_minutes as u64, self.occurred_at_unix, out)
64 }
65}
66
67#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
69pub struct OutputOrService {
70 pub id: String,
71 pub project_id: String,
72 pub contributor_did: String,
73 pub activity_ids: Vec<String>,
74 pub artifact_uri: String,
75 pub non_monetary_badges: Vec<String>,
76 pub provenance_attestation_id: Option<String>,
77 pub produced_at_unix: u32,
78}
79
80impl OutputOrService {
81 pub fn compile_to_quins(&self, out: &mut [NQuin]) -> usize {
83 emit_stage_quins(&self.id, &self.project_id, "hro:OutputOrService", q_hash_str(&self.artifact_uri), self.produced_at_unix, out)
84 }
85}
86
87#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
89pub struct SubmissionOrClaim {
90 pub id: String,
91 pub project_id: String,
92 pub contributor_did: String,
93 pub agreement_id: Option<String>,
94 pub output_id: String,
95 pub claimed_effort_minutes: u32,
96 pub claimed_expense_cents: i64,
97 pub claimed_capital_cents: i64,
98 pub submitted_at_unix: u32,
99}
100
101impl SubmissionOrClaim {
102 pub fn compile_to_quins(&self, out: &mut [NQuin]) -> usize {
104 emit_stage_quins(&self.id, &self.project_id, "hro:SubmissionOrClaim", self.claimed_effort_minutes as u64, self.submitted_at_unix, out)
105 }
106}
107
108#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
110#[serde(rename_all = "snake_case")]
111pub enum AcceptanceOutcome {
112 Accepted,
113 AcceptedWithConditions,
114 RevisionRequested,
115 Rejected,
116 Deferred,
117 Disputed,
118}
119
120pub type AcceptanceStatus = AcceptanceOutcome;
122
123impl AcceptanceOutcome {
124 pub const fn is_accepted(&self) -> bool {
126 matches!(self, Self::Accepted | Self::AcceptedWithConditions)
127 }
128}
129
130#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
132pub struct AcceptanceDecision {
133 pub id: String,
134 pub project_id: String,
135 pub submission_id: String,
136 pub agreement_id: Option<String>,
137 pub outcome: AcceptanceOutcome,
138 pub reviewer_did: String,
139 pub conditions_or_rationale: Option<String>,
140 pub decided_at_unix: u32,
141}
142
143#[allow(non_upper_case_globals)]
144impl AcceptanceDecision {
145 pub const Accepted: AcceptanceOutcome = AcceptanceOutcome::Accepted;
146 pub const AcceptedWithConditions: AcceptanceOutcome = AcceptanceOutcome::AcceptedWithConditions;
147 pub const RevisionRequested: AcceptanceOutcome = AcceptanceOutcome::RevisionRequested;
148 pub const Rejected: AcceptanceOutcome = AcceptanceOutcome::Rejected;
149 pub const Deferred: AcceptanceOutcome = AcceptanceOutcome::Deferred;
150 pub const Disputed: AcceptanceOutcome = AcceptanceOutcome::Disputed;
151
152 pub fn compile_to_quins(&self, out: &mut [NQuin]) -> usize {
154 emit_stage_quins(&self.id, &self.project_id, "hro:AcceptanceDecision", self.outcome as u64, self.decided_at_unix, out)
155 }
156}
157
158#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
160pub struct Valuation {
161 pub id: String,
162 pub project_id: String,
163 pub submission_id: String,
164 pub acceptance_id: String,
165 pub valued_effort_cents: i64,
166 pub valued_expense_cents: i64,
167 pub valued_capital_cents: i64,
168 pub risk_cap_bps: u32,
169 pub approved_by_did: String,
170 pub valued_at_unix: u32,
171}
172
173impl Valuation {
174 pub const fn total_valued_cents(&self) -> i64 {
176 let cap_with_return = if self.risk_cap_bps == 0 {
177 self.valued_capital_cents
178 } else {
179 div_round_bankers((self.valued_capital_cents as i128) * (self.risk_cap_bps as i128), 10_000)
180 };
181 self.valued_effort_cents.saturating_add(self.valued_expense_cents).saturating_add(cap_with_return)
182 }
183
184 pub fn compile_to_quins(&self, out: &mut [NQuin]) -> usize {
186 emit_stage_quins(&self.id, &self.project_id, "hro:Valuation", self.total_valued_cents() as u64, self.valued_at_unix, out)
187 }
188}
189
190#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
192#[serde(rename_all = "snake_case")]
193pub enum ObligationStatus {
194 Active,
195 PartiallySettled,
196 Satisfied,
197 Waived,
198 Disputed,
199}
200
201#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
203pub struct LifecycleObligation {
204 pub id: String,
205 pub project_id: String,
206 pub beneficiary_did: String,
207 pub agreement_id: Option<String>,
208 pub acceptance_id: Option<String>,
209 pub valuation_id: Option<String>,
210 pub principal_cents: i64,
211 pub settled_cents: i64,
212 pub outstanding_cents: i64,
213 pub status: ObligationStatus,
214 pub waiver_terms: Option<String>,
215 pub waived_by_did: Option<String>,
216 pub created_at_unix: u32,
217}
218
219#[allow(non_upper_case_globals)]
220impl LifecycleObligation {
221 pub const Active: ObligationStatus = ObligationStatus::Active;
222 pub const PartiallySettled: ObligationStatus = ObligationStatus::PartiallySettled;
223 pub const Satisfied: ObligationStatus = ObligationStatus::Satisfied;
224 pub const Waived: ObligationStatus = ObligationStatus::Waived;
225 pub const Disputed: ObligationStatus = ObligationStatus::Disputed;
226
227 pub fn compile_to_quins(&self, out: &mut [NQuin]) -> usize {
229 emit_stage_quins(&self.id, &self.project_id, "hro:LifecycleObligation", self.outstanding_cents as u64, self.created_at_unix, out)
230 }
231}
232
233#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
235pub struct SettlementAllocation {
236 pub id: String,
237 pub project_id: String,
238 pub obligation_id: String,
239 pub beneficiary_did: String,
240 pub allocated_cents: i64,
241 pub currency: String,
242 pub source_pool_id: String,
243 pub beneficiary_receipt_hash: Option<u64>,
244 pub settled_at_unix: u32,
245}
246
247impl SettlementAllocation {
248 pub const fn has_verified_receipt(&self) -> bool {
250 self.allocated_cents > 0 && self.beneficiary_receipt_hash.is_some()
251 }
252
253 pub fn compile_to_quins(&self, out: &mut [NQuin]) -> usize {
255 emit_stage_quins(&self.id, &self.project_id, "hro:SettlementAllocation", self.beneficiary_receipt_hash.unwrap_or(0), self.settled_at_unix, out)
256 }
257}
258
259#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
261#[serde(rename_all = "snake_case")]
262pub enum TransitionReadiness {
263 Satisfied,
264 Held { reason: String },
265 Failed { reason: String },
266}
267
268impl TransitionReadiness {
269 pub const fn is_ready(&self) -> bool {
271 matches!(self, Self::Satisfied)
272 }
273}
274
275#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
277pub struct TransitionDecision {
278 pub id: String,
279 pub project_id: String,
280 pub target_licence_uri: String,
281 pub authorised_steward_did: String,
282 pub steward_is_human: bool,
283 pub pool_funded_cents: i64,
284 pub total_obligation_cents: i64,
285 pub settled_contributor_cents: i64,
286 pub unresolved_material_challenges: u32,
287 pub dependencies_compatible: bool,
288 pub decided_at_unix: u32,
289}
290
291impl TransitionDecision {
292 pub fn compile_to_quins(&self, out: &mut [NQuin]) -> usize {
294 emit_stage_quins(&self.id, &self.project_id, "hro:TransitionDecision", q_hash_str(&self.target_licence_uri), self.decided_at_unix, out)
295 }
296}
297
298#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
300#[serde(tag = "stage", rename_all = "snake_case")]
301pub enum ContributionLifecycleStage {
302 RequestAndAgreement(RequestAndAgreement),
303 ActivityAndResources(ActivityAndResources),
304 OutputOrService(OutputOrService),
305 SubmissionOrClaim(SubmissionOrClaim),
306 AcceptanceDecision(AcceptanceDecision),
307 Valuation(Valuation),
308 LifecycleObligation(LifecycleObligation),
309 SettlementAllocation(SettlementAllocation),
310 TransitionDecision(TransitionDecision),
311}
312
313impl ContributionLifecycleStage {
314 pub fn compile_to_quins(&self, out: &mut [NQuin]) -> usize {
316 match self {
317 Self::RequestAndAgreement(r) => r.compile_to_quins(out),
318 Self::ActivityAndResources(r) => r.compile_to_quins(out),
319 Self::OutputOrService(r) => r.compile_to_quins(out),
320 Self::SubmissionOrClaim(r) => r.compile_to_quins(out),
321 Self::AcceptanceDecision(r) => r.compile_to_quins(out),
322 Self::Valuation(r) => r.compile_to_quins(out),
323 Self::LifecycleObligation(r) => r.compile_to_quins(out),
324 Self::SettlementAllocation(r) => r.compile_to_quins(out),
325 Self::TransitionDecision(r) => r.compile_to_quins(out),
326 }
327 }
328}
329
330fn emit_stage_quins(id: &str, project_id: &str, rdf_type: &str, value_word: u64, at_unix: u32, out: &mut [NQuin]) -> usize {
331 let mut written = 0;
332 let (s, ctx) = (q_hash_str(id), q_hash_str(project_id));
333 let meta = SensitivityClass::Restricted.to_metadata_mask() | (at_unix as u64);
334 for (p, o) in [
335 (q_hash_str("http://www.w3.org/1999/02/22-rdf-syntax-ns#type"), q_hash_str(rdf_type)),
336 (q_hash_str("https://vocab.Burst.net.au/hro#stageValue"), value_word),
337 ] {
338 if written < out.len() {
339 out[written] = NQuin::new(s, p, o, ctx, meta);
340 written += 1;
341 }
342 }
343 written
344}
345
346pub fn derive_obligation_from_lifecycle(
349 obligation_id: impl Into<String>,
350 submission: &SubmissionOrClaim,
351 agreement: Option<&RequestAndAgreement>,
352 acceptance: Option<&AcceptanceDecision>,
353 valuation: Option<&Valuation>,
354 now_unix: u32,
355) -> Result<LifecycleObligation, String> {
356 if agreement.is_some_and(|ag| ag.compensation_class == CompensationClass::VoluntaryCommonsGift) {
357 return Err("voluntary commons gifts do not create payable obligations".to_string());
358 }
359 if acceptance.is_some_and(|a| a.outcome.is_accepted()) {
360 let val = valuation.ok_or_else(|| "accepted submission requires a Valuation before creating a LifecycleObligation".to_string())?;
361 let principal = val.total_valued_cents();
362 if principal <= 0 {
363 return Err("valuation must have positive total_valued_cents".to_string());
364 }
365 return Ok(LifecycleObligation {
366 id: obligation_id.into(),
367 project_id: submission.project_id.clone(),
368 beneficiary_did: submission.contributor_did.clone(),
369 agreement_id: submission.agreement_id.clone(),
370 acceptance_id: acceptance.map(|a| a.id.clone()),
371 valuation_id: Some(val.id.clone()),
372 principal_cents: principal,
373 settled_cents: 0,
374 outstanding_cents: principal,
375 status: ObligationStatus::Active,
376 waiver_terms: None,
377 waived_by_did: None,
378 created_at_unix: now_unix,
379 });
380 }
381 if let Some(ag) = agreement.filter(|a| a.is_commissioned_guarantee()) {
382 let billable_minutes = submission.claimed_effort_minutes.min(ag.max_authorised_effort_minutes);
383 let effort_cents = div_round_bankers((billable_minutes as i128) * (ag.rate_cents_per_hour as i128), 60);
384 let expense_cents = submission.claimed_expense_cents.max(0).min(ag.max_authorised_expense_cents.max(0));
385 let principal = effort_cents.saturating_add(expense_cents);
386 if principal > 0 {
387 return Ok(LifecycleObligation {
388 id: obligation_id.into(),
389 project_id: submission.project_id.clone(),
390 beneficiary_did: submission.contributor_did.clone(),
391 agreement_id: Some(ag.id.clone()),
392 acceptance_id: acceptance.map(|a| a.id.clone()),
393 valuation_id: valuation.map(|v| v.id.clone()),
394 principal_cents: principal,
395 settled_cents: 0,
396 outstanding_cents: principal,
397 status: ObligationStatus::Active,
398 waiver_terms: None,
399 waived_by_did: None,
400 created_at_unix: now_unix,
401 });
402 }
403 }
404 Err("unsolicited or non-commissioned activity cannot create a payable obligation without AcceptanceDecision and Valuation".to_string())
405}
406
407pub fn apply_settlements_and_recognition(
409 obligation: &LifecycleObligation,
410 allocations: &[SettlementAllocation],
411 _outputs_with_badges: &[OutputOrService],
412) -> LifecycleObligation {
413 let mut updated = obligation.clone();
414 if updated.status == ObligationStatus::Waived {
415 if updated.waiver_terms.as_deref().is_some_and(|t| !t.trim().is_empty())
416 && updated.waived_by_did.as_deref().is_some_and(|d| !d.trim().is_empty())
417 {
418 updated.outstanding_cents = 0;
419 return updated;
420 }
421 updated.status = ObligationStatus::Active;
422 }
423 let verified_paid_cents: i64 = allocations
424 .iter()
425 .filter(|a| a.obligation_id == obligation.id && a.beneficiary_did == obligation.beneficiary_did && a.has_verified_receipt())
426 .fold(0i64, |acc, a| acc.saturating_add(a.allocated_cents));
427 updated.settled_cents = verified_paid_cents.min(updated.principal_cents);
428 updated.outstanding_cents = (updated.principal_cents - updated.settled_cents).max(0);
429 if updated.status != ObligationStatus::Disputed {
430 updated.status = if updated.outstanding_cents == 0 {
431 ObligationStatus::Satisfied
432 } else if updated.settled_cents > 0 {
433 ObligationStatus::PartiallySettled
434 } else {
435 ObligationStatus::Active
436 };
437 }
438 updated
439}
440
441pub fn evaluate_transition_readiness(
443 decision: &TransitionDecision,
444 obligations: &[LifecycleObligation],
445 allocations: &[SettlementAllocation],
446) -> TransitionReadiness {
447 if !decision.steward_is_human || decision.authorised_steward_did.trim().is_empty() {
448 return TransitionReadiness::Failed { reason: "transition decision requires an authorised human steward DID".to_string() };
449 }
450 if !decision.dependencies_compatible {
451 return TransitionReadiness::Failed { reason: "incompatible dependency licences block transition".to_string() };
452 }
453 if decision.unresolved_material_challenges > 0 {
454 return TransitionReadiness::Held { reason: format!("{} unresolved material challenge(s) block transition", decision.unresolved_material_challenges) };
455 }
456 for ob in obligations {
457 let recomputed = apply_settlements_and_recognition(ob, allocations, &[]);
458 if recomputed.status == ObligationStatus::Disputed {
459 return TransitionReadiness::Held { reason: format!("obligation {} is disputed", ob.id) };
460 }
461 if recomputed.status != ObligationStatus::Waived && recomputed.outstanding_cents > 0 {
462 return TransitionReadiness::Held {
463 reason: format!(
464 "pool funded ({}) != contributor paid: obligation {} for {} has {} cents outstanding without verified beneficiary receipt",
465 decision.pool_funded_cents, ob.id, ob.beneficiary_did, recomputed.outstanding_cents
466 ),
467 };
468 }
469 }
470 TransitionReadiness::Satisfied
471}
472
473pub fn is_transition_ready(
475 decision: &TransitionDecision,
476 obligations: &[LifecycleObligation],
477 allocations: &[SettlementAllocation],
478) -> bool {
479 evaluate_transition_readiness(decision, obligations, allocations).is_ready()
480}
481
482#[cfg(test)]
483#[path = "contribution_lifecycle_tests.rs"]
484mod tests;