1use 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#[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#[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#[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#[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#[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#[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
180pub 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#[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
259pub 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#[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
322pub 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
349pub 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}