Skip to main content

qualia_cooperative_core/
contribution_lifecycle.rs

1//! Nine-Stage Contribution, Valuation, Obligation, and Licence-Transition Lifecycle (`CONTRIBUTION-LIFECYCLE.md`).
2
3use serde::{Deserialize, Serialize};
4use crate::finance::div_round_bankers;
5use crate::record::{q_hash_str, InstantBridge, NQuin, SensitivityClass};
6
7/// Governance authority under which work was requested or initiated (Stage 1).
8#[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/// Compensation model agreed prior to or at acceptance (Stage 1).
15#[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/// Stage 1 — Request & Agreement record.
22#[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    /// True when the agreement was commissioned with guaranteed payment for authorised effort/expense.
32    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    /// Zero-heap compilation into 48-byte `NQuin`s.
39    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/// Stage 2 — Activity & Resources record (logs effort/expense; never directly creates payable debt).
45#[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    /// Zero-heap compilation into 48-byte `NQuin`s.
62    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/// Stage 3 — Output or Service produced by activity.
68#[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    /// Zero-heap compilation into 48-byte `NQuin`s.
82    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/// Stage 4 — Submission or Claim for review/compensation.
88#[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    /// Zero-heap compilation into 48-byte `NQuin`s.
103    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/// Outcome of a Stage 5 `AcceptanceDecision`.
109#[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
120/// Type alias for callers referring to `AcceptanceStatus`.
121pub type AcceptanceStatus = AcceptanceOutcome;
122
123impl AcceptanceOutcome {
124    /// True if the deliverable was accepted (unconditionally or with conditions).
125    pub const fn is_accepted(&self) -> bool {
126        matches!(self, Self::Accepted | Self::AcceptedWithConditions)
127    }
128}
129
130/// Stage 5 — Acceptance Decision record.
131#[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    /// Zero-heap compilation into 48-byte `NQuin`s.
153    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/// Stage 6 — Valuation record.
159#[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    /// Total valued obligation in integer minor units (cents) using banker's rounding on capital return.
175    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    /// Zero-heap compilation into 48-byte `NQuin`s.
185    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/// Status of a Stage 7 `LifecycleObligation`.
191#[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/// Stage 7 — Lifecycle Obligation record.
202#[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    /// Zero-heap compilation into 48-byte `NQuin`s.
228    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/// Stage 8 — Settlement Allocation record (maps pool funds to a specific beneficiary obligation).
234#[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    /// True only when a positive allocation is backed by a verified beneficiary receipt hash.
249    pub const fn has_verified_receipt(&self) -> bool {
250        self.allocated_cents > 0 && self.beneficiary_receipt_hash.is_some()
251    }
252
253    /// Zero-heap compilation into 48-byte `NQuin`s.
254    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/// Readiness evaluation status for Stage 9 (`TransitionDecision`).
260#[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    /// True only when all transition preconditions are satisfied.
270    pub const fn is_ready(&self) -> bool {
271        matches!(self, Self::Satisfied)
272    }
273}
274
275/// Stage 9 — Licence Transition Decision record (requires an authorised human steward DID).
276#[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    /// Zero-heap compilation into 48-byte `NQuin`s.
293    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/// Unified enum over all 9 contribution lifecycle stages.
299#[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    /// Zero-heap compilation of any lifecycle stage into 48-byte `NQuin`s.
315    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
346/// Rule 1 (`Activity != Payable Debt`): Derive a `LifecycleObligation` from a submission,
347/// optional agreement, acceptance decision, and optional valuation.
348pub 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
407/// Rule 3 (`Non-Monetary Recognition Never Discharges Debt`): Recompute an obligation's balance.
408pub 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
441/// Rule 2 (`Pool Funded != Contributor Paid`): Evaluate whether a project is ready for licence transition.
442pub 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
473/// Boolean helper returning `true` iff [`evaluate_transition_readiness`] returns `Satisfied`.
474pub 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;