Skip to main content

qualia_core_db/q42/
spatial_predicates.rs

1//! Canonical `.q42` spatial, volumetric, and multi-sensory ontological predicates (§3.6.2 / §2.8).
2//!
3//! Provides compile-time `q_hash` constants and zero-heap `NQuin` constructors/decoders
4//! for the 6 canonical predicate families (28 predicates total):
5//! - Multi-scale spatial & topological predicates (`geo:*`)
6//! - Volumetric & container sidecar predicates (`q42:*`)
7//! - Kinematic, biomechanical & botanical predicates (`kin:*`, `bio:*`, `mech:*`, `phys:*`)
8//! - Sensory, acoustic & optical predicates (`sens:*`)
9//! - Epistemic & bifurcation predicates (`epi:*`)
10//! - KV-cache & LLM grounding predicates (`llm:*`)
11
12use crate::{q_hash, NQuin};
13
14// ── Family A: Multi-Scale Spatial & Topological Predicates (7) ───────────
15pub const PRED_GEO_HAS_VERTEX: u64 = q_hash("geo:hasVertex");
16pub const PRED_GEO_HAS_PACKED_CENTROID: u64 = q_hash("geo:hasPackedCentroid");
17pub const PRED_GEO_HAS_PACKED_BBOX_MIN: u64 = q_hash("geo:hasPackedBboxMin");
18pub const PRED_GEO_HAS_PACKED_BBOX_MAX: u64 = q_hash("geo:hasPackedBboxMax");
19pub const PRED_GEO_HAS_SCALE_TIER: u64 = q_hash("geo:hasScaleTier");
20pub const PRED_GEO_HAS_TOPOLOGY_CLASS: u64 = q_hash("geo:hasTopologyClass");
21pub const PRED_GEO_HAS_PORTAL_LINK: u64 = q_hash("geo:hasPortalLink");
22
23// ── Family B: Volumetric & Container Sidecar Predicates (6) ───────────────
24pub const PRED_Q42_HAS_CONTAINER_10D: u64 = q_hash("q42:hasContainer10d");
25pub const PRED_Q42_HAS_M64_CHUNK: u64 = q_hash("q42:hasM64Chunk");
26pub const PRED_Q42_HAS_EMF_CHUNK: u64 = q_hash("q42:hasEmfChunk");
27pub const PRED_Q42_HAS_SPECTRAL_SHEET_V3: u64 = q_hash("q42:hasSpectralSheetV3");
28pub const PRED_Q42_HAS_HMC_BUNDLE: u64 = q_hash("q42:hasHmcBundle");
29pub const PRED_Q42_HAS_CLUSTER_DAG: u64 = q_hash("q42:hasClusterDag");
30
31// ── Family C: Kinematic, Biomechanical & Botanical Predicates (6) ─────────
32pub const PRED_KIN_HAS_PGA_MOTOR: u64 = q_hash("kin:hasPgaMotor");
33pub const PRED_KIN_HAS_JOINT_PARENT: u64 = q_hash("kin:hasJointParent");
34pub const PBIO_HAS_HILL_MUSCLE_ALIAS: u64 = q_hash("bio:hasHillMuscle");
35pub const PRED_BIO_HAS_HILL_MUSCLE: u64 = PBIO_HAS_HILL_MUSCLE_ALIAS;
36pub const PRED_BIO_HAS_ALLOMETRIC_LAW: u64 = q_hash("bio:hasAllometricLaw");
37pub const PRED_MECH_HAS_FATIGUE_LAW: u64 = q_hash("mech:hasFatigueLaw");
38pub const PRED_PHYS_HAS_BOND_PORT: u64 = q_hash("phys:hasBondPort");
39
40// ── Family D: Sensory, Acoustic & Optical Predicates (4) ─────────────────
41pub const PRED_SENS_HAS_HOA_ORDER: u64 = q_hash("sens:hasHoaOrder");
42pub const PRED_SENS_HAS_SOFA_HRTF: u64 = q_hash("sens:hasSofaHrtf");
43pub const PRED_SENS_HAS_STOKES_VECTOR: u64 = q_hash("sens:hasStokesVector");
44pub const PRED_SENS_HAS_REFRACTIVE_INDEX: u64 = q_hash("sens:hasRefractiveIndex");
45
46// ── Family E: Epistemic & Bifurcation Predicates (3) ──────────────────────
47pub const PRED_EPI_HAS_QUANTUM_RANGE: u64 = q_hash("epi:hasQuantumRange");
48pub const PRED_EPI_HAS_BIFURCATION_WING: u64 = q_hash("epi:hasBifurcationWing");
49pub const PRED_EPI_HAS_CONSENT_RECEIPT: u64 = q_hash("epi:hasConsentReceipt");
50
51// ── Family F: KV-Cache & LLM Grounding Predicates (2) ────────────────────
52pub const PRED_LLM_HAS_KV_SLOT: u64 = q_hash("llm:hasKvSlot");
53pub const PRED_LLM_HAS_SPARSE_ATOM_CODE: u64 = q_hash("llm:hasSparseAtomCode");
54
55/// All 28 canonical predicates defined by §3.6.2.
56pub const ALL_SPATIAL_SENSORY_PREDICATES: [u64; 28] = [
57    PRED_GEO_HAS_VERTEX,
58    PRED_GEO_HAS_PACKED_CENTROID,
59    PRED_GEO_HAS_PACKED_BBOX_MIN,
60    PRED_GEO_HAS_PACKED_BBOX_MAX,
61    PRED_GEO_HAS_SCALE_TIER,
62    PRED_GEO_HAS_TOPOLOGY_CLASS,
63    PRED_GEO_HAS_PORTAL_LINK,
64    PRED_Q42_HAS_CONTAINER_10D,
65    PRED_Q42_HAS_M64_CHUNK,
66    PRED_Q42_HAS_EMF_CHUNK,
67    PRED_Q42_HAS_SPECTRAL_SHEET_V3,
68    PRED_Q42_HAS_HMC_BUNDLE,
69    PRED_Q42_HAS_CLUSTER_DAG,
70    PRED_KIN_HAS_PGA_MOTOR,
71    PRED_KIN_HAS_JOINT_PARENT,
72    PRED_BIO_HAS_HILL_MUSCLE,
73    PRED_BIO_HAS_ALLOMETRIC_LAW,
74    PRED_MECH_HAS_FATIGUE_LAW,
75    PRED_PHYS_HAS_BOND_PORT,
76    PRED_SENS_HAS_HOA_ORDER,
77    PRED_SENS_HAS_SOFA_HRTF,
78    PRED_SENS_HAS_STOKES_VECTOR,
79    PRED_SENS_HAS_REFRACTIVE_INDEX,
80    PRED_EPI_HAS_QUANTUM_RANGE,
81    PRED_EPI_HAS_BIFURCATION_WING,
82    PRED_EPI_HAS_CONSENT_RECEIPT,
83    PRED_LLM_HAS_KV_SLOT,
84    PRED_LLM_HAS_SPARSE_ATOM_CODE,
85];
86
87// ── Coordinate Packing & Scale Helpers ────────────────────────────────────
88
89/// Step in meters for scale tier `0..=7`.
90#[inline]
91pub fn scale_tier_step_meters(tier: u8) -> f32 {
92    match tier {
93        0 => 0.001,      // mm default (legacy compatible)
94        1 => 1.0e-9,     // nm
95        2 => 1.0e-6,     // um
96        3 => 1.0,        // m
97        4 => 1.0e3,      // km
98        5 => 1.0e6,      // 100 km / Mm
99        6 => 1.496e11,   // Astronomical (AU)
100        7 => 3.0857e16,  // Interstellar (Parsec)
101        _ => 0.001,
102    }
103}
104
105#[inline]
106fn sign_extend_20(v: u32) -> i32 {
107    let v = v & 0xF_FFFF;
108    if (v & 0x8_0000) != 0 {
109        (v | !0xF_FFFF) as i32
110    } else {
111        v as i32
112    }
113}
114
115/// Pack 3D floating-point coordinates `(x, y, z)` into a 60-bit payload + 3-bit scale tier.
116#[inline]
117pub fn pack_coord_with_scale(x: f32, y: f32, z: f32, scale_tier: u8) -> u64 {
118    let step = scale_tier_step_meters(scale_tier);
119    let xi = ((x / step).round() as i64) & 0xF_FFFF;
120    let yi = ((y / step).round() as i64) & 0xF_FFFF;
121    let zi = ((z / step).round() as i64) & 0xF_FFFF;
122    let tier_bits = (scale_tier as u64 & 0x7) << 60;
123    tier_bits | ((xi as u64) << 40) | ((yi as u64) << 20) | (zi as u64)
124}
125
126/// Unpack 60-bit payload + 3-bit scale tier into `(x, y, z, scale_tier)`.
127#[inline]
128pub fn unpack_coord_with_scale(object: u64) -> (f32, f32, f32, u8) {
129    let tier = ((object >> 60) & 0x7) as u8;
130    let xi = sign_extend_20(((object >> 40) & 0xF_FFFF) as u32);
131    let yi = sign_extend_20(((object >> 20) & 0xF_FFFF) as u32);
132    let zi = sign_extend_20((object & 0xF_FFFF) as u32);
133    let step = scale_tier_step_meters(tier);
134    (xi as f32 * step, yi as f32 * step, zi as f32 * step, tier)
135}
136
137// ── Zero-Heap Constructors & Decoders ─────────────────────────────────────
138
139/// Construct an `NQuin` for a 3D spatial coordinate or bounding box bound.
140#[inline]
141pub fn make_spatial_coord_quin(
142    subject: u64,
143    predicate: u64,
144    x: f32,
145    y: f32,
146    z: f32,
147    scale_tier: u8,
148    context: u64,
149    metadata: u64,
150) -> NQuin {
151    let object = pack_coord_with_scale(x, y, z, scale_tier);
152    let parity = NQuin::calculate_parity(subject, predicate, object, context, metadata);
153    NQuin {
154        subject,
155        predicate,
156        object,
157        context,
158        metadata,
159        parity,
160    }
161}
162
163/// Decode coordinates and scale tier from a spatial coordinate `NQuin`.
164#[inline]
165pub fn decode_spatial_coord_quin(quin: &NQuin) -> (f32, f32, f32, u8) {
166    unpack_coord_with_scale(quin.object)
167}
168
169/// Construct an `NQuin` linking a subject to a binary container section (.10d, .m64, .emf, etc.).
170#[inline]
171pub fn make_container_link_quin(
172    subject: u64,
173    predicate: u64,
174    container_hash: u64,
175    section_offset: u32,
176    chunk_records: u16,
177    context: u64,
178) -> NQuin {
179    let object = container_hash & 0x0FFF_FFFF_FFFF_FFFF;
180    let metadata = ((section_offset as u64) << 32) | (chunk_records as u64);
181    let parity = NQuin::calculate_parity(subject, predicate, object, context, metadata);
182    NQuin {
183        subject,
184        predicate,
185        object,
186        context,
187        metadata,
188        parity,
189    }
190}
191
192/// Decode container link payload: `(container_hash, section_offset, chunk_records)`.
193#[inline]
194pub fn decode_container_link_quin(quin: &NQuin) -> (u64, u32, u16) {
195    let container_hash = quin.object & 0x0FFF_FFFF_FFFF_FFFF;
196    let section_offset = (quin.metadata >> 32) as u32;
197    let chunk_records = (quin.metadata & 0xFFFF) as u16;
198    (container_hash, section_offset, chunk_records)
199}
200
201/// Construct an `NQuin` for a kinematic or physical property (joint parent, PGA motor slot).
202#[inline]
203pub fn make_kinematic_quin(
204    subject: u64,
205    predicate: u64,
206    parent_or_type_hash: u64,
207    motor_slot: u32,
208    context: u64,
209) -> NQuin {
210    let object = parent_or_type_hash & 0x0FFF_FFFF_FFFF_FFFF;
211    let metadata = motor_slot as u64;
212    let parity = NQuin::calculate_parity(subject, predicate, object, context, metadata);
213    NQuin {
214        subject,
215        predicate,
216        object,
217        context,
218        metadata,
219        parity,
220    }
221}
222
223/// Decode kinematic quin: `(parent_or_type_hash, motor_slot)`.
224#[inline]
225pub fn decode_kinematic_quin(quin: &NQuin) -> (u64, u32) {
226    (quin.object & 0x0FFF_FFFF_FFFF_FFFF, quin.metadata as u32)
227}
228
229/// Construct an `NQuin` for sensory or acoustic attachments (Ambisonics HOA order, SOFA HRTF).
230#[inline]
231pub fn make_sensory_quin(
232    subject: u64,
233    predicate: u64,
234    asset_hash: u64,
235    hoa_order_or_band: u32,
236    context: u64,
237) -> NQuin {
238    let object = asset_hash & 0x0FFF_FFFF_FFFF_FFFF;
239    let metadata = hoa_order_or_band as u64;
240    let parity = NQuin::calculate_parity(subject, predicate, object, context, metadata);
241    NQuin {
242        subject,
243        predicate,
244        object,
245        context,
246        metadata,
247        parity,
248    }
249}
250
251/// Decode sensory quin: `(asset_hash, hoa_order_or_band)`.
252#[inline]
253pub fn decode_sensory_quin(quin: &NQuin) -> (u64, u32) {
254    (quin.object & 0x0FFF_FFFF_FFFF_FFFF, quin.metadata as u32)
255}
256
257/// Construct an `NQuin` linking a subject to an epistemic quantum range or consent receipt.
258#[inline]
259pub fn make_epistemic_quin(
260    subject: u64,
261    predicate: u64,
262    value: u64,
263    context: u64,
264    lamport_clock: u32,
265) -> NQuin {
266    let metadata = lamport_clock as u64;
267    let parity = NQuin::calculate_parity(subject, predicate, value, context, metadata);
268    NQuin {
269        subject,
270        predicate,
271        object: value,
272        context,
273        metadata,
274        parity,
275    }
276}
277
278/// Decode epistemic quin: returns `quin.object`.
279#[inline]
280pub fn decode_epistemic_quin(quin: &NQuin) -> u64 {
281    quin.object
282}
283
284/// Construct an `NQuin` linking a volumetric node to an LLM KV slot and prompt page.
285#[inline]
286pub fn make_llm_grounding_quin(
287    subject: u64,
288    predicate: u64,
289    kv_slot: u32,
290    parent_page_id: u64,
291    context: u64,
292) -> NQuin {
293    let object = kv_slot as u64;
294    let metadata = parent_page_id;
295    let parity = NQuin::calculate_parity(subject, predicate, object, context, metadata);
296    NQuin {
297        subject,
298        predicate,
299        object,
300        context,
301        metadata,
302        parity,
303    }
304}
305
306/// Decode LLM grounding quin: `(kv_slot, parent_page_id)`.
307#[inline]
308pub fn decode_llm_grounding_quin(quin: &NQuin) -> (u32, u64) {
309    (quin.object as u32, quin.metadata)
310}
311
312#[cfg(test)]
313mod tests {
314    use super::*;
315
316    #[test]
317    fn all_28_predicates_are_unique_with_zero_collisions() {
318        let preds = ALL_SPATIAL_SENSORY_PREDICATES;
319        assert_eq!(preds.len(), 28);
320        for i in 0..preds.len() {
321            for j in (i + 1)..preds.len() {
322                assert_ne!(
323                    preds[i], preds[j],
324                    "Collision detected between predicate index {i} and {j}"
325                );
326            }
327        }
328    }
329
330    #[test]
331    fn spatial_coord_round_trip_millimeter() {
332        let quin = make_spatial_coord_quin(100, PRED_GEO_HAS_VERTEX, 1.25, -2.5, 3.75, 0, 0, 0);
333        assert!(quin.verify_ecc_parity());
334        let (x, y, z, tier) = decode_spatial_coord_quin(&quin);
335        assert_eq!(tier, 0);
336        assert!((x - 1.25).abs() < 0.002);
337        assert!((y - -2.5).abs() < 0.002);
338        assert!((z - 3.75).abs() < 0.002);
339    }
340
341    #[test]
342    fn spatial_coord_round_trip_meter_tier() {
343        let quin = make_spatial_coord_quin(101, PRED_GEO_HAS_PACKED_CENTROID, 120.0, -45.0, 300.0, 3, 0, 0);
344        assert!(quin.verify_ecc_parity());
345        let (x, y, z, tier) = decode_spatial_coord_quin(&quin);
346        assert_eq!(tier, 3);
347        assert!((x - 120.0).abs() < 1.0);
348        assert!((y - -45.0).abs() < 1.0);
349        assert!((z - 300.0).abs() < 1.0);
350    }
351
352    #[test]
353    fn container_link_round_trip() {
354        let quin = make_container_link_quin(200, PRED_Q42_HAS_M64_CHUNK, 0x1234_5678_9ABC_DEF0, 4096, 64, 1);
355        assert!(quin.verify_ecc_parity());
356        let (hash, offset, chunks) = decode_container_link_quin(&quin);
357        assert_eq!(hash, 0x1234_5678_9ABC_DEF0 & 0x0FFF_FFFF_FFFF_FFFF);
358        assert_eq!(offset, 4096);
359        assert_eq!(chunks, 64);
360    }
361
362    #[test]
363    fn kinematic_round_trip() {
364        let quin = make_kinematic_quin(300, PRED_KIN_HAS_PGA_MOTOR, 0x9999_8888, 12, 0);
365        assert!(quin.verify_ecc_parity());
366        let (hash, slot) = decode_kinematic_quin(&quin);
367        assert_eq!(hash, 0x9999_8888);
368        assert_eq!(slot, 12);
369    }
370
371    #[test]
372    fn sensory_round_trip() {
373        let quin = make_sensory_quin(400, PRED_SENS_HAS_HOA_ORDER, 0x7777, 3, 0);
374        assert!(quin.verify_ecc_parity());
375        let (hash, hoa) = decode_sensory_quin(&quin);
376        assert_eq!(hash, 0x7777);
377        assert_eq!(hoa, 3);
378    }
379
380    #[test]
381    fn epistemic_round_trip() {
382        let quin = make_epistemic_quin(500, PRED_EPI_HAS_QUANTUM_RANGE, 998, 0, 42);
383        assert!(quin.verify_ecc_parity());
384        assert_eq!(decode_epistemic_quin(&quin), 998);
385        assert_eq!(quin.extract_lamport_clock(), 42);
386    }
387
388    #[test]
389    fn llm_grounding_round_trip() {
390        let quin = make_llm_grounding_quin(600, PRED_LLM_HAS_KV_SLOT, 128, 0xABCDE, 0);
391        assert!(quin.verify_ecc_parity());
392        let (slot, page) = decode_llm_grounding_quin(&quin);
393        assert_eq!(slot, 128);
394        assert_eq!(page, 0xABCDE);
395    }
396}