Skip to main content

qualia_cooperative_core/authoring/
records.rs

1use super::{policy::text, *};
2use crate::projects::{Contribution, ContributionPrivacy};
3use serde::{Deserialize, Serialize};
4
5/// Actual compensation is independent of role/permission. A receipt reference
6/// is retained, not verified or converted into money by this authoring slice.
7#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
8#[serde(rename_all = "snake_case")]
9pub enum WorkStatus {
10    Unknown,
11    Unpaid { evidence_ref: String },
12    SelfFunded { evidence_ref: String },
13    PartiallyCompensated { evidence_ref: String },
14    Compensated { evidence_ref: String },
15    Disputed { evidence_ref: String },
16}
17
18impl WorkStatus {
19    pub(super) fn evidence(&self) -> Option<&str> {
20        match self {
21            Self::Unknown => None,
22            Self::Unpaid { evidence_ref }
23            | Self::SelfFunded { evidence_ref }
24            | Self::PartiallyCompensated { evidence_ref }
25            | Self::Compensated { evidence_ref }
26            | Self::Disputed { evidence_ref } => Some(evidence_ref),
27        }
28    }
29}
30
31/// Canonical contribution plus exact editable source binding. No valuation,
32/// payment, permission, agreement adoption or human acceptance is implied.
33#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
34#[serde(deny_unknown_fields)]
35pub struct ContributionRecord {
36    pub contribution: Contribution,
37    pub target: DocumentRevision,
38    pub contributor_subject: String,
39    pub principal_kind: PrincipalKind,
40    pub authentication_ref: String,
41    pub identifier_association: IdentifierAssociationEvidence,
42    pub membership_id: String,
43    pub admission_ref: String,
44    pub authority_generation: u64,
45    pub work_status: WorkStatus,
46}
47
48#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
49#[serde(rename_all = "snake_case")]
50pub enum ReviewDecision {
51    Accepted,
52    ChangesRequested,
53    Rejected,
54}
55
56/// An actual identified reviewer's decision about this exact source state.
57/// `SoftwareAgent` review cannot be presented as a human acceptance gate.
58#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
59#[serde(deny_unknown_fields)]
60pub struct ReviewRecord {
61    pub id: String,
62    pub target: DocumentRevision,
63    pub reviewer_subject: String,
64    pub reviewer_identifier: String,
65    pub principal_kind: PrincipalKind,
66    pub authentication_ref: String,
67    pub identifier_association: IdentifierAssociationEvidence,
68    pub membership_id: String,
69    pub admission_ref: String,
70    pub review_grant_id: String,
71    pub review_admission_ref: String,
72    pub authority_generation: u64,
73    pub occurred_at_unix: u64,
74    pub decision: ReviewDecision,
75    pub rationale: String,
76    /// The review act, not a generated draft or unverified signing display.
77    pub decision_evidence_ref: String,
78}
79
80/// Saved evidence of the exact association used; reopening it grants nothing.
81#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
82#[serde(deny_unknown_fields)]
83pub struct IdentifierAssociationEvidence {
84    pub value: String,
85    pub scheme: String,
86    pub issuer: String,
87    pub project_id: String,
88    pub evidence_ref: String,
89    pub valid_from_unix: u64,
90    pub valid_until_unix: u64,
91}
92
93impl From<&QualifiedIdentifier<'_>> for IdentifierAssociationEvidence {
94    fn from(identifier: &QualifiedIdentifier<'_>) -> Self {
95        Self {
96            value: identifier.value.into(),
97            scheme: identifier.scheme.into(),
98            issuer: identifier.issuer.into(),
99            project_id: identifier.project_id.into(),
100            evidence_ref: identifier.evidence_ref.into(),
101            valid_from_unix: identifier.valid_from_unix,
102            valid_until_unix: identifier.valid_until_unix,
103        }
104    }
105}
106
107pub(super) fn reserve_record<'a>(
108    values: impl IntoIterator<Item = &'a str>,
109    limits: AuthoringLimits,
110) -> Result<(), AuthoringError> {
111    // JSON can escape a byte into six bytes. Include a fixed metadata reserve;
112    // check BEFORE any owned output allocation. Runtime encoding must also use
113    // a byte-limited writer because these are logical records, not a codec.
114    let mut bytes = 2048usize;
115    for value in values {
116        text(value, limits)?;
117        bytes = value
118            .len()
119            .checked_mul(6)
120            .and_then(|n| bytes.checked_add(n))
121            .ok_or(AuthoringError::BudgetExceeded)?;
122    }
123    if bytes > limits.max_record_bytes {
124        return Err(AuthoringError::BudgetExceeded);
125    }
126    Ok(())
127}
128
129impl AuthoringPermit<'_> {
130    /// Call only after authoring succeeded, while the host's transaction still
131    /// owns this current revision. The owner persists/deduplicates this record
132    /// atomically with its source journal. Caller cannot attribute another author.
133    pub fn contribution_record(
134        self,
135        id: &str,
136        description: &str,
137        effort_minutes: u32,
138        work_status: WorkStatus,
139        predecessor: Option<&ContributionRecord>,
140    ) -> Result<ContributionRecord, AuthoringError> {
141        if self.action != AuthoringAction::ContributionRecord {
142            return Err(AuthoringError::WrongAction);
143        }
144        let target = self.view.current_document;
145        if target.author_subject.as_deref() != Some(self.principal.subject) {
146            return Err(AuthoringError::InvalidBinding);
147        }
148        let member = self.membership.membership;
149        let occurred_at_unix =
150            u32::try_from(self.view.now_unix).map_err(|_| AuthoringError::UnsupportedTime)?;
151        let values = [
152            id,
153            description,
154            target.project_id.as_str(),
155            target.project_id.as_str(), // canonical contribution and source binding
156            target.document_id.as_str(),
157            target.source_id.as_str(),
158            self.principal.subject,
159            self.principal.subject, // contributor referent and target author
160            self.principal.authentication_ref,
161            member.member_did.as_str(),
162            member.id.as_str(),
163            self.membership.admission_ref,
164            self.identifier.value,
165            self.identifier.scheme,
166            self.identifier.issuer,
167            self.identifier.project_id,
168            self.identifier.evidence_ref,
169        ];
170        if let Some(previous) = predecessor {
171            if previous.contribution.project_id != target.project_id
172                || previous.contributor_subject != self.principal.subject
173                || previous.contribution.contributor_did != member.member_did
174                || previous.contribution.id == id
175            {
176                return Err(AuthoringError::InvalidBinding);
177            }
178        }
179        reserve_record(
180            values
181                .into_iter()
182                .chain(work_status.evidence())
183                .chain(predecessor.map(|p| p.contribution.id.as_str())),
184            self.view.limits,
185        )?;
186        Ok(ContributionRecord {
187            contribution: Contribution {
188                id: id.into(),
189                project_id: target.project_id.clone(),
190                contributor_did: member.member_did.clone(),
191                description: description.into(),
192                effort_minutes,
193                // This API records effort only. No capital or monetary amount
194                // is inferred, and no mixed-unit obligation score is evaluated.
195                capital_cents: 0,
196                roi_multiplier: 1.0,
197                privacy_level: ContributionPrivacy::Private,
198                occurred_at_unix,
199                occurred_at_instant: None,
200                predecessor_id: predecessor.map(|p| p.contribution.id.clone()),
201            },
202            target: target.clone(),
203            contributor_subject: self.principal.subject.into(),
204            principal_kind: self.principal.kind,
205            authentication_ref: self.principal.authentication_ref.into(),
206            identifier_association: self.identifier.into(),
207            membership_id: member.id.clone(),
208            admission_ref: self.membership.admission_ref.into(),
209            authority_generation: self.view.generation,
210            work_status,
211        })
212    }
213
214    pub fn review_record(
215        self,
216        id: &str,
217        decision: ReviewDecision,
218        rationale: &str,
219        decision_evidence_ref: &str,
220    ) -> Result<ReviewRecord, AuthoringError> {
221        if self.action != AuthoringAction::ReviewDecision {
222            return Err(AuthoringError::WrongAction);
223        }
224        let grant = self.review_grant.ok_or(AuthoringError::ReviewDenied)?;
225        let member = self.membership.membership;
226        let target = self.view.current_document;
227        reserve_record(
228            [
229                id,
230                rationale,
231                decision_evidence_ref,
232                target.project_id.as_str(),
233                target.document_id.as_str(),
234                target.source_id.as_str(),
235                target
236                    .author_subject
237                    .as_deref()
238                    .ok_or(AuthoringError::ReviewDenied)?,
239                self.principal.subject,
240                self.principal.authentication_ref,
241                member.member_did.as_str(),
242                member.id.as_str(),
243                self.membership.admission_ref,
244                grant.id,
245                grant.admission_ref,
246                self.identifier.value,
247                self.identifier.scheme,
248                self.identifier.issuer,
249                self.identifier.project_id,
250                self.identifier.evidence_ref,
251            ],
252            self.view.limits,
253        )?;
254        Ok(ReviewRecord {
255            id: id.into(),
256            target: target.clone(),
257            reviewer_subject: self.principal.subject.into(),
258            reviewer_identifier: member.member_did.clone(),
259            principal_kind: self.principal.kind,
260            authentication_ref: self.principal.authentication_ref.into(),
261            identifier_association: self.identifier.into(),
262            membership_id: member.id.clone(),
263            admission_ref: self.membership.admission_ref.into(),
264            review_grant_id: grant.id.into(),
265            review_admission_ref: grant.admission_ref.into(),
266            authority_generation: self.view.generation,
267            occurred_at_unix: self.view.now_unix,
268            decision,
269            rationale: rationale.into(),
270            decision_evidence_ref: decision_evidence_ref.into(),
271        })
272    }
273}