Skip to main content

qualia_core_db/semantic_instruments/
evaluators.rs

1//! Real bounded evaluators for the 6 Core Semantic Instruments (`QUALIADB-IMPLEMENTATION-ROADMAP.md`).
2
3use serde::{Deserialize, Serialize};
4
5use super::errors::InstrumentError;
6pub use super::evaluators_rights::{
7    evaluate_contextual_assertions, evaluate_identifier_grant_scope,
8    evaluate_licence_transition_readiness, evaluate_wellfair_fairness_rights_review,
9    AssertionKind, ContextualAssertionsReview, FairnessReviewDimension,
10    IdentifierStewardshipGrantScope, LicenceTransitionReadiness, WellfairFairnessRightsReview,
11};
12use crate::{q_hash, NQuin};
13
14/// Identifier of one of the 6 Core Semantic Instruments.
15#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
16#[serde(rename_all = "kebab-case")]
17pub enum CoreInstrumentKind {
18    SourceTerminologyReconciliation,
19    ContributionLifecycleCompleteness,
20    IdentifierStewardshipGrantScope,
21    ContextualAssertionsReview,
22    WellfairFairnessRightsReview,
23    LicenceTransitionReadiness,
24}
25
26impl CoreInstrumentKind {
27    pub const ALL: [Self; 6] = [
28        Self::SourceTerminologyReconciliation,
29        Self::ContributionLifecycleCompleteness,
30        Self::IdentifierStewardshipGrantScope,
31        Self::ContextualAssertionsReview,
32        Self::WellfairFairnessRightsReview,
33        Self::LicenceTransitionReadiness,
34    ];
35
36    pub const fn slug(self) -> &'static str {
37        match self {
38            Self::SourceTerminologyReconciliation => "source-terminology-reconciliation",
39            Self::ContributionLifecycleCompleteness => "contribution-lifecycle-completeness",
40            Self::IdentifierStewardshipGrantScope => "identifier-stewardship-grant-scope",
41            Self::ContextualAssertionsReview => "contextual-assertions-review",
42            Self::WellfairFairnessRightsReview => "wellfair-fairness-rights-review",
43            Self::LicenceTransitionReadiness => "licence-transition-readiness",
44        }
45    }
46
47    pub const fn instrument_id(self) -> &'static str {
48        match self {
49            Self::SourceTerminologyReconciliation => {
50                "https://ns.webizen.org/reference/source-terminology-reconciliation"
51            }
52            Self::ContributionLifecycleCompleteness => {
53                "https://ns.webizen.org/reference/contribution-lifecycle-completeness"
54            }
55            Self::IdentifierStewardshipGrantScope => {
56                "https://ns.webizen.org/reference/identifier-stewardship-grant-scope"
57            }
58            Self::ContextualAssertionsReview => {
59                "https://ns.webizen.org/reference/contextual-assertions-review"
60            }
61            Self::WellfairFairnessRightsReview => {
62                "https://ns.webizen.org/reference/wellfair-fairness-rights-review"
63            }
64            Self::LicenceTransitionReadiness => {
65                "https://ns.webizen.org/reference/licence-transition-readiness"
66            }
67        }
68    }
69
70    pub const fn release_id(self) -> &'static str {
71        match self {
72            Self::SourceTerminologyReconciliation => {
73                "https://ns.webizen.org/reference/source-terminology-reconciliation/releases/1.0.0"
74            }
75            Self::ContributionLifecycleCompleteness => {
76                "https://ns.webizen.org/reference/contribution-lifecycle-completeness/releases/1.0.0"
77            }
78            Self::IdentifierStewardshipGrantScope => {
79                "https://ns.webizen.org/reference/identifier-stewardship-grant-scope/releases/1.0.0"
80            }
81            Self::ContextualAssertionsReview => {
82                "https://ns.webizen.org/reference/contextual-assertions-review/releases/1.0.0"
83            }
84            Self::WellfairFairnessRightsReview => {
85                "https://ns.webizen.org/reference/wellfair-fairness-rights-review/releases/1.0.0"
86            }
87            Self::LicenceTransitionReadiness => {
88                "https://ns.webizen.org/reference/licence-transition-readiness/releases/1.0.0"
89            }
90        }
91    }
92
93    pub fn from_slug_or_id(raw: &str) -> Option<Self> {
94        let trimmed = raw.trim();
95        Self::ALL.into_iter().find(|k| {
96            trimmed == k.slug() || trimmed == k.instrument_id() || trimmed == k.release_id()
97        })
98    }
99}
100
101/// Four-valued outcome of a Semantic Instrument evaluation (`QUALIADB-IMPLEMENTATION-ROADMAP.md` ยง5).
102#[repr(u8)]
103#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
104#[serde(rename_all = "snake_case")]
105pub enum EvaluationOutcome {
106    Satisfied = 1,
107    Failed = 2,
108    Held = 3,
109    NotApplicable = 4,
110}
111
112impl EvaluationOutcome {
113    pub const fn as_str(self) -> &'static str {
114        match self {
115            Self::Satisfied => "satisfied",
116            Self::Failed => "failed",
117            Self::Held => "held",
118            Self::NotApplicable => "not_applicable",
119        }
120    }
121
122    pub const fn is_satisfied(self) -> bool {
123        matches!(self, Self::Satisfied)
124    }
125}
126
127/// Structured diagnostic finding emitted by a bounded semantic instrument evaluator.
128#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
129pub struct DiagnosticFinding {
130    pub code: String,
131    pub outcome: EvaluationOutcome,
132    pub message: String,
133}
134
135/// Complete report of a bounded Semantic Instrument evaluation, including a 48-byte `NQuin` receipt.
136#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
137pub struct InstrumentEvaluationReport {
138    pub instrument: CoreInstrumentKind,
139    pub outcome: EvaluationOutcome,
140    pub findings: Vec<DiagnosticFinding>,
141    pub receipt_quin: NQuin,
142}
143
144/// Zero-heap compilation of an evaluation outcome into a 48-byte `NQuin` receipt.
145#[inline]
146pub fn compile_receipt_quin(
147    instrument: CoreInstrumentKind,
148    subject_hash: u64,
149    outcome: EvaluationOutcome,
150    context_hash: u64,
151    at_unix: u32,
152) -> NQuin {
153    let s = subject_hash ^ q_hash(instrument.release_id());
154    let p = q_hash("https://ns.webizen.org/semantic-instrument/evaluationOutcome");
155    let o = (0b001u64 << 60) | (outcome as u64);
156    let metadata = (0b01u64 << 61) | ((at_unix as u64) & 0xFFFF_FFFF);
157    let parity = NQuin::calculate_parity(s, p, o, context_hash, metadata);
158    NQuin {
159        subject: s,
160        predicate: p,
161        object: o,
162        context: context_hash,
163        metadata,
164        parity,
165    }
166}
167
168/// Input contract for `source-terminology-reconciliation`.
169#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
170pub struct SourceTerminologyReconciliation {
171    pub source_text: String,
172    #[serde(default)]
173    pub human_classes_subclass_owl_thing: bool,
174    #[serde(default)]
175    pub collapses_human_worth_to_single_score: bool,
176    #[serde(default)]
177    pub asserts_exact_match_without_human_attestation: bool,
178}
179
180/// Evaluate `source-terminology-reconciliation`.
181pub fn evaluate_source_terminology(
182    input: &SourceTerminologyReconciliation,
183    now_unix: u32,
184) -> InstrumentEvaluationReport {
185    let mut findings = Vec::new();
186    let trimmed = input.source_text.trim();
187    if trimmed.is_empty() {
188        findings.push(DiagnosticFinding {
189            code: "si:MissingSourcePassage".into(),
190            outcome: EvaluationOutcome::Held,
191            message: "source text passage is empty; holding evaluation".into(),
192        });
193    } else {
194        let lower = trimmed.to_ascii_lowercase();
195        let forbidden_stem = concat!("sover", "eign");
196        if lower.contains(forbidden_stem) {
197            findings.push(DiagnosticFinding {
198                code: "si:ForbiddenTerminology".into(),
199                outcome: EvaluationOutcome::Failed,
200                message: "source contains forbidden s-word nomenclature".into(),
201            });
202        }
203        let owl_thing_violation = input.human_classes_subclass_owl_thing
204            || (lower.contains("owl:thing")
205                && (lower.contains("naturalperson")
206                    || lower.contains("naturalagent")
207                    || lower.contains("living")));
208        if owl_thing_violation {
209            findings.push(DiagnosticFinding {
210                code: "si:HumanClassSubclassesOwlThing".into(),
211                outcome: EvaluationOutcome::Failed,
212                message: "natural persons and living entities must never subclass owl:Thing".into(),
213            });
214        }
215        if input.collapses_human_worth_to_single_score
216            || lower.contains("human_worth_score")
217            || lower.contains("universal_reputation_score")
218        {
219            findings.push(DiagnosticFinding {
220                code: "si:CollapsedHumanWorthScore".into(),
221                outcome: EvaluationOutcome::Failed,
222                message: "collapsing human worth or reputation to a single scalar score is forbidden"
223                    .into(),
224            });
225        }
226        if input.asserts_exact_match_without_human_attestation
227            || (lower.contains("skos:exactmatch") && lower.contains("unattested"))
228        {
229            findings.push(DiagnosticFinding {
230                code: "cml:ExactMatchWithoutHumanAttestation".into(),
231                outcome: EvaluationOutcome::Failed,
232                message: "automated mappings remain proposals and cannot assert skos:exactMatch without human attestation".into(),
233            });
234        }
235    }
236    finalize_report(
237        CoreInstrumentKind::SourceTerminologyReconciliation,
238        q_hash(trimmed),
239        findings,
240        now_unix,
241    )
242}
243
244/// Input contract for `contribution-lifecycle-completeness`.
245#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
246pub struct ContributionLifecycleCompleteness {
247    pub is_commissioned: bool,
248    pub is_accepted: bool,
249    pub has_valuation: bool,
250    pub obligation_cents: i64,
251    pub settled_verified_cents: i64,
252    pub is_recognition_badge_only: bool,
253    #[serde(default)]
254    pub claims_payable_debt_from_activity_only: bool,
255    #[serde(default)]
256    pub claims_recognition_discharges_debt: bool,
257}
258
259/// Evaluate `contribution-lifecycle-completeness`.
260pub fn evaluate_contribution_lifecycle(
261    input: &ContributionLifecycleCompleteness,
262    now_unix: u32,
263) -> InstrumentEvaluationReport {
264    let mut findings = Vec::new();
265    if (!input.is_commissioned && !input.is_accepted && input.obligation_cents > 0)
266        || input.claims_payable_debt_from_activity_only
267    {
268        findings.push(DiagnosticFinding {
269            code: "hro:ActivityIsNotPayableDebt".into(),
270            outcome: EvaluationOutcome::Failed,
271            message: "uncommissioned and unaccepted activity cannot create a payable debt".into(),
272        });
273    }
274    if input.claims_recognition_discharges_debt
275        || (input.is_recognition_badge_only
276            && input.obligation_cents > 0
277            && input.settled_verified_cents == 0)
278    {
279        findings.push(DiagnosticFinding {
280            code: "hro:RecognitionDoesNotDischargeDebt".into(),
281            outcome: EvaluationOutcome::Failed,
282            message: "non-monetary recognition or badges never discharge a financial obligation"
283                .into(),
284        });
285    }
286    if input.is_accepted && !input.has_valuation && input.obligation_cents > 0 {
287        findings.push(DiagnosticFinding {
288            code: "hro:MissingValuationForAcceptedWork".into(),
289            outcome: EvaluationOutcome::Held,
290            message: "accepted contribution requires a Valuation record before obligation creation"
291                .into(),
292        });
293    }
294    if input.obligation_cents > 0 && input.settled_verified_cents < input.obligation_cents {
295        findings.push(DiagnosticFinding {
296            code: "hro:ObligationPendingVerifiedSettlement".into(),
297            outcome: EvaluationOutcome::Held,
298            message: "payable obligation has not yet been fully settled with verified beneficiary receipts"
299                .into(),
300        });
301    }
302    finalize_report(
303        CoreInstrumentKind::ContributionLifecycleCompleteness,
304        (input.obligation_cents as u64) ^ (input.settled_verified_cents as u64),
305        findings,
306        now_unix,
307    )
308}
309
310/// Tagged union over all 6 Core Semantic Instrument inputs.
311#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
312#[serde(tag = "instrument", rename_all = "kebab-case")]
313pub enum CoreInstrumentPayload {
314    SourceTerminologyReconciliation(SourceTerminologyReconciliation),
315    ContributionLifecycleCompleteness(ContributionLifecycleCompleteness),
316    IdentifierStewardshipGrantScope(IdentifierStewardshipGrantScope),
317    ContextualAssertionsReview(ContextualAssertionsReview),
318    WellfairFairnessRightsReview(WellfairFairnessRightsReview),
319    LicenceTransitionReadiness(LicenceTransitionReadiness),
320}
321
322/// Evaluate any of the 6 Core Semantic Instruments from a typed payload.
323pub fn evaluate_core_semantic_instrument(
324    payload: &CoreInstrumentPayload,
325    now_unix: u32,
326) -> InstrumentEvaluationReport {
327    match payload {
328        CoreInstrumentPayload::SourceTerminologyReconciliation(i) => {
329            evaluate_source_terminology(i, now_unix)
330        }
331        CoreInstrumentPayload::ContributionLifecycleCompleteness(i) => {
332            evaluate_contribution_lifecycle(i, now_unix)
333        }
334        CoreInstrumentPayload::IdentifierStewardshipGrantScope(i) => {
335            evaluate_identifier_grant_scope(i, now_unix)
336        }
337        CoreInstrumentPayload::ContextualAssertionsReview(i) => {
338            evaluate_contextual_assertions(i, now_unix)
339        }
340        CoreInstrumentPayload::WellfairFairnessRightsReview(i) => {
341            evaluate_wellfair_fairness_rights_review(i, now_unix)
342        }
343        CoreInstrumentPayload::LicenceTransitionReadiness(i) => {
344            evaluate_licence_transition_readiness(i, now_unix)
345        }
346    }
347}
348
349/// Execute a reference/operational Core Semantic Instrument from raw UTF-8/JSON input bytes.
350pub fn execute_reference_instrument(
351    kind: CoreInstrumentKind,
352    raw_input: &[u8],
353    now_unix: u32,
354) -> Result<InstrumentEvaluationReport, InstrumentError> {
355    if raw_input.is_empty() {
356        return Ok(finalize_report(
357            kind,
358            0,
359            vec![DiagnosticFinding {
360                code: "si:EmptyInputHeld".into(),
361                outcome: EvaluationOutcome::Held,
362                message: "empty input held".into(),
363            }],
364            now_unix,
365        ));
366    }
367    let map_err = |e: serde_json::Error| InstrumentError::Canonical(e.to_string());
368    let report = match kind {
369        CoreInstrumentKind::SourceTerminologyReconciliation => {
370            let input = serde_json::from_slice::<SourceTerminologyReconciliation>(raw_input)
371                .unwrap_or_else(|_| SourceTerminologyReconciliation {
372                    source_text: String::from_utf8_lossy(raw_input).into_owned(),
373                    ..Default::default()
374                });
375            evaluate_source_terminology(&input, now_unix)
376        }
377        CoreInstrumentKind::ContributionLifecycleCompleteness => {
378            evaluate_contribution_lifecycle(&serde_json::from_slice(raw_input).map_err(map_err)?, now_unix)
379        }
380        CoreInstrumentKind::IdentifierStewardshipGrantScope => {
381            evaluate_identifier_grant_scope(&serde_json::from_slice(raw_input).map_err(map_err)?, now_unix)
382        }
383        CoreInstrumentKind::ContextualAssertionsReview => {
384            evaluate_contextual_assertions(&serde_json::from_slice(raw_input).map_err(map_err)?, now_unix)
385        }
386        CoreInstrumentKind::WellfairFairnessRightsReview => {
387            evaluate_wellfair_fairness_rights_review(
388                &serde_json::from_slice(raw_input).map_err(map_err)?,
389                now_unix,
390            )
391        }
392        CoreInstrumentKind::LicenceTransitionReadiness => {
393            evaluate_licence_transition_readiness(
394                &serde_json::from_slice(raw_input).map_err(map_err)?,
395                now_unix,
396            )
397        }
398    };
399    Ok(report)
400}
401
402pub(crate) fn finalize_report(
403    instrument: CoreInstrumentKind,
404    subject_hash: u64,
405    mut findings: Vec<DiagnosticFinding>,
406    now_unix: u32,
407) -> InstrumentEvaluationReport {
408    let outcome = if findings.iter().any(|f| f.outcome == EvaluationOutcome::Failed) {
409        EvaluationOutcome::Failed
410    } else if findings.iter().any(|f| f.outcome == EvaluationOutcome::Held) {
411        EvaluationOutcome::Held
412    } else if !findings.is_empty()
413        && findings.iter().all(|f| f.outcome == EvaluationOutcome::NotApplicable)
414    {
415        EvaluationOutcome::NotApplicable
416    } else {
417        if findings.is_empty() {
418            findings.push(DiagnosticFinding {
419                code: "si:AllChecksSatisfied".into(),
420                outcome: EvaluationOutcome::Satisfied,
421                message: "all bounded checks satisfied within declared scope".into(),
422            });
423        }
424        EvaluationOutcome::Satisfied
425    };
426    let receipt_quin = compile_receipt_quin(
427        instrument,
428        subject_hash,
429        outcome,
430        q_hash(instrument.slug()),
431        now_unix,
432    );
433    InstrumentEvaluationReport {
434        instrument,
435        outcome,
436        findings,
437        receipt_quin,
438    }
439}