Skip to main content

qualia_core_db/tensor/
bake_pipeline.rs

1//! Cold-path NQuin → Tensor10D baking (ingest / encode tier).
2//!
3//! Hot-path queries read baked SOA volumes; this module runs at ingest only.
4
5use crate::{q_hash, NQuin};
6
7use super::Tensor10D;
8
9pub const PRED_GEO_VERTEX: u64 = q_hash("geo:hasVertex");
10pub const PRED_GEO_PACKED_CENTROID: u64 = q_hash("geo:hasPackedCentroid");
11pub const PRED_GEO_PACKED_BBOX_MIN: u64 = q_hash("geo:hasPackedBboxMin");
12pub const PRED_GEO_PACKED_BBOX_MAX: u64 = q_hash("geo:hasPackedBboxMax");
13
14/// Link to a registered acoustic resource. Registry indices are not file digests.
15pub const PRED_HAS_SPECTRAL_SHEET: u64 = q_hash("q42:hasSpectralSheet");
16
17/// Scale tier for multi-scale spatial coordinate packing (§2.3)
18#[repr(u8)]
19#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
20pub enum ScaleTier {
21    /// 1 mm (10^-3 m) per LSB — backward-compatible legacy default
22    MillimeterDefault = 0,
23    /// 10^-9 m
24    Nanometer = 1,
25    /// 10^-6 m
26    Micrometer = 2,
27    /// 10^0 m (1 meter)
28    Meter = 3,
29    /// 10^3 m (1 kilometer)
30    Kilometer = 4,
31    /// 10^6 m (1 megameter)
32    Megameter = 5,
33    /// 10^9 m (1 gigameter / astronomical)
34    Astronomical = 6,
35    /// 10^12 m (1 terameter / parsec tier)
36    Parsec = 7,
37}
38
39impl Default for ScaleTier {
40    fn default() -> Self {
41        ScaleTier::MillimeterDefault
42    }
43}
44
45impl ScaleTier {
46    /// Map canonical scale tier exponent S in [0..7] (step = 10^(3*S - 9)) to ScaleTier.
47    pub fn from_canonical_exponent_tier(s: u8) -> Self {
48        match s {
49            0 => ScaleTier::Nanometer,
50            1 => ScaleTier::Micrometer,
51            2 => ScaleTier::MillimeterDefault,
52            3 => ScaleTier::Meter,
53            4 => ScaleTier::Kilometer,
54            5 => ScaleTier::Megameter,
55            6 => ScaleTier::Astronomical,
56            7 => ScaleTier::Parsec,
57            _ => ScaleTier::MillimeterDefault,
58        }
59    }
60
61    /// Decode raw 3-bit value (bits 60..62).
62    pub fn from_u8(raw: u8) -> Self {
63        match raw & 0x7 {
64            0 => ScaleTier::MillimeterDefault,
65            1 => ScaleTier::Nanometer,
66            2 => ScaleTier::Micrometer,
67            3 => ScaleTier::Meter,
68            4 => ScaleTier::Kilometer,
69            5 => ScaleTier::Megameter,
70            6 => ScaleTier::Astronomical,
71            7 => ScaleTier::Parsec,
72            _ => ScaleTier::MillimeterDefault,
73        }
74    }
75
76    /// Metric step in meters per LSB.
77    pub fn step_meters(self) -> f64 {
78        match self {
79            ScaleTier::MillimeterDefault => 1e-3,
80            ScaleTier::Nanometer => 1e-9,
81            ScaleTier::Micrometer => 1e-6,
82            ScaleTier::Meter => 1.0,
83            ScaleTier::Kilometer => 1e3,
84            ScaleTier::Megameter => 1e6,
85            ScaleTier::Astronomical => 1e9,
86            ScaleTier::Parsec => 1e12,
87        }
88    }
89}
90
91/// Encode metric coordinates in meters into a 64-bit packed object with scale tier.
92#[inline]
93pub fn encode_scaled_coord(x_m: f64, y_m: f64, z_m: f64, tier: ScaleTier) -> u64 {
94    let step = tier.step_meters();
95    let xi = (x_m / step).round().clamp(-524288.0, 524287.0) as i64 & 0xFFFFF;
96    let yi = (y_m / step).round().clamp(-524288.0, 524287.0) as i64 & 0xFFFFF;
97    let zi = (z_m / step).round().clamp(-524288.0, 524287.0) as i64 & 0xFFFFF;
98    let tier_bits = ((tier as u8 as u64) & 0x7) << 60;
99    tier_bits | ((xi as u64) << 40) | ((yi as u64) << 20) | (zi as u64)
100}
101
102/// Decode a 64-bit packed object into coordinates in meters along with its scale tier.
103#[inline]
104pub fn decode_scaled_coord(object: u64) -> (f64, f64, f64, ScaleTier) {
105    let tier_raw = ((object >> 60) & 0x7) as u8;
106    let tier = ScaleTier::from_u8(tier_raw);
107    let step = tier.step_meters();
108    let xi = sign_extend_20(((object >> 40) & 0xFFFFF) as u32);
109    let yi = sign_extend_20(((object >> 20) & 0xFFFFF) as u32);
110    let zi = sign_extend_20((object & 0xFFFFF) as u32);
111    (xi as f64 * step, yi as f64 * step, zi as f64 * step, tier)
112}
113
114/// Migrate a legacy unscaled millimeter Quin to a target scale tier.
115pub fn migrate_unscaled_mm_quin(quin: &NQuin, target_tier: ScaleTier) -> NQuin {
116    let (x, y, z) = decode_packed_coord(quin.object);
117    let new_object = encode_scaled_coord(x as f64, y as f64, z as f64, target_tier);
118    let mut updated = *quin;
119    updated.object = new_object;
120    updated.parity = updated.subject ^ updated.predicate ^ updated.object ^ updated.context;
121    updated
122}
123
124/// Zero-heap canonical path from the complete final-byte BLAKE3 digest.
125/// Returns0 without mutation when caller capacity is insufficient.
126pub fn audio_sidecar_relpath(digest: &[u8; 32], out: &mut [u8]) -> usize {
127    const PREFIX: &[u8] = b"spectral/audio/";
128    const SUFFIX: &[u8] = b".qac";
129    const HEX: &[u8; 16] = b"0123456789abcdef";
130    let need = PREFIX.len() + 64 + SUFFIX.len();
131    if out.len() < need {
132        return 0;
133    }
134    out[..PREFIX.len()].copy_from_slice(PREFIX);
135    for (i, byte) in digest.iter().enumerate() {
136        out[PREFIX.len() + i * 2] = HEX[usize::from(byte >> 4)];
137        out[PREFIX.len() + i * 2 + 1] = HEX[usize::from(byte & 15)];
138    }
139    out[PREFIX.len() + 64..need].copy_from_slice(SUFFIX);
140    need
141}
142
143/// σ sheet index from baked NQuin object when `q42:hasSpectralSheet` is present.
144#[inline]
145pub fn sigma_sheet_index_from_nquin(nquin: &NQuin) -> Option<u32> {
146    let pred = nquin.predicate & 0x0FFF_FFFF_FFFF_FFFF;
147    if pred != (PRED_HAS_SPECTRAL_SHEET & 0x0FFF_FFFF_FFFF_FFFF) {
148        return None;
149    }
150    let idx = (nquin.object & 0x0FFF_FFFF_FFFF_FFFF) as u32;
151    Some(idx)
152}
153
154/// Decode `spatial_encode_wasm` packed coordinates from an object field.
155///
156/// When bits 60..62 are 0 (ScaleTier::MillimeterDefault), returns (xi / 1000.0, yi / 1000.0, zi / 1000.0).
157/// When bits 60..62 are 1..7, scales by the corresponding tier step in meters.
158#[inline]
159pub fn decode_packed_coord(object: u64) -> (f32, f32, f32) {
160    let xi = sign_extend_20(((object >> 40) & 0xfffff) as u32);
161    let yi = sign_extend_20(((object >> 20) & 0xfffff) as u32);
162    let zi = sign_extend_20((object & 0xfffff) as u32);
163    let tier_raw = ((object >> 60) & 0x7) as u8;
164    if tier_raw == 0 {
165        (xi as f32 / 1000.0, yi as f32 / 1000.0, zi as f32 / 1000.0)
166    } else {
167        let step = ScaleTier::from_u8(tier_raw).step_meters() as f32;
168        (xi as f32 * step, yi as f32 * step, zi as f32 * step)
169    }
170}
171
172#[inline]
173fn sign_extend_20(v: u32) -> i32 {
174    let v = v & 0xfffff;
175    if v & 0x8_0000 != 0 {
176        (v | !0xfffff) as i32
177    } else {
178        v as i32
179    }
180}
181
182/// True when the Quin carries a baked geo coordinate payload (not a hash-proxy xyz).
183#[inline]
184pub fn is_geo_vertex_quin(nquin: &NQuin) -> bool {
185    let masked_7f = nquin.predicate & 0x7FFF_FFFF_FFFF_FF00;
186    let masked_0f = nquin.predicate & 0x0FFF_FFFF_FFFF_FFFF;
187    let matches = |pred: u64| masked_7f == pred || masked_0f == (pred & 0x0FFF_FFFF_FFFF_FFFF);
188    matches(PRED_GEO_VERTEX)
189        || matches(PRED_GEO_PACKED_CENTROID)
190        || matches(PRED_GEO_PACKED_BBOX_MIN)
191        || matches(PRED_GEO_PACKED_BBOX_MAX)
192}
193
194/// Semantic xyz: packed geo coords when present, else legacy hash spread.
195#[inline]
196pub fn semantic_xyz_from_nquin(nquin: &NQuin) -> (f32, f32, f32) {
197    if is_geo_vertex_quin(nquin) && (nquin.object >> 63) == 0 {
198        return decode_packed_coord(nquin.object);
199    }
200    let hash = nquin.object & 0x0FFF_FFFF_FFFF_FFFF;
201    let x = (hash & 0xFFFF) as f32 / 65535.0;
202    let y = ((hash >> 16) & 0xFFFF) as f32 / 65535.0;
203    let z = ((hash >> 32) & 0xFFFF) as f32 / 65535.0;
204    (x, y, z)
205}
206
207/// Bake a single NQuin into a ground-truth Tensor10D node.
208#[inline]
209pub fn bake_quin_to_tensor(nquin: &NQuin) -> Tensor10D {
210    let q = if (nquin.metadata >> 60) & 0xF != 0 {
211        0.25
212    } else {
213        0.0
214    };
215    let v = ((nquin.context >> 32) & 0x7) as f32;
216    let w = ((nquin.context >> 40) & 0xF) as f32;
217    let (x, y, z) = semantic_xyz_from_nquin(nquin);
218    let t = ((nquin.metadata >> 32) & 0x1FFF_FFFF) as f32;
219    let payload = nquin.metadata & 0xFFFF_FFFF;
220    let alpha = (payload & 0xFF) as f32 / 255.0;
221    let mu = ((payload >> 8) & 0xFF) as f32 / 255.0;
222    let sigma = ((payload >> 16) & 0xFF) as f32 / 255.0;
223    if q > 0.0 {
224        Tensor10D::parallel_context(q, v, w, x, y, z, t, alpha.max(0.1), mu, sigma)
225    } else {
226        Tensor10D::ground_truth(v, w, x, y, z, t, alpha.max(0.1), mu, sigma)
227    }
228}
229
230/// Write baked tensors into caller buffer; returns count written.
231pub fn bake_quins_into(quins: &[NQuin], out: &mut [Tensor10D]) -> usize {
232    let n = quins.len().min(out.len());
233    for i in 0..n {
234        out[i] = bake_quin_to_tensor(&quins[i]);
235    }
236    n
237}
238
239#[cfg(test)]
240mod tests {
241    use super::*;
242    use crate::NQuin;
243
244    fn pack_coord(x: f32, y: f32, z: f32) -> u64 {
245        let xi = (x * 1000.0).round() as i64 & 0xfffff;
246        let yi = (y * 1000.0).round() as i64 & 0xfffff;
247        let zi = (z * 1000.0).round() as i64 & 0xfffff;
248        ((xi as u64) << 40) | ((yi as u64) << 20) | (zi as u64)
249    }
250
251    #[test]
252    fn packed_coord_round_trip() {
253        let (x, y, z) = decode_packed_coord(pack_coord(1.25, -2.5, 3.75));
254        assert!((x - 1.25).abs() < 0.002);
255        assert!((y + 2.5).abs() < 0.002);
256        assert!((z - 3.75).abs() < 0.002);
257    }
258
259    #[test]
260    fn audio_sidecar_path_format() {
261        let mut digest = [0u8; 32];
262        digest[0] = 0xab;
263        digest[31] = 0xcd;
264        let mut buf = [0xa5; 96];
265        let n = audio_sidecar_relpath(&digest, &mut buf);
266        assert_eq!(n, b"spectral/audio/".len() + 64 + b".qac".len());
267        assert_eq!(
268            std::str::from_utf8(&buf[..n]).unwrap(),
269            "spectral/audio/ab000000000000000000000000000000000000000000000000000000000000cd.qac"
270        );
271        assert!(buf[n..].iter().all(|x| *x == 0xa5));
272        let mut small = [0xa5; 82];
273        assert_eq!(audio_sidecar_relpath(&digest, &mut small), 0);
274        assert!(small.iter().all(|x| *x == 0xa5));
275    }
276
277    #[test]
278    fn spectral_sheet_predicate_extracts_index() {
279        let mut q = NQuin::default();
280        q.predicate = PRED_HAS_SPECTRAL_SHEET;
281        q.object = 42;
282        assert_eq!(sigma_sheet_index_from_nquin(&q), Some(42));
283    }
284
285    #[test]
286    fn geo_vertex_bake_uses_packed_xyz() {
287        let mut q = NQuin::default();
288        q.predicate = PRED_GEO_VERTEX;
289        q.object = pack_coord(0.1, 0.2, 0.3);
290        q.metadata = 42 << 32;
291        let t = bake_quin_to_tensor(&q);
292        assert!((t.x - 0.1).abs() < 0.002);
293        assert!((t.y - 0.2).abs() < 0.002);
294        assert!((t.z - 0.3).abs() < 0.002);
295        assert!(t.is_ground_truth());
296    }
297
298    #[test]
299    fn test_multi_scale_packing_across_all_eight_tiers() {
300        let tiers = [
301            ScaleTier::MillimeterDefault,
302            ScaleTier::Nanometer,
303            ScaleTier::Micrometer,
304            ScaleTier::Meter,
305            ScaleTier::Kilometer,
306            ScaleTier::Megameter,
307            ScaleTier::Astronomical,
308            ScaleTier::Parsec,
309        ];
310
311        for tier in tiers {
312            let step = tier.step_meters();
313            let xm = 42.0 * step;
314            let ym = -17.0 * step;
315            let zm = 100.0 * step;
316
317            let packed = encode_scaled_coord(xm, ym, zm, tier);
318            let (dx, dy, dz, decoded_tier) = decode_scaled_coord(packed);
319
320            assert_eq!(decoded_tier, tier);
321            assert!((dx - xm).abs() / step < 0.5, "Tier {tier:?} x error");
322            assert!((dy - ym).abs() / step < 0.5, "Tier {tier:?} y error");
323            assert!((dz - zm).abs() / step < 0.5, "Tier {tier:?} z error");
324
325            // Also test via decode_packed_coord
326            let (px, py, pz) = decode_packed_coord(packed);
327            assert!((px as f64 - xm).abs() / step < 0.5);
328            assert!((py as f64 - ym).abs() / step < 0.5);
329            assert!((pz as f64 - zm).abs() / step < 0.5);
330        }
331    }
332
333    #[test]
334    fn test_canonical_exponent_mapping() {
335        assert_eq!(
336            ScaleTier::from_canonical_exponent_tier(0),
337            ScaleTier::Nanometer
338        );
339        assert_eq!(
340            ScaleTier::from_canonical_exponent_tier(1),
341            ScaleTier::Micrometer
342        );
343        assert_eq!(
344            ScaleTier::from_canonical_exponent_tier(2),
345            ScaleTier::MillimeterDefault
346        );
347        assert_eq!(ScaleTier::from_canonical_exponent_tier(3), ScaleTier::Meter);
348        assert_eq!(
349            ScaleTier::from_canonical_exponent_tier(4),
350            ScaleTier::Kilometer
351        );
352        assert_eq!(
353            ScaleTier::from_canonical_exponent_tier(5),
354            ScaleTier::Megameter
355        );
356        assert_eq!(
357            ScaleTier::from_canonical_exponent_tier(6),
358            ScaleTier::Astronomical
359        );
360        assert_eq!(
361            ScaleTier::from_canonical_exponent_tier(7),
362            ScaleTier::Parsec
363        );
364    }
365
366    #[test]
367    fn test_geo_predicates_and_migration() {
368        let preds = [
369            PRED_GEO_VERTEX,
370            PRED_GEO_PACKED_CENTROID,
371            PRED_GEO_PACKED_BBOX_MIN,
372            PRED_GEO_PACKED_BBOX_MAX,
373        ];
374        for pred in preds {
375            let mut q = NQuin::default();
376            q.predicate = pred;
377            assert!(is_geo_vertex_quin(&q));
378        }
379
380        // Migration from unscaled mm to meter tier
381        let mut q = NQuin::default();
382        q.predicate = PRED_GEO_PACKED_CENTROID;
383        q.object = pack_coord(5.0, -10.0, 15.0); // 5m, -10m, 15m in mm
384        let migrated = migrate_unscaled_mm_quin(&q, ScaleTier::Meter);
385
386        let (x, y, z, tier) = decode_scaled_coord(migrated.object);
387        assert_eq!(tier, ScaleTier::Meter);
388        assert!((x - 5.0).abs() < 1e-3);
389        assert!((y - (-10.0)).abs() < 1e-3);
390        assert!((z - 15.0).abs() < 1e-3);
391    }
392}