Skip to main content

qualia_core_db/hypermedia/
mod.rs

1//! **Hypermedia semantic library** — an asset ⊕ its analytics ⊕ its related/associated assets, bound as a
2//! **semantic graph (NQuins), not a directory structure.**
3//!
4//! The Qualia line is *"context is the asset"*: an asset is never a bare file; it is a first-class entity
5//! that carries, inseparably, what it was derived *from* (`prov:wasDerivedFrom`), the analytics computed
6//! *about* it (`analysisTarget`/`analysisResult`), the related assets bound *with* it (`bundledWith` + a
7//! role), and its provenance (`hasProvenance`). Because the binding is a **graph of edges over the one
8//! identity space** (`q_hash`/`fnv` subjects, shared with [`crate::render::assets`]), you browse and query it
9//! by **meaning and lineage** — "what was this derived from / what analytics belong to it / what's related" —
10//! never by folder path.
11//!
12//! P0 (this module): the semantic model + [`container_to_nquins`] (emit the whole edge-graph) + the
13//! query helpers that read the relationships back out. It composes the real primitives — [`NQuin`],
14//! `q_hash`, and the same 60-bit FNV subject-hashing that `render/assets.rs::mesh_to_nquins` uses, so a
15//! container's reference to a mesh asset resolves to *the same subject* that asset's own manifest emits.
16//! P1 adds the in-`.10d` provenance sidecar + a validate-before-use gate; P2 re-points the anatomy pipeline
17//! through this (an organ = mesh ⊕ systemic-burden analytics ⊕ source-GLB / provenance). See
18//! `docs/plans/hypermedia-semantic-library.md`.
19
20use std::collections::HashMap;
21
22use crate::frame_layout::pack_float_object;
23use crate::{q_hash, NQuin};
24
25/// Content-processor implementations that derive searchability at ingest. The
26/// model-free [`TextProcessor`] lives in this file (it is the framework
27/// reference); the heavier [`ImageProcessor`] (EXIF time/place → the
28/// timeline/map facets) and [`WavProcessor`] (STFT spectral summary) live in
29/// [`processors`] as their own units (§11: split as the library grows).
30pub mod processors;
31pub use processors::{AudioSpectralSummary, ImageProcessor, WavProcessor};
32
33/// The named graph the hypermedia relationship edges live in.
34pub const HYPERMEDIA_CONTEXT: u64 = q_hash("urn:qualia:context:hypermedia");
35
36const P_RDF_TYPE: u64 = q_hash("http://www.w3.org/1999/02/22-rdf-syntax-ns#type");
37const C_CONTAINER: u64 = q_hash("urn:qualia:hypermedia:Container");
38const C_ANALYTICS: u64 = q_hash("urn:qualia:hypermedia:Analytics");
39/// container → its primary asset.
40const P_HAS_PRIMARY: u64 = q_hash("urn:qualia:hypermedia:hasPrimary");
41/// container → each asset it bundles (primary + related).
42const P_BUNDLED_WITH: u64 = q_hash("urn:qualia:hypermedia:bundledWith");
43/// asset → its role class within the container.
44const P_HAS_ROLE: u64 = q_hash("urn:qualia:hypermedia:hasRole");
45/// asset → the source asset it was derived from (W3C PROV).
46const P_WAS_DERIVED_FROM: u64 = q_hash("http://www.w3.org/ns/prov#wasDerivedFrom");
47/// asset → its provenance record asset.
48const P_HAS_PROVENANCE: u64 = q_hash("urn:qualia:hypermedia:hasProvenance");
49/// analytics → the asset it is *about*.
50const P_ANALYSIS_TARGET: u64 = q_hash("urn:qualia:hypermedia:analysisTarget");
51/// container → an analytics result it carries.
52const P_ANALYSIS_RESULT: u64 = q_hash("urn:qualia:hypermedia:analysisResult");
53/// analytics → the method that produced it.
54const P_ANALYSIS_METHOD: u64 = q_hash("urn:qualia:hypermedia:analysisMethod");
55const P_MEDIA_TYPE: u64 = q_hash("urn:qualia:hypermedia:mediaType");
56const P_DIGEST: u64 = q_hash("urn:qualia:hypermedia:digest");
57const P_LICENCE: u64 = q_hash("http://purl.org/dc/terms/license");
58const P_CREATOR: u64 = q_hash("http://purl.org/dc/terms/creator");
59
60/// The role a bundled asset plays relative to the container's primary asset.
61#[derive(Debug, Clone, Copy, PartialEq, Eq)]
62pub enum AssetRole {
63    /// The container's principal asset (the thing it is *about*).
64    Primary,
65    /// An immutable original source the primary/derivations came from.
66    Source,
67    /// A derivation of the primary (e.g. the compiled `.10d`, a transcode).
68    Derivation,
69    /// A level-of-detail variant.
70    Lod,
71    /// An analysis-result asset.
72    Analysis,
73    /// A provenance record (source bytes / licence / VC).
74    Provenance,
75    /// Any other associated asset.
76    Related,
77}
78
79impl AssetRole {
80    const fn uri(self) -> &'static str {
81        match self {
82            AssetRole::Primary => "urn:qualia:hypermedia:role:primary",
83            AssetRole::Source => "urn:qualia:hypermedia:role:source",
84            AssetRole::Derivation => "urn:qualia:hypermedia:role:derivation",
85            AssetRole::Lod => "urn:qualia:hypermedia:role:lod",
86            AssetRole::Analysis => "urn:qualia:hypermedia:role:analysis",
87            AssetRole::Provenance => "urn:qualia:hypermedia:role:provenance",
88            AssetRole::Related => "urn:qualia:hypermedia:role:related",
89        }
90    }
91
92    /// The `q_hash` of this role's class IRI — the object of a `hasRole` edge.
93    pub fn class(self) -> u64 {
94        q_hash(self.uri())
95    }
96
97    /// Map a role-class hash back to the role (for reading edges).
98    pub fn from_class(class: u64) -> Option<AssetRole> {
99        const ALL: [AssetRole; 7] = [
100            AssetRole::Primary,
101            AssetRole::Source,
102            AssetRole::Derivation,
103            AssetRole::Lod,
104            AssetRole::Analysis,
105            AssetRole::Provenance,
106            AssetRole::Related,
107        ];
108        ALL.into_iter().find(|r| r.class() == class)
109    }
110}
111
112/// A content-addressed reference to an asset (its stable subject is `fnv60(uri)`, the same subject its own
113/// geometry manifest emits, so container edges join to the asset's facts in the one identity space).
114#[derive(Debug, Clone, PartialEq, Eq)]
115pub struct AssetRef {
116    pub uri: String,
117    /// Content digest (CRC-32C or SHA-256 truncated) — the anti-tamper / dedup anchor.
118    pub digest: u64,
119    pub media_type: String,
120    pub role: AssetRole,
121    /// URIs of the source asset(s) this one was derived from (emits `prov:wasDerivedFrom`).
122    pub derived_from: Vec<String>,
123    /// Optional licence / creator (dcterms) — the never-strip-context fields.
124    pub licence: Option<String>,
125    pub creator: Option<String>,
126}
127
128impl AssetRef {
129    /// Creates an asset reference for `uri` with media-type and hash metadata.
130    pub fn new(
131        uri: impl Into<String>,
132        digest: u64,
133        media_type: impl Into<String>,
134        role: AssetRole,
135    ) -> Self {
136        Self {
137            uri: uri.into(),
138            digest,
139            media_type: media_type.into(),
140            role,
141            derived_from: Vec::new(),
142            licence: None,
143            creator: None,
144        }
145    }
146
147    /// Builder: records the source URI this asset derives from.
148    pub fn derived_from(mut self, source_uri: impl Into<String>) -> Self {
149        self.derived_from.push(source_uri.into());
150        self
151    }
152    /// Builder: attaches a licence URI.
153    pub fn with_licence(mut self, licence: impl Into<String>) -> Self {
154        self.licence = Some(licence.into());
155        self
156    }
157    /// q_hash of the asset URI — the graph subject.
158    pub fn subject(&self) -> u64 {
159        fnv60(self.uri.as_bytes())
160    }
161}
162
163/// An analytics result *about* an asset — the derived data bound back to the geometry it concerns.
164#[derive(Debug, Clone, PartialEq, Eq)]
165pub struct AnalyticsRef {
166    pub id: String,
167    /// The method/tool that produced it (e.g. `wellfare:systemic-burden`).
168    pub method: String,
169    /// The URI of the asset this analysis is *about* (defaults to the container primary if empty).
170    pub target_uri: String,
171    /// A short serialized summary of the result (e.g. a JSON burden roll-up).
172    pub summary: String,
173}
174
175impl AnalyticsRef {
176    /// `AnalyticsRef::subject`.
177    pub fn subject(&self) -> u64 {
178        fnv60(self.id.as_bytes())
179    }
180}
181
182/// A hypermedia container: a primary asset bundled with its related assets and its analytics, as one
183/// addressable semantic unit.
184#[derive(Debug, Clone, PartialEq, Eq)]
185pub struct HypermediaContainer {
186    pub uri: String,
187    pub primary: AssetRef,
188    pub related: Vec<AssetRef>,
189    pub analytics: Vec<AnalyticsRef>,
190}
191
192impl HypermediaContainer {
193    /// Creates a container rooted at `uri` holding `primary`.
194    pub fn new(uri: impl Into<String>, primary: AssetRef) -> Self {
195        Self {
196            uri: uri.into(),
197            primary,
198            related: Vec::new(),
199            analytics: Vec::new(),
200        }
201    }
202    /// Builder: adds a related asset.
203    pub fn with_related(mut self, asset: AssetRef) -> Self {
204        self.related.push(asset);
205        self
206    }
207    /// Builder: attaches analytics metadata.
208    pub fn with_analytics(mut self, analytics: AnalyticsRef) -> Self {
209        self.analytics.push(analytics);
210        self
211    }
212    /// q_hash of the container URI.
213    pub fn subject(&self) -> u64 {
214        fnv60(self.uri.as_bytes())
215    }
216}
217
218/// The same 60-bit FNV-1a subject hash `render/assets.rs` uses — so a container's reference to a mesh asset
219/// resolves to the *identical* subject that asset's own `mesh_to_nquins` manifest emits (one identity space).
220pub fn fnv60(bytes: &[u8]) -> u64 {
221    let mut h: u64 = 0xcbf2_9ce4_8422_2325;
222    for &b in bytes {
223        h ^= b as u64;
224        h = h.wrapping_mul(0x0000_0100_0000_01b3);
225    }
226    h & 0x0FFF_FFFF_FFFF_FFFF
227}
228
229/// A content digest for an asset's bytes, in the same 60-bit identity space as
230/// asset subjects — the anti-tamper / dedup anchor a caller stores as
231/// [`AssetRef::digest`]. (Public wrapper so client-core ingest can compute it.)
232pub fn content_digest(bytes: &[u8]) -> u64 {
233    fnv60(bytes)
234}
235
236fn edge(subject: u64, predicate: u64, object: u64) -> NQuin {
237    let context = HYPERMEDIA_CONTEXT;
238    let metadata = 0;
239    NQuin {
240        subject,
241        predicate,
242        object,
243        context,
244        metadata,
245        parity: NQuin::calculate_parity(subject, predicate, object, context, metadata),
246    }
247}
248
249/// Emit the **whole relationship edge-graph** of a container as NQuins (+ a lexicon of the string values),
250/// in the [`HYPERMEDIA_CONTEXT`] named graph. This is the semantic library's core: the edges *are* the
251/// container. Every emitted quin carries valid field parity.
252pub fn container_to_nquins(c: &HypermediaContainer) -> (Vec<NQuin>, HashMap<u64, String>) {
253    let mut quins = Vec::new();
254    let mut lexicon: HashMap<u64, String> = HashMap::new();
255    let cs = c.subject();
256    lexicon.insert(cs, c.uri.clone());
257
258    // The container node.
259    quins.push(edge(cs, P_RDF_TYPE, C_CONTAINER));
260    quins.push(edge(cs, P_HAS_PRIMARY, c.primary.subject()));
261
262    // Every asset (primary first, then related) is bundled and described.
263    let assets = std::iter::once(&c.primary).chain(c.related.iter());
264    for a in assets {
265        let asu = a.subject();
266        lexicon.insert(asu, a.uri.clone());
267        quins.push(edge(cs, P_BUNDLED_WITH, asu));
268        quins.push(edge(asu, P_HAS_ROLE, a.role.class()));
269
270        let mt = fnv60(a.media_type.as_bytes());
271        lexicon.insert(mt, a.media_type.clone());
272        quins.push(edge(asu, P_MEDIA_TYPE, mt));
273        quins.push(edge(asu, P_DIGEST, a.digest));
274
275        for src in &a.derived_from {
276            let ss = fnv60(src.as_bytes());
277            lexicon.insert(ss, src.clone());
278            quins.push(edge(asu, P_WAS_DERIVED_FROM, ss));
279        }
280        if a.role == AssetRole::Provenance {
281            quins.push(edge(c.primary.subject(), P_HAS_PROVENANCE, asu));
282        }
283        if let Some(lic) = &a.licence {
284            let lh = fnv60(lic.as_bytes());
285            lexicon.insert(lh, lic.clone());
286            quins.push(edge(asu, P_LICENCE, lh));
287        }
288        if let Some(cr) = &a.creator {
289            let ch = fnv60(cr.as_bytes());
290            lexicon.insert(ch, cr.clone());
291            quins.push(edge(asu, P_CREATOR, ch));
292        }
293    }
294
295    // Analytics bound back to the asset they are *about*.
296    for an in &c.analytics {
297        let ansu = an.subject();
298        lexicon.insert(ansu, an.id.clone());
299        let target = if an.target_uri.is_empty() {
300            c.primary.subject()
301        } else {
302            fnv60(an.target_uri.as_bytes())
303        };
304        quins.push(edge(ansu, P_RDF_TYPE, C_ANALYTICS));
305        quins.push(edge(ansu, P_ANALYSIS_TARGET, target));
306        quins.push(edge(cs, P_ANALYSIS_RESULT, ansu));
307        let mh = fnv60(an.method.as_bytes());
308        lexicon.insert(mh, an.method.clone());
309        quins.push(edge(ansu, P_ANALYSIS_METHOD, mh));
310    }
311
312    (quins, lexicon)
313}
314
315// ── Query the graph by *meaning and lineage* (not by path) ──────────────────────────────────────
316
317fn objects(quins: &[NQuin], subject: u64, predicate: u64) -> Vec<u64> {
318    quins
319        .iter()
320        .filter(|q| {
321            q.context == HYPERMEDIA_CONTEXT && q.subject == subject && q.predicate == predicate
322        })
323        .map(|q| q.object)
324        .collect()
325}
326
327/// The container's primary asset subject.
328pub fn primary_of(quins: &[NQuin], container_subject: u64) -> Option<u64> {
329    objects(quins, container_subject, P_HAS_PRIMARY)
330        .first()
331        .copied()
332}
333
334/// Every asset subject a container bundles (primary + related).
335pub fn bundled(quins: &[NQuin], container_subject: u64) -> Vec<u64> {
336    objects(quins, container_subject, P_BUNDLED_WITH)
337}
338
339/// The role of an asset within the container.
340pub fn role_of(quins: &[NQuin], asset_subject: u64) -> Option<AssetRole> {
341    objects(quins, asset_subject, P_HAS_ROLE)
342        .first()
343        .copied()
344        .and_then(AssetRole::from_class)
345}
346
347/// The source asset subjects an asset was derived from — its lineage.
348pub fn derived_from(quins: &[NQuin], asset_subject: u64) -> Vec<u64> {
349    objects(quins, asset_subject, P_WAS_DERIVED_FROM)
350}
351
352/// The provenance-record subject bound to an asset, if any.
353pub fn provenance_of(quins: &[NQuin], asset_subject: u64) -> Option<u64> {
354    objects(quins, asset_subject, P_HAS_PROVENANCE)
355        .first()
356        .copied()
357}
358
359/// The analytics subjects that are *about* a given asset — the derived data belonging to it.
360pub fn analytics_for(quins: &[NQuin], asset_subject: u64) -> Vec<u64> {
361    quins
362        .iter()
363        .filter(|q| {
364            q.context == HYPERMEDIA_CONTEXT
365                && q.predicate == P_ANALYSIS_TARGET
366                && q.object == asset_subject
367        })
368        .map(|q| q.subject)
369        .collect()
370}
371
372// ── Descriptors (facets): find assets by meaning / time / place / project / content, not by path ──
373//
374// Ingest *derives* searchability: a processor attaches these facets to an asset, and search is a query over
375// the edges — "files about a topic", "what an image depicts", "events in a period" (timeline), "photos at a
376// place" (map), "everything for a project", "documents that support a tax/expenses claim". None is a folder.
377
378const P_TOPIC: u64 = q_hash("urn:qualia:hypermedia:topic");
379const P_DEPICTS: u64 = q_hash("urn:qualia:hypermedia:depicts");
380const P_OCCURRED_AT: u64 = q_hash("urn:qualia:hypermedia:occurredAt");
381const P_OCCURRED_START: u64 = q_hash("urn:qualia:hypermedia:occurredStart");
382const P_OCCURRED_END: u64 = q_hash("urn:qualia:hypermedia:occurredEnd");
383const P_AT_PLACE: u64 = q_hash("urn:qualia:hypermedia:atPlace");
384const P_AT_LAT: u64 = q_hash("urn:qualia:hypermedia:atLat");
385const P_AT_LON: u64 = q_hash("urn:qualia:hypermedia:atLon");
386const P_IN_PROJECT: u64 = q_hash("urn:qualia:hypermedia:inProject");
387const P_DOCUMENT_TYPE: u64 = q_hash("urn:qualia:hypermedia:documentType");
388const P_PURPOSE: u64 = q_hash("urn:qualia:hypermedia:purpose");
389const P_HAS_FLAG: u64 = q_hash("urn:qualia:hypermedia:hasFlag");
390const P_FLAG_KIND: u64 = q_hash("urn:qualia:hypermedia:flagKind");
391const P_FLAG_SEVERITY: u64 = q_hash("urn:qualia:hypermedia:flagSeverity");
392const P_FLAG_DETAIL: u64 = q_hash("urn:qualia:hypermedia:flagDetail");
393const C_FLAG: u64 = q_hash("urn:qualia:hypermedia:Flag");
394
395/// A place an asset is bound to — a human label plus coordinates (for the map view).
396#[derive(Debug, Clone, PartialEq)]
397pub struct Place {
398    pub label: String,
399    pub lat: f32,
400    pub lon: f32,
401}
402
403/// The semantic facets that make an asset findable — topic, what it depicts, when/where it happened, which
404/// project it belongs to, and its document-type / purpose (e.g. tax-support). All edges; none a folder.
405#[derive(Debug, Clone, Default, PartialEq)]
406pub struct Descriptors {
407    pub topics: Vec<String>,
408    /// Subjects depicted in an image (the "representation of something in the image").
409    pub depicts: Vec<String>,
410    /// A single event instant (unix seconds) — the timeline anchor.
411    pub occurred_at: Option<i64>,
412    /// A period the asset covers (unix seconds).
413    pub occurred_interval: Option<(i64, i64)>,
414    pub place: Option<Place>,
415    pub projects: Vec<String>,
416    pub document_type: Option<String>,
417    /// Purposes the asset serves (e.g. `tax-return-2025`, `expenses-claim`).
418    pub purposes: Vec<String>,
419}
420
421/// Emit descriptor edges for an asset subject. Each string facet's object is `fnv60(value)` (so a search for
422/// that value matches); event times are stored as their `u64` bit pattern for range scans.
423pub fn descriptors_to_nquins(
424    asset_subject: u64,
425    d: &Descriptors,
426) -> (Vec<NQuin>, HashMap<u64, String>) {
427    let mut quins = Vec::new();
428    let mut lex = HashMap::new();
429    let str_edge =
430        |quins: &mut Vec<NQuin>, lex: &mut HashMap<u64, String>, pred: u64, val: &str| {
431            let o = fnv60(val.as_bytes());
432            lex.insert(o, val.to_string());
433            quins.push(edge(asset_subject, pred, o));
434        };
435    for t in &d.topics {
436        str_edge(&mut quins, &mut lex, P_TOPIC, t);
437    }
438    for s in &d.depicts {
439        str_edge(&mut quins, &mut lex, P_DEPICTS, s);
440    }
441    for p in &d.projects {
442        str_edge(&mut quins, &mut lex, P_IN_PROJECT, p);
443    }
444    for p in &d.purposes {
445        str_edge(&mut quins, &mut lex, P_PURPOSE, p);
446    }
447    if let Some(dt) = &d.document_type {
448        str_edge(&mut quins, &mut lex, P_DOCUMENT_TYPE, dt);
449    }
450    if let Some(t) = d.occurred_at {
451        quins.push(edge(asset_subject, P_OCCURRED_AT, t as u64));
452    }
453    if let Some((s, e)) = d.occurred_interval {
454        quins.push(edge(asset_subject, P_OCCURRED_START, s as u64));
455        quins.push(edge(asset_subject, P_OCCURRED_END, e as u64));
456    }
457    if let Some(pl) = &d.place {
458        let lh = fnv60(pl.label.as_bytes());
459        lex.insert(lh, pl.label.clone());
460        quins.push(edge(asset_subject, P_AT_PLACE, lh));
461        quins.push(edge(asset_subject, P_AT_LAT, pack_float_object(pl.lat)));
462        quins.push(edge(asset_subject, P_AT_LON, pack_float_object(pl.lon)));
463    }
464    (quins, lex)
465}
466
467fn subjects_with(quins: &[NQuin], predicate: u64, object: u64) -> Vec<u64> {
468    quins
469        .iter()
470        .filter(|q| {
471            q.context == HYPERMEDIA_CONTEXT && q.predicate == predicate && q.object == object
472        })
473        .map(|q| q.subject)
474        .collect()
475}
476
477/// Assets *about* a topic. (biology / engineering / policy / software / law / …)
478pub fn by_topic(quins: &[NQuin], topic: &str) -> Vec<u64> {
479    subjects_with(quins, P_TOPIC, fnv60(topic.as_bytes()))
480}
481/// Assets whose image *depicts* a subject (the "representation in the image").
482pub fn by_depiction(quins: &[NQuin], subject: &str) -> Vec<u64> {
483    subjects_with(quins, P_DEPICTS, fnv60(subject.as_bytes()))
484}
485/// Assets at a place (map view).
486pub fn by_place(quins: &[NQuin], place_label: &str) -> Vec<u64> {
487    subjects_with(quins, P_AT_PLACE, fnv60(place_label.as_bytes()))
488}
489/// Assets collected under a project.
490pub fn in_project(quins: &[NQuin], project: &str) -> Vec<u64> {
491    subjects_with(quins, P_IN_PROJECT, fnv60(project.as_bytes()))
492}
493/// Assets serving a purpose (e.g. `tax-return-2025`, `expenses-claim`).
494pub fn for_purpose(quins: &[NQuin], purpose: &str) -> Vec<u64> {
495    subjects_with(quins, P_PURPOSE, fnv60(purpose.as_bytes()))
496}
497/// Assets whose event instant falls within `[start, end]` (unix seconds) — the timeline query.
498pub fn in_time_range(quins: &[NQuin], start: i64, end: i64) -> Vec<u64> {
499    quins
500        .iter()
501        .filter(|q| {
502            q.context == HYPERMEDIA_CONTEXT
503                && q.predicate == P_OCCURRED_AT
504                && (q.object as i64) >= start
505                && (q.object as i64) <= end
506        })
507        .map(|q| q.subject)
508        .collect()
509}
510
511/// Severity of an ingest flag. Higher = more likely to warrant a guardian notification.
512#[derive(Debug, Clone, Copy, PartialEq, Eq)]
513pub enum FlagSeverity {
514    Info,
515    Notice,
516    Concern,
517    Urgent,
518}
519impl FlagSeverity {
520    /// Numeric severity level for ordering.
521    pub fn level(self) -> u64 {
522        match self {
523            FlagSeverity::Info => 0,
524            FlagSeverity::Notice => 1,
525            FlagSeverity::Concern => 2,
526            FlagSeverity::Urgent => 3,
527        }
528    }
529}
530
531/// A flag raised while processing an ingested asset (e.g. concerning content). The flag is a **semantic
532/// descriptor** on the asset; if the principal is under a guardianship relation, the ingest path
533/// (client-core / host) reads these and notifies the guardian (and records who was notified — the
534/// accountability fabric). Defining flags here keeps them queryable; the notification wiring lives where
535/// guardianship + notifications do.
536#[derive(Debug, Clone, PartialEq, Eq)]
537pub struct Flag {
538    pub kind: String,
539    pub severity: FlagSeverity,
540    pub detail: String,
541}
542
543/// Emit flag edges bound to an asset subject.
544pub fn flags_to_nquins(
545    asset_subject: u64,
546    asset_uri: &str,
547    flags: &[Flag],
548) -> (Vec<NQuin>, HashMap<u64, String>) {
549    let mut quins = Vec::new();
550    let mut lex = HashMap::new();
551    for f in flags {
552        let fs = fnv60(format!("{asset_uri}#flag:{}", f.kind).as_bytes());
553        lex.insert(fs, format!("{asset_uri}#flag:{}", f.kind));
554        quins.push(edge(asset_subject, P_HAS_FLAG, fs));
555        quins.push(edge(fs, P_RDF_TYPE, C_FLAG));
556        let kh = fnv60(f.kind.as_bytes());
557        lex.insert(kh, f.kind.clone());
558        quins.push(edge(fs, P_FLAG_KIND, kh));
559        quins.push(edge(fs, P_FLAG_SEVERITY, f.severity.level()));
560        if !f.detail.is_empty() {
561            let dh = fnv60(f.detail.as_bytes());
562            lex.insert(dh, f.detail.clone());
563            quins.push(edge(fs, P_FLAG_DETAIL, dh));
564        }
565    }
566    (quins, lex)
567}
568
569/// The flag subjects raised on an asset — what the guardian-notify path reads.
570pub fn flags_on(quins: &[NQuin], asset_subject: u64) -> Vec<u64> {
571    objects(quins, asset_subject, P_HAS_FLAG)
572}
573/// A flag's severity level (0 Info .. 3 Urgent), if present.
574pub fn flag_severity(quins: &[NQuin], flag_subject: u64) -> Option<u64> {
575    objects(quins, flag_subject, P_FLAG_SEVERITY)
576        .first()
577        .copied()
578}
579
580// ── Ingest processors: ingest DERIVES searchability (P3) ─────────────────────────────────────────
581//
582// A document/image/asset goes in; a processor produces the derived searchable files (text / transcript /
583// depicted-subjects / thumbnail) + descriptor facets + any flags — which fold into the asset's container so
584// the *original* becomes findable. Heavy content processors (image→depicted-subjects/OCR, audio→transcript)
585// compose the parked `qualia-vision` / `qualia-audio` engines; this is the framework + a real model-free
586// text processor. (§11: this module is ~800 lines — split `hypermedia.rs` → `hypermedia/{container,descriptors,
587// processors}.rs` in a dedicated library-ization pass.)
588
589/// What a processor derives from an ingested asset — the searchable representations + facets + flags.
590#[derive(Debug, Clone, Default, PartialEq)]
591pub struct ProcessorOutput {
592    /// Derived searchable assets (role Derivation / Analysis) to bundle into the container.
593    pub derived: Vec<AssetRef>,
594    /// The bytes of each derived asset, keyed by its uri (e.g. the extracted plain text).
595    pub derived_bytes: HashMap<String, Vec<u8>>,
596    /// Descriptor facets extracted (topics, depicts, …) — bound to the primary asset.
597    pub descriptors: Descriptors,
598    /// Flags raised (→ the guardian-notify path when the principal is under guardianship).
599    pub flags: Vec<Flag>,
600}
601
602/// A processor: ingest an asset (bytes + media-type) → derive its searchable representations + facets.
603pub trait Processor {
604    /// Whether this processor handles the given media type.
605    fn handles(&self, media_type: &str) -> bool;
606    /// Derive searchable content + descriptors + flags from the asset.
607    fn process(&self, asset_uri: &str, bytes: &[u8], media_type: &str) -> ProcessorOutput;
608}
609
610/// A real, **model-free text / markdown** processor: derives a plain-text representation, assigns **topics**
611/// from a keyword map (biology / engineering / policy / software / law / finance-for-tax-&-expenses), and
612/// raises a **flag** for any watch-word present. Proves "ingest derives searchability" with no model runtime;
613/// the semantic-content processors compose `qualia-vision` / `qualia-audio`.
614pub struct TextProcessor {
615    /// topic → trigger words (any present ⇒ the topic is assigned).
616    pub topic_keywords: Vec<(String, Vec<String>)>,
617    /// watch-word → (flag kind, severity) (any present ⇒ a flag is raised).
618    pub flag_words: Vec<(String, (String, FlagSeverity))>,
619}
620
621impl Default for TextProcessor {
622    fn default() -> Self {
623        let kw = |t: &str, ws: &[&str]| (t.to_string(), ws.iter().map(|s| s.to_string()).collect());
624        Self {
625            topic_keywords: vec![
626                kw(
627                    "biology",
628                    &[
629                        "cell",
630                        "organ",
631                        "gene",
632                        "protein",
633                        "hepatocyte",
634                        "liver",
635                        "anatomy",
636                    ],
637                ),
638                kw(
639                    "engineering",
640                    &["stress", "load", "circuit", "tolerance", "mechanical"],
641                ),
642                kw(
643                    "policy",
644                    &["policy", "regulation", "governance", "legislation"],
645                ),
646                kw(
647                    "software",
648                    &["function", "compiler", "api", "struct", "runtime"],
649                ),
650                kw(
651                    "law",
652                    &["contract", "statute", "liability", "clause", "jurisdiction"],
653                ),
654                kw(
655                    "finance",
656                    &["invoice", "expense", "tax", "receipt", "deduction"],
657                ),
658                // Privacy / GDPR-family (aligned with wellfair::cml_context extractors).
659                kw(
660                    "privacy",
661                    &[
662                        "personal data",
663                        "data subject",
664                        "data controller",
665                        "data processor",
666                        "consent",
667                        "gdpr",
668                        "privacy",
669                        "erasure",
670                        "portability",
671                        "dpia",
672                        "breach",
673                    ],
674                ),
675                kw(
676                    "human-rights",
677                    &[
678                        "human rights",
679                        "discrimination",
680                        "freedom of expression",
681                        "due process",
682                        "fair trial",
683                    ],
684                ),
685                kw(
686                    "deontic",
687                    &[
688                        "must not",
689                        "shall not",
690                        "is required to",
691                        "obligation",
692                        "prohibition",
693                    ],
694                ),
695            ],
696            flag_words: Vec::new(),
697        }
698    }
699}
700
701impl Processor for TextProcessor {
702    fn handles(&self, media_type: &str) -> bool {
703        media_type.starts_with("text/")
704    }
705
706    fn process(&self, asset_uri: &str, bytes: &[u8], _media_type: &str) -> ProcessorOutput {
707        let text = String::from_utf8_lossy(bytes).to_lowercase();
708        let mut topics = Vec::new();
709        for (topic, words) in &self.topic_keywords {
710            if words.iter().any(|w| text.contains(&w.to_lowercase())) {
711                topics.push(topic.clone());
712            }
713        }
714        let mut flags = Vec::new();
715        for (word, (kind, sev)) in &self.flag_words {
716            if text.contains(&word.to_lowercase()) {
717                flags.push(Flag {
718                    kind: kind.clone(),
719                    severity: *sev,
720                    detail: format!("matched '{word}'"),
721                });
722            }
723        }
724        // A plain-text derivation of the original (what makes it searchable), derived from the primary.
725        let text_uri = format!("{asset_uri}#text");
726        let derived =
727            vec![
728                AssetRef::new(&text_uri, fnv60(bytes), "text/plain", AssetRole::Derivation)
729                    .derived_from(asset_uri),
730            ];
731        let mut derived_bytes = HashMap::new();
732        derived_bytes.insert(text_uri, bytes.to_vec());
733        ProcessorOutput {
734            derived,
735            derived_bytes,
736            descriptors: Descriptors {
737                topics,
738                ..Default::default()
739            },
740            flags,
741        }
742    }
743}
744
745/// The result of ingesting an asset through a processor: the container, its quin graph (edges + descriptors +
746/// flags), the lexicon, and the flags (which the caller checks against a guardianship relation).
747pub struct IngestResult {
748    pub container: HypermediaContainer,
749    pub quins: Vec<NQuin>,
750    pub lexicon: HashMap<u64, String>,
751    pub flags: Vec<Flag>,
752}
753
754/// **Ingest an asset through a processor** and fold its output into a fresh container — the original plus its
755/// derived searchable representations, its facets, and any flags, all as edges. `digest` is the primary
756/// asset's content digest.
757pub fn ingest_with(
758    processor: &dyn Processor,
759    asset_uri: &str,
760    media_type: &str,
761    digest: u64,
762    bytes: &[u8],
763) -> IngestResult {
764    let out = processor.process(asset_uri, bytes, media_type);
765    let primary = AssetRef::new(asset_uri, digest, media_type, AssetRole::Primary);
766    let mut container = HypermediaContainer::new(format!("{asset_uri}#container"), primary.clone());
767    for d in &out.derived {
768        container = container.with_related(d.clone());
769    }
770    let (mut quins, mut lexicon) = container_to_nquins(&container);
771    let (dq, dl) = descriptors_to_nquins(primary.subject(), &out.descriptors);
772    quins.extend(dq);
773    for (k, v) in dl {
774        lexicon.entry(k).or_insert(v);
775    }
776    let (fq, fl) = flags_to_nquins(primary.subject(), asset_uri, &out.flags);
777    quins.extend(fq);
778    for (k, v) in fl {
779        lexicon.entry(k).or_insert(v);
780    }
781    IngestResult {
782        container,
783        quins,
784        lexicon,
785        flags: out.flags,
786    }
787}
788
789#[cfg(test)]
790mod tests {
791    use super::*;
792
793    /// Build a real anatomy-shaped container (an organ mesh ⊕ its source GLB ⊕ a systemic-burden analysis ⊕
794    /// a provenance record) and read every relationship back out of the quin graph — proving the container is
795    /// a **semantic graph of edges**, not a directory.
796    #[test]
797    fn container_round_trips_as_a_semantic_graph_not_a_directory() {
798        let primary = AssetRef::new(
799            "urn:qualia:organ:liver.10d",
800            0xABCD,
801            "model/qualia-10d",
802            AssetRole::Primary,
803        )
804        .derived_from("urn:hra:ccf:liver.glb");
805        let source = AssetRef::new(
806            "urn:hra:ccf:liver.glb",
807            0x1234,
808            "model/gltf-binary",
809            AssetRole::Source,
810        )
811        .with_licence("CC-BY-4.0");
812        let provenance = AssetRef::new(
813            "urn:qualia:prov:liver",
814            0x5555,
815            "application/ld+json",
816            AssetRole::Provenance,
817        );
818        let analysis = AnalyticsRef {
819            id: "urn:qualia:analysis:liver-burden".into(),
820            method: "wellfare:systemic-burden".into(),
821            target_uri: String::new(), // → the primary
822            summary: r#"{"digestive":420,"circulatory":180}"#.into(),
823        };
824
825        let c = HypermediaContainer::new("urn:qualia:container:liver", primary.clone())
826            .with_related(source.clone())
827            .with_related(provenance.clone())
828            .with_analytics(analysis.clone());
829
830        let (quins, _lex) = container_to_nquins(&c);
831        assert!(
832            quins.iter().all(|q| q.verify_ecc_parity()),
833            "every emitted quin has valid parity"
834        );
835
836        let cs = c.subject();
837        // The primary edge resolves to the SAME subject the asset's own manifest would use.
838        assert_eq!(primary_of(&quins, cs), Some(primary.subject()));
839        // The container bundles all three assets.
840        let bundled = bundled(&quins, cs);
841        assert_eq!(bundled.len(), 3);
842        assert!(bundled.contains(&source.subject()) && bundled.contains(&provenance.subject()));
843        // Roles are readable per asset.
844        assert_eq!(role_of(&quins, primary.subject()), Some(AssetRole::Primary));
845        assert_eq!(role_of(&quins, source.subject()), Some(AssetRole::Source));
846        // Lineage: the primary was derived from the source GLB.
847        assert_eq!(
848            derived_from(&quins, primary.subject()),
849            vec![source.subject()]
850        );
851        // Provenance is bound to the primary.
852        assert_eq!(
853            provenance_of(&quins, primary.subject()),
854            Some(provenance.subject())
855        );
856        // The analysis is bound *back to the mesh it is about* — not a sibling file, an edge.
857        assert_eq!(
858            analytics_for(&quins, primary.subject()),
859            vec![analysis.subject()]
860        );
861    }
862
863    #[test]
864    fn role_class_round_trips() {
865        for r in [
866            AssetRole::Primary,
867            AssetRole::Source,
868            AssetRole::Derivation,
869            AssetRole::Lod,
870            AssetRole::Analysis,
871            AssetRole::Provenance,
872            AssetRole::Related,
873        ] {
874            assert_eq!(AssetRole::from_class(r.class()), Some(r));
875        }
876    }
877
878    #[test]
879    fn subject_hash_matches_the_asset_identity_space() {
880        // A container's reference to a URI hashes to the same 60-bit FNV subject that render/assets uses,
881        // so container edges join to the asset's own geometry facts.
882        let a = AssetRef::new(
883            "urn:qualia:organ:heart.10d",
884            1,
885            "model/qualia-10d",
886            AssetRole::Primary,
887        );
888        assert_eq!(
889            a.subject() & 0xF000_0000_0000_0000,
890            0,
891            "subject stays in the 60-bit identity space"
892        );
893        assert_eq!(a.subject(), fnv60(b"urn:qualia:organ:heart.10d"));
894    }
895
896    #[test]
897    fn descriptors_make_assets_findable_by_facet_not_folder() {
898        let liver = fnv60(b"urn:qualia:organ:liver.10d");
899        let heart = fnv60(b"urn:qualia:organ:heart.10d");
900        let d_liver = Descriptors {
901            topics: vec!["biology".into(), "anatomy".into()],
902            projects: vec!["med-course".into()],
903            purposes: vec!["study".into()],
904            occurred_at: Some(1_700_000_000),
905            place: Some(Place {
906                label: "Sydney".into(),
907                lat: -33.87,
908                lon: 151.21,
909            }),
910            ..Default::default()
911        };
912        let d_heart = Descriptors {
913            topics: vec!["biology".into()],
914            occurred_at: Some(1_700_100_000),
915            ..Default::default()
916        };
917        let (mut q, _) = descriptors_to_nquins(liver, &d_liver);
918        let (q2, _) = descriptors_to_nquins(heart, &d_heart);
919        q.extend(q2);
920        assert!(
921            q.iter().all(|x| x.verify_ecc_parity()),
922            "descriptor quins have valid parity"
923        );
924
925        // By topic: both are biology; only the liver is anatomy — search by MEANING, not path.
926        let bio = by_topic(&q, "biology");
927        assert!(bio.contains(&liver) && bio.contains(&heart));
928        assert_eq!(by_topic(&q, "anatomy"), vec![liver]);
929        // By project / place / purpose.
930        assert_eq!(in_project(&q, "med-course"), vec![liver]);
931        assert_eq!(by_place(&q, "Sydney"), vec![liver]);
932        assert_eq!(for_purpose(&q, "study"), vec![liver]);
933        // Timeline: a window that excludes the liver's instant catches only the heart.
934        assert_eq!(in_time_range(&q, 1_700_050_000, 1_700_200_000), vec![heart]);
935    }
936
937    #[test]
938    fn a_flag_is_bound_to_the_asset_for_the_guardian_path() {
939        let uri = "urn:qualia:doc:xray.10d";
940        let asset = fnv60(uri.as_bytes());
941        let (q, _) = flags_to_nquins(
942            asset,
943            uri,
944            &[Flag {
945                kind: "sensitive-medical".into(),
946                severity: FlagSeverity::Concern,
947                detail: "radiograph".into(),
948            }],
949        );
950        assert!(q.iter().all(|x| x.verify_ecc_parity()));
951        let flags = flags_on(&q, asset);
952        assert_eq!(
953            flags.len(),
954            1,
955            "the flag is bound to the asset (what the guardian-notify path reads)"
956        );
957        assert_eq!(flag_severity(&q, flags[0]), Some(2), "Concern = level 2");
958    }
959
960    #[test]
961    fn text_processor_derives_topics_and_a_searchable_text_derivation() {
962        let proc = TextProcessor::default();
963        let doc = b"The human liver is an organ; hepatocytes secrete bile.";
964        let out = proc.process("urn:doc:liver-notes", doc, "text/markdown");
965        assert!(
966            out.descriptors.topics.contains(&"biology".to_string()),
967            "topic derived from content"
968        );
969        assert_eq!(
970            out.derived.len(),
971            1,
972            "a searchable text derivation is produced"
973        );
974        assert_eq!(out.derived[0].role, AssetRole::Derivation);
975    }
976
977    #[test]
978    fn ingest_makes_the_original_findable_and_raises_a_flag() {
979        // A processor with a topic (law) and a watch-word that raises a flag (for the guardian path).
980        let proc = TextProcessor {
981            topic_keywords: vec![("law".into(), vec!["contract".into(), "statute".into()])],
982            flag_words: vec![(
983                "confidential".into(),
984                ("sensitive".into(), FlagSeverity::Concern),
985            )],
986        };
987        let doc = b"This CONFIDENTIAL contract is governed by statute.";
988        let r = ingest_with(&proc, "urn:doc:nda", "text/plain", 0xAA, doc);
989        let primary = r.container.primary.subject();
990        // The original is now findable by meaning.
991        assert!(
992            by_topic(&r.quins, "law").contains(&primary),
993            "original findable by derived topic"
994        );
995        // The flag is raised AND bound to the asset — the guardian-notify path reads it.
996        assert_eq!(r.flags.len(), 1);
997        assert!(!flags_on(&r.quins, primary).is_empty());
998        assert!(r.quins.iter().all(|q| q.verify_ecc_parity()));
999    }
1000}