Skip to main content

qualia_core_db/sensing/quin_index/
encode.rs

1use super::super::record::MeasurementRecord;
2use crate::{
3    frame_layout::{self, INLINE_TAG_BOOLEAN, INLINE_TAG_INTEGER, INLINE_VALUE_MASK},
4    NQuin,
5};
6
7/// Proposed predicates; a host ontology must explicitly adopt their meaning.
8pub mod proposed_predicates {
9    pub const RECORD_ID: u64 = crate::q_hash("urn:qualia:proposed:sensing:measurementRecordId");
10    pub const FIELD_ID: u64 = crate::q_hash("urn:qualia:proposed:sensing:measurementFieldId");
11    pub const FIELD_KIND: u64 = crate::q_hash("urn:qualia:proposed:sensing:measurementFieldKind");
12    pub const PAYLOAD_REFERENCE: u64 =
13        crate::q_hash("urn:qualia:proposed:sensing:measurementPayloadReference");
14    pub const SOURCE_KNOWN: u64 =
15        crate::q_hash("urn:qualia:proposed:sensing:measurementSourceKnown");
16    pub const SOURCE_ID: u64 = crate::q_hash("urn:qualia:proposed:sensing:measurementSourceId");
17}
18
19pub const MAX_MEASUREMENT_LINK_QUINS: usize = 6;
20
21#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub enum MeasurementQuinError {
23    InvalidMapping,
24    IdentifierOutOfRange,
25    RecordMismatch,
26    OutputTooSmall,
27    VocabularyCollision,
28}
29
30/// Explicit record-to-event mapping. The payload IRI is a host-registered
31/// 60-bit token, not a pointer or a digest inferred from the container bytes.
32/// The host must bind it to this record's exact payload reference and policy.
33#[derive(Clone, Copy, Debug, PartialEq, Eq)]
34pub struct MeasurementQuinMapping {
35    record_id: u64,
36    subject: u64,
37    context: u64,
38    payload_iri_token: u64,
39}
40
41impl MeasurementQuinMapping {
42    pub const fn new(
43        record_id: u64,
44        subject: u64,
45        context: u64,
46        payload_iri_token: u64,
47    ) -> Result<Self, MeasurementQuinError> {
48        if record_id == 0 || subject == 0 || context == 0 || payload_iri_token == 0 {
49            return Err(MeasurementQuinError::InvalidMapping);
50        }
51        if record_id > INLINE_VALUE_MASK || payload_iri_token > INLINE_VALUE_MASK {
52            return Err(MeasurementQuinError::IdentifierOutOfRange);
53        }
54        Ok(Self {
55            record_id,
56            subject,
57            context,
58            payload_iri_token,
59        })
60    }
61}
62
63/// Write links only, with zero metadata and parity valid under both current
64/// conventions. Unknown source produces an explicit false flag and no source
65/// ID assertion. Every validation precedes output changes; no ID is truncated.
66pub fn measurement_record_to_quins(
67    record: MeasurementRecord,
68    mapping: MeasurementQuinMapping,
69    output: &mut [NQuin],
70) -> Result<usize, MeasurementQuinError> {
71    use proposed_predicates as p;
72    if record.record_id() != mapping.record_id {
73        return Err(MeasurementQuinError::RecordMismatch);
74    }
75    let field_id = record.physical().field_id();
76    let source_id = record.source_id().value();
77    if field_id > INLINE_VALUE_MASK || source_id.is_some_and(|id| id > INLINE_VALUE_MASK) {
78        return Err(MeasurementQuinError::IdentifierOutOfRange);
79    }
80    let predicates = [
81        p::RECORD_ID,
82        p::FIELD_ID,
83        p::FIELD_KIND,
84        p::PAYLOAD_REFERENCE,
85        p::SOURCE_KNOWN,
86        p::SOURCE_ID,
87    ];
88    for i in 0..predicates.len() {
89        if predicates[..i].contains(&predicates[i]) {
90            return Err(MeasurementQuinError::VocabularyCollision);
91        }
92    }
93    let count = if source_id.is_some() { 6 } else { 5 };
94    if output.len() < count {
95        return Err(MeasurementQuinError::OutputTooSmall);
96    }
97    let objects = [
98        INLINE_TAG_INTEGER | mapping.record_id,
99        INLINE_TAG_INTEGER | field_id,
100        INLINE_TAG_INTEGER | u64::from(record.physical().typed_field_kind()),
101        mapping.payload_iri_token,
102        INLINE_TAG_BOOLEAN | u64::from(source_id.is_some()),
103        INLINE_TAG_INTEGER | source_id.unwrap_or(0),
104    ];
105    let mut staged = [NQuin::default(); MAX_MEASUREMENT_LINK_QUINS];
106    for i in 0..count {
107        staged[i] = frame_layout::sealed(NQuin {
108            subject: mapping.subject,
109            predicate: predicates[i],
110            object: objects[i],
111            context: mapping.context,
112            metadata: 0,
113            parity: 0,
114        });
115    }
116    output[..count].copy_from_slice(&staged[..count]);
117    Ok(count)
118}