1use 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
13const 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
35const 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#[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
95pub 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
137pub 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
215pub fn core_instrument_by_slug(slug: &str) -> Option<&'static ReferenceSeed> {
217 core_instrument_catalog().iter().find(|s| s.slug == slug)
218}
219
220pub 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
309pub 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}