Skip to main content

qualia_core_db/semantic_instruments/
reference.rs

1//! Labelled **Reference** packs (`si:Reference`) and the 6 Core Semantic Instruments.
2//! Not Host IDs; bounded evaluators live in [`super::evaluators`].
3
4use super::category::ContentCategory;
5use super::errors::InstrumentError;
6use super::manifest::{InstrumentManifest, COLLECTABLE_FORMAT_VERSION};
7use super::package::{build_collectable, CollectableParts};
8use super::visual::{demo_badge_10d, VISUAL_MEDIA_TYPE};
9
10const UNIT_N3: &str =
11    include_str!("../../../../core-ontologies/fixtures/semantic-instruments/positive-small.n3");
12
13/// Training sum of declared 0–3 items. Not diagnosis, not a ClinicalRisk kernel.
14const WELLBEING_N3: &str = "\
15@prefix si: <https://ns.webizen.org/semantic-instrument/> .\n\
16@prefix cml: <https://ns.webcivics.net/cml/> .\n\
17ex:wellbeing-training a si:SemanticInstrument ;\n\
18    si:name \"Wellbeing training (reference pack)\" ;\n\
19    si:contentCategory si:Reference ;\n\
20    si:prohibitedInterpretation \"diagnosis\" ;\n\
21    si:entryPoint ex:wellbeing-assess ;\n\
22    si:honestyPolicy ex:wellbeing-honesty .\n\
23ex:wellbeing-assess a si:EntryPoint ;\n\
24    si:entryPointName \"assess\" ;\n\
25    si:logicApplication ex:wellbeing-logic .\n\
26ex:wellbeing-logic a cml:LogicApplication ;\n\
27    cml:logicSummary \"Sum declared items each in 0-3. Training only. Not diagnosis.\" .\n\
28ex:wellbeing-honesty a si:HonestyPolicy ;\n\
29    si:resultKind \"training-claim\" ;\n\
30    si:requiredNotice \"Reference pack. Training/demo only.\" .\n\
31ex:item-scale a si:DeclaredScale ;\n\
32    si:minInclusive \"0\" ;\n\
33    si:maxInclusive \"3\" .\n";
34
35/// Fictional training percentage of a declared number. Not professional advice.
36const TAX_N3: &str = "\
37@prefix si: <https://ns.webizen.org/semantic-instrument/> .\n\
38@prefix cml: <https://ns.webcivics.net/cml/> .\n\
39ex:tax-training a si:SemanticInstrument ;\n\
40    si:name \"Tax training (reference pack)\" ;\n\
41    si:contentCategory si:Reference ;\n\
42    si:prohibitedInterpretation \"professional-advice\" ;\n\
43    si:entryPoint ex:tax-assess ;\n\
44    si:honestyPolicy ex:tax-honesty .\n\
45ex:tax-assess a si:EntryPoint ;\n\
46    si:entryPointName \"assess\" ;\n\
47    si:logicApplication ex:tax-logic .\n\
48ex:tax-logic a cml:LogicApplication ;\n\
49    cml:logicSummary \"Fictional training percentage of a declared number.\" .\n\
50ex:tax-honesty a si:HonestyPolicy ;\n\
51    si:resultKind \"training-claim\" ;\n\
52    si:requiredNotice \"Reference pack. Fictional tax-training example.\" .\n\
53ex:tax-rate a si:DeclaredPercentage ;\n\
54    si:exampleRate \"0.10\" .\n";
55
56const CORE_INSTRUMENT_N3: &str = "\
57@prefix si: <https://ns.webizen.org/semantic-instrument/> .\n\
58@prefix cml: <https://ns.webcivics.net/cml/> .\n\
59ex:core-instrument a si:SemanticInstrument ;\n\
60    si:contentCategory si:Reference ;\n\
61    si:entryPoint ex:core-assess ;\n\
62    si:honestyPolicy ex:core-honesty .\n\
63ex:core-assess a si:EntryPoint ;\n\
64    si:entryPointName \"assess\" ;\n\
65    si:logicApplication ex:core-logic .\n\
66ex:core-logic a cml:LogicApplication ;\n\
67    cml:logicSummary \"Bounded core semantic instrument evaluator.\" .\n\
68ex:core-honesty a si:HonestyPolicy ;\n\
69    si:resultKind \"reference-claim\" ;\n\
70    si:requiredNotice \"Reference pack. Bounded semantic instrument review.\" .\n";
71
72const NOTICE_UNITS: &str = "Reference pack. Units conformance fixture. Not operational.";
73const NOTICE_WELLBEING: &str =
74    "Reference pack. Training/demo only. Not diagnosis, not a ClinicalRisk kernel, not operational advice.";
75const NOTICE_TAX: &str =
76    "Reference pack. Fictional tax-training example. Not professional tax advice.";
77const NOTICE_CORE: &str =
78    "Reference pack. Bounded semantic instrument review. Does not replace human adjudication.";
79
80/// One labelled reference seed. Same shape as [`super::demo::DemoSeed`].
81#[derive(Debug, Clone, Copy)]
82pub struct ReferenceSeed {
83    pub slug: &'static str,
84    pub instrument_id: &'static str,
85    pub release_id: &'static str,
86    pub name: &'static str,
87    pub purpose: &'static str,
88    pub domain: &'static str,
89    pub entry_point: &'static str,
90    pub definition_n3: &'static str,
91    pub honesty_notice: &'static str,
92    pub prohibited_interpretation: &'static str,
93}
94
95/// Built-in reference catalogue. Order is deterministic.
96pub fn reference_catalog() -> &'static [ReferenceSeed] {
97    &[
98        ReferenceSeed {
99            slug: "simple-units",
100            instrument_id: "https://ns.webizen.org/reference/simple-units",
101            release_id: "https://ns.webizen.org/reference/simple-units/releases/1.0.0",
102            name: "Unit conversion (reference pack)",
103            purpose: "conformance-reference",
104            domain: "https://ns.webizen.org/reference/concepts/units",
105            entry_point: "assess",
106            definition_n3: UNIT_N3,
107            honesty_notice: NOTICE_UNITS,
108            prohibited_interpretation: "operational-use",
109        },
110        ReferenceSeed {
111            slug: "wellbeing-training",
112            instrument_id: "https://ns.webizen.org/reference/wellbeing-training",
113            release_id: "https://ns.webizen.org/reference/wellbeing-training/releases/1.0.0",
114            name: "Wellbeing training (reference pack)",
115            purpose: "labelled-training-sum",
116            domain: "https://ns.webizen.org/reference/concepts/wellbeing-training",
117            entry_point: "assess",
118            definition_n3: WELLBEING_N3,
119            honesty_notice: NOTICE_WELLBEING,
120            prohibited_interpretation: "diagnosis",
121        },
122        ReferenceSeed {
123            slug: "tax-training",
124            instrument_id: "https://ns.webizen.org/reference/tax-training",
125            release_id: "https://ns.webizen.org/reference/tax-training/releases/1.0.0",
126            name: "Tax training (reference pack)",
127            purpose: "fictional-tax-training",
128            domain: "https://ns.webizen.org/reference/concepts/tax-training",
129            entry_point: "assess",
130            definition_n3: TAX_N3,
131            honesty_notice: NOTICE_TAX,
132            prohibited_interpretation: "professional-advice",
133        },
134    ]
135}
136
137/// The 6 Core Semantic Instruments defined in `QUALIADB-IMPLEMENTATION-ROADMAP.md` §5.
138pub fn core_instrument_catalog() -> &'static [ReferenceSeed] {
139    &[
140        ReferenceSeed {
141            slug: "source-terminology-reconciliation",
142            instrument_id: "https://ns.webizen.org/reference/source-terminology-reconciliation",
143            release_id: "https://ns.webizen.org/reference/source-terminology-reconciliation/releases/1.0.0",
144            name: "Source Terminology Reconciliation",
145            purpose: "terminology-reconciliation",
146            domain: "https://ns.webizen.org/reference/concepts/terminology",
147            entry_point: "assess",
148            definition_n3: CORE_INSTRUMENT_N3,
149            honesty_notice: NOTICE_CORE,
150            prohibited_interpretation: "automated-exact-match-without-human-attestation",
151        },
152        ReferenceSeed {
153            slug: "contribution-lifecycle-completeness",
154            instrument_id: "https://ns.webizen.org/reference/contribution-lifecycle-completeness",
155            release_id: "https://ns.webizen.org/reference/contribution-lifecycle-completeness/releases/1.0.0",
156            name: "Contribution Lifecycle Completeness",
157            purpose: "contribution-lifecycle-audit",
158            domain: "https://ns.webizen.org/reference/concepts/contribution-lifecycle",
159            entry_point: "assess",
160            definition_n3: CORE_INSTRUMENT_N3,
161            honesty_notice: NOTICE_CORE,
162            prohibited_interpretation: "activity-equals-payable-debt",
163        },
164        ReferenceSeed {
165            slug: "identifier-stewardship-grant-scope",
166            instrument_id: "https://ns.webizen.org/reference/identifier-stewardship-grant-scope",
167            release_id: "https://ns.webizen.org/reference/identifier-stewardship-grant-scope/releases/1.0.0",
168            name: "Identifier Stewardship & Grant Scope",
169            purpose: "identifier-grant-scope-audit",
170            domain: "https://ns.webizen.org/reference/concepts/identifier-stewardship",
171            entry_point: "assess",
172            definition_n3: CORE_INSTRUMENT_N3,
173            honesty_notice: NOTICE_CORE,
174            prohibited_interpretation: "unbounded-cross-context-disclosure",
175        },
176        ReferenceSeed {
177            slug: "contextual-assertions-review",
178            instrument_id: "https://ns.webizen.org/reference/contextual-assertions-review",
179            release_id: "https://ns.webizen.org/reference/contextual-assertions-review/releases/1.0.0",
180            name: "Contextual Assertions Review",
181            purpose: "epistemic-assertion-review",
182            domain: "https://ns.webizen.org/reference/concepts/contextual-assertions",
183            entry_point: "assess",
184            definition_n3: CORE_INSTRUMENT_N3,
185            honesty_notice: NOTICE_CORE,
186            prohibited_interpretation: "universal-reputation-score",
187        },
188        ReferenceSeed {
189            slug: "wellfair-fairness-rights-review",
190            instrument_id: "https://ns.webizen.org/reference/wellfair-fairness-rights-review",
191            release_id: "https://ns.webizen.org/reference/wellfair-fairness-rights-review/releases/1.0.0",
192            name: "Wellfair Fairness & Rights Review",
193            purpose: "six-dimension-fairness-rights-review",
194            domain: "https://ns.webizen.org/reference/concepts/wellfair-review",
195            entry_point: "assess",
196            definition_n3: CORE_INSTRUMENT_N3,
197            honesty_notice: NOTICE_CORE,
198            prohibited_interpretation: "single-scalar-fairness-score",
199        },
200        ReferenceSeed {
201            slug: "licence-transition-readiness",
202            instrument_id: "https://ns.webizen.org/reference/licence-transition-readiness",
203            release_id: "https://ns.webizen.org/reference/licence-transition-readiness/releases/1.0.0",
204            name: "Licence Transition Readiness",
205            purpose: "licence-transition-readiness-gate",
206            domain: "https://ns.webizen.org/reference/concepts/licence-transition",
207            entry_point: "assess",
208            definition_n3: CORE_INSTRUMENT_N3,
209            honesty_notice: NOTICE_CORE,
210            prohibited_interpretation: "pool-funded-equals-contributor-paid",
211        },
212    ]
213}
214
215/// Core instrument seed by slug.
216pub fn core_instrument_by_slug(slug: &str) -> Option<&'static ReferenceSeed> {
217    core_instrument_catalog().iter().find(|s| s.slug == slug)
218}
219
220/// Reference by slug (checks both the 3 reference seeds and the 6 Core Semantic Instruments).
221pub fn reference_by_slug(slug: &str) -> Option<&'static ReferenceSeed> {
222    reference_catalog()
223        .iter()
224        .find(|s| s.slug == slug)
225        .or_else(|| core_instrument_by_slug(slug))
226}
227
228fn manifest_for(seed: &ReferenceSeed) -> InstrumentManifest {
229    InstrumentManifest {
230        format_version: COLLECTABLE_FORMAT_VERSION.into(),
231        instrument_id: seed.instrument_id.into(),
232        release_id: seed.release_id.into(),
233        version: "1.0.0".into(),
234        name: seed.name.into(),
235        purpose: seed.purpose.into(),
236        content_category: ContentCategory::Reference,
237        prohibited_interpretation: seed.prohibited_interpretation.into(),
238        domain: seed.domain.into(),
239        ontology_reference: "https://ns.webizen.org/semantic-instrument/".into(),
240        entry_point: seed.entry_point.into(),
241        citation: "https://ns.webizen.org/reference/citations/seed-catalogue".into(),
242        honesty_notice: seed.honesty_notice.into(),
243        incomplete_input: "held".into(),
244        result_kind: "reference-claim".into(),
245        licence: "https://spdx.org/licenses/CC-BY-4.0.html".into(),
246        authored_by: "did:webizen:agent:reference-seed".into(),
247        accessible_text: seed.name.into(),
248        visual_media_type: VISUAL_MEDIA_TYPE.into(),
249        content_digest: String::new(),
250        extra: {
251            let mut extra = std::collections::BTreeMap::new();
252            extra.insert("slug".into(), serde_json::json!(seed.slug));
253            extra.insert("catalog".into(), serde_json::json!("si:Reference"));
254            extra
255        },
256    }
257}
258
259#[cfg(not(target_arch = "wasm32"))]
260fn small_q42_from_n3(n3: &str) -> Result<Vec<u8>, InstrumentError> {
261    use crate::modalities::logic::n3_parser::{N3Event, N3Parser, Term};
262    use crate::q42::q42_volume::write_sorted_quins_volume;
263    use crate::{q_hash, NQuin};
264
265    fn term_hash(term: Term<'_>) -> u64 {
266        match term {
267            Term::Uri(s) | Term::Literal(s) | Term::Variable(s) | Term::Formula(s) => q_hash(s),
268        }
269    }
270
271    let mut quins = Vec::new();
272    let mut parser = N3Parser::new(n3);
273    parser
274        .parse_all(|event| {
275            if let N3Event::StaticTriple(t) = event {
276                let subject_s = match t.subject {
277                    Term::Uri(s) => s,
278                    _ => "",
279                };
280                if subject_s.starts_with('@') {
281                    return Ok(());
282                }
283                let subject = term_hash(t.subject);
284                let predicate = term_hash(t.predicate);
285                let object = term_hash(t.object);
286                quins.push(NQuin {
287                    subject,
288                    predicate,
289                    object,
290                    context: 0,
291                    metadata: 0,
292                    parity: NQuin::calculate_parity(subject, predicate, object, 0, 0),
293                });
294            }
295            Ok(())
296        })
297        .map_err(|e| InstrumentError::Graph(e.to_string()))?;
298    if quins.is_empty() {
299        return Err(InstrumentError::Graph("no triples in definition".into()));
300    }
301    let dir = tempfile::TempDir::new().map_err(|e| InstrumentError::Graph(e.to_string()))?;
302    let path = dir.path().join("instrument.q42");
303    write_sorted_quins_volume(&path, &quins).map_err(|e| InstrumentError::Graph(e.to_string()))?;
304    let bytes = std::fs::read(&path).map_err(|e| InstrumentError::Graph(e.to_string()))?;
305    drop(dir);
306    Ok(bytes)
307}
308
309/// Build one labelled reference collectable (HMC).
310pub fn build_reference(slug: &str) -> Result<Vec<u8>, InstrumentError> {
311    let seed = reference_by_slug(slug).ok_or(InstrumentError::MissingField("reference slug"))?;
312    let manifest = manifest_for(seed);
313    let small_q42 = {
314        #[cfg(not(target_arch = "wasm32"))]
315        {
316            Some(small_q42_from_n3(seed.definition_n3)?)
317        }
318        #[cfg(target_arch = "wasm32")]
319        {
320            None
321        }
322    };
323    build_collectable(CollectableParts {
324        hcf: super::package::hcf_from_manifest(&manifest),
325        definition_n3: seed.definition_n3.as_bytes().to_vec(),
326        visual_10d: demo_badge_10d().to_vec(),
327        small_q42,
328        manifest,
329    })
330}
331
332#[cfg(test)]
333mod tests {
334    use super::*;
335    use crate::semantic_instruments::category::seed_notice_is_labelled;
336    use crate::semantic_instruments::package::open_collectable;
337
338    #[test]
339    fn catalog_has_three_labelled_references() {
340        assert_eq!(reference_catalog().len(), 3);
341        for seed in reference_catalog() {
342            assert_eq!(seed.entry_point, "assess");
343            assert!(!seed.slug.contains("Host"));
344            assert!(seed_notice_is_labelled(seed.honesty_notice));
345        }
346    }
347
348    #[test]
349    fn core_catalog_has_six_instruments() {
350        assert_eq!(core_instrument_catalog().len(), 6);
351        for seed in core_instrument_catalog() {
352            let bytes = build_reference(seed.slug).expect(seed.slug);
353            let opened = open_collectable(&bytes).expect(seed.slug);
354            assert_eq!(opened.manifest.instrument_id, seed.instrument_id);
355        }
356    }
357
358    #[test]
359    fn each_reference_builds_and_opens() {
360        for seed in reference_catalog() {
361            let bytes = build_reference(seed.slug).expect(seed.slug);
362            let opened = open_collectable(&bytes).expect(seed.slug);
363            assert_eq!(opened.manifest.content_category, ContentCategory::Reference);
364            assert_eq!(opened.manifest.instrument_id, seed.instrument_id);
365            assert_eq!(opened.manifest.entry_point, "assess");
366            assert_eq!(opened.manifest.honesty_notice, seed.honesty_notice);
367            assert!(seed_notice_is_labelled(&opened.manifest.honesty_notice));
368            #[cfg(not(target_arch = "wasm32"))]
369            assert!(opened.small_q42.is_some(), "{}", seed.slug);
370        }
371    }
372
373    #[test]
374    fn simple_units_notice_and_wellbeing_are_labelled_not_host() {
375        let units = reference_by_slug("simple-units").unwrap();
376        let n = units.honesty_notice.to_ascii_lowercase();
377        assert!(n.contains("reference pack"));
378        assert!(n.contains("not operational"));
379        assert_eq!(units.definition_n3, UNIT_N3);
380
381        let well = reference_by_slug("wellbeing-training").unwrap();
382        assert_eq!(well.honesty_notice, NOTICE_WELLBEING);
383        assert_eq!(well.prohibited_interpretation, "diagnosis");
384        assert!(!well.slug.contains("Host"));
385        assert!(!well.definition_n3.contains("Host."));
386        assert!(!well.entry_point.contains("Host"));
387
388        let tax = reference_by_slug("tax-training").unwrap();
389        assert_eq!(tax.honesty_notice, NOTICE_TAX);
390        assert_eq!(tax.prohibited_interpretation, "professional-advice");
391        assert!(!tax.slug.contains("Host"));
392    }
393
394    #[test]
395    fn unknown_slug_is_missing() {
396        assert_eq!(
397            build_reference("Host.ClinicalRisk").unwrap_err(),
398            InstrumentError::MissingField("reference slug")
399        );
400    }
401}