Skip to main content

qualia_core_db/tensor/
mod.rs

1//! 10D Volumetric Tensor System
2//!
3//! Implements the 10-dimensional tensor coordinate system [q, v, w, x, y, z, t, α, μ, σ]
4//! for the Q42 volumetric tensor system with zero-heap hot path guarantees.
5
6pub mod bake_pipeline;
7pub mod buffer_export;
8pub mod coordinate;
9pub mod gsr;
10pub mod kv_provenance;
11pub mod manifold;
12pub mod payload;
13pub mod q42_integration;
14pub mod quantum;
15pub mod resident_substrate;
16pub mod spacetime;
17pub mod spectral;
18pub mod topology;
19#[cfg(feature = "gpu-runtime")]
20pub mod volume_gpu;
21
22pub use bake_pipeline::ScaleTier;
23pub use quantum::QuantumContextRange;
24pub use spacetime::HierarchicalSpacetimeCoord;
25
26use bytemuck::{Pod, Zeroable};
27use serde::{Deserialize, Serialize};
28
29/// 10D Tensor coordinate system [q, v, w, x, y, z, t, α, μ, σ]
30///
31/// Zero-heap compatible, stack-allocated structure for hot path operations.
32/// Uses fixed-size f32 values for GPU/SIMD compatibility and quantization.
33/// In the `.10d` v2 identity model, this is the structured manifold address
34/// component, interpreted with its declared domain/profile and typed parts
35/// that describe shape and behavior. It is not a digest or a globally unique
36/// identifier by itself; hashes may index or verify the identity but do not
37/// replace these coordinates or their declared semantics.
38#[repr(C)]
39#[derive(Debug, Clone, Copy, PartialEq, Pod, Zeroable, Serialize, Deserialize)]
40pub struct Tensor10D {
41    /// Quantum Context / Superposition Index (10th dimension)
42    /// q = 0: Collapsed Ground Truth
43    /// q > 0: Parallel epistemic contexts, pending resolutions
44    pub q: f32,
45
46    /// Topological / Algebraic Variety Class
47    /// v = 0: Euclidean, v = 1: Cyclic/Toroidal, v = 2: Hyperbolic/Tree, v = 3+: Boundary Cliques
48    pub v: f32,
49
50    /// Manifold / Domain Index (Multi-Head Bifurcation)
51    /// w = 0: Medical, w = 1: Legal, w = 2: Personal, w = 3: Environmental, w = 4: Socioeconomic
52    pub w: f32,
53
54    /// Semantic Topology X coordinate
55    pub x: f32,
56
57    /// Semantic Topology Y coordinate
58    pub y: f32,
59
60    /// Semantic Topology Z coordinate
61    pub z: f32,
62
63    /// Coordinate Time — the 4th dimension of spacetime (T67 reconciled).
64    ///
65    /// `t` is a **Coordinate** axis: it participates in distance queries
66    /// alongside `x`, `y`, `z`, `α`, `σ`. It is NOT the provenance
67    /// carrier. The earlier "Provenance Ledger" label was incorrect and
68    /// has been reconciled with `container_10d/axis_role.rs` (T67).
69    ///
70    /// Cross-reference: T14 (name the two tens) and T15 (resolve t vs μ).
71    pub t: f32,
72
73    /// Spectral Amplitude / Dynamic Range / Confidence Weight
74    pub alpha: f32,
75
76    /// Provenance Weight / Carrier — epistemic metadata lane (T67 reconciled).
77    ///
78    /// `μ` is the **CoordinateCarrier**: a dual-role axis that is both a
79    /// measured coordinate AND the in-band provenance carrier. This is
80    /// distinct from `t` (coordinate time). The provenance/consent lane
81    /// is `μ`, not `t`. See `container_10d/axis_role.rs` for the
82    /// normative axis-role taxonomy.
83    ///
84    /// Cross-reference: T14 (name the two tens) and T15 (resolve t vs μ).
85    pub mu: f32,
86
87    /// Spectral Signature / Logical Class Index
88    pub sigma: f32,
89}
90
91impl Default for Tensor10D {
92    fn default() -> Self {
93        Self {
94            q: 0.0,
95            v: 0.0,
96            w: 0.0,
97            x: 0.0,
98            y: 0.0,
99            z: 0.0,
100            t: 0.0,
101            alpha: 1.0,
102            mu: 0.0,
103            sigma: 0.0,
104        }
105    }
106}
107
108impl Tensor10D {
109    /// Creates a new tensor with specified coordinates
110    #[inline]
111    pub fn new(
112        q: f32,
113        v: f32,
114        w: f32,
115        x: f32,
116        y: f32,
117        z: f32,
118        t: f32,
119        alpha: f32,
120        mu: f32,
121        sigma: f32,
122    ) -> Self {
123        Self {
124            q,
125            v,
126            w,
127            x,
128            y,
129            z,
130            t,
131            alpha,
132            mu,
133            sigma,
134        }
135    }
136
137    /// Creates a ground truth tensor (q = 0)
138    #[inline]
139    pub fn ground_truth(
140        v: f32,
141        w: f32,
142        x: f32,
143        y: f32,
144        z: f32,
145        t: f32,
146        alpha: f32,
147        mu: f32,
148        sigma: f32,
149    ) -> Self {
150        Self {
151            q: 0.0,
152            v,
153            w,
154            x,
155            y,
156            z,
157            t,
158            alpha,
159            mu,
160            sigma,
161        }
162    }
163
164    /// Creates a parallel context tensor (q > 0)
165    #[inline]
166    pub fn parallel_context(
167        q: f32,
168        v: f32,
169        w: f32,
170        x: f32,
171        y: f32,
172        z: f32,
173        t: f32,
174        alpha: f32,
175        mu: f32,
176        sigma: f32,
177    ) -> Self {
178        Self {
179            q,
180            v,
181            w,
182            x,
183            y,
184            z,
185            t,
186            alpha,
187            mu,
188            sigma,
189        }
190    }
191
192    /// Returns true if this is a ground truth tensor (q = 0)
193    #[inline]
194    pub fn is_ground_truth(&self) -> bool {
195        self.q == 0.0
196    }
197
198    /// Calculates Euclidean distance between spatial coordinates (x, y, z)
199    #[inline]
200    pub fn spatial_distance(&self, other: &Self) -> f32 {
201        let dx = self.x - other.x;
202        let dy = self.y - other.y;
203        let dz = self.z - other.z;
204        (dx * dx + dy * dy + dz * dz).sqrt()
205    }
206
207    /// Calculates full 10D distance considering topological adjustments
208    #[inline]
209    pub fn full_distance(&self, other: &Self) -> f32 {
210        match self.v as u32 {
211            0 => self.euclidean_distance(other),
212            1 => self.cyclic_distance(other),
213            2 => self.hyperbolic_distance(other),
214            3 => self.boundary_distance(other),
215            4 => self.spherical_healpix_distance(other),
216            5 => self.lorentzian_spacetime_distance(other),
217            6 => self.multiply_connected_portal_distance(other),
218            _ => self.boundary_distance(other),
219        }
220    }
221
222    /// Euclidean distance (standard straight-line)
223    #[inline]
224    fn euclidean_distance(&self, other: &Self) -> f32 {
225        let spatial = self.spatial_distance(other);
226        let temporal = (self.t - other.t).abs();
227        let spectral = ((self.alpha - other.alpha).powi(2)
228            + (self.mu - other.mu).powi(2)
229            + (self.sigma - other.sigma).powi(2))
230        .sqrt();
231        (spatial.powi(2) + temporal.powi(2) + spectral.powi(2)).sqrt()
232    }
233
234    /// Cyclic distance (modulo arithmetic for toroidal topology)
235    #[inline]
236    fn cyclic_distance(&self, other: &Self) -> f32 {
237        let dx = (self.x - other.x).abs().min(1.0 - (self.x - other.x).abs());
238        let dy = (self.y - other.y).abs().min(1.0 - (self.y - other.y).abs());
239        let dz = (self.z - other.z).abs().min(1.0 - (self.z - other.z).abs());
240        (dx * dx + dy * dy + dz * dz).sqrt()
241    }
242
243    /// Hyperbolic distance (exponential hierarchy)
244    #[inline]
245    fn hyperbolic_distance(&self, other: &Self) -> f32 {
246        let dx = (self.x - other.x).abs();
247        let dy = (self.y - other.y).abs();
248        let dz = (self.z - other.z).abs();
249        (dx.exp() + dy.exp() + dz.exp()).ln()
250    }
251
252    /// Boundary clique distance (byte comparison)
253    #[inline]
254    fn boundary_distance(&self, other: &Self) -> f32 {
255        if self.v == other.v {
256            0.0
257        } else {
258            1.0
259        }
260    }
261
262    /// Spherical HEALPix distance (folds x, y, z)
263    #[inline]
264    fn spherical_healpix_distance(&self, other: &Self) -> f32 {
265        topology::TopologyClass::SphericalHealpix
266            .calculate_distance((self.x, self.y, self.z), (other.x, other.y, other.z))
267    }
268
269    /// Lorentzian spacetime distance (folds x, y, z, t)
270    #[inline]
271    fn lorentzian_spacetime_distance(&self, other: &Self) -> f32 {
272        let dx = self.x - other.x;
273        let dy = self.y - other.y;
274        let dz = self.z - other.z;
275        let dt = self.t - other.t;
276        (-(dt * dt) + (dx * dx + dy * dy + dz * dz)).abs().sqrt()
277    }
278
279    /// Multiply-connected portal distance (folds x, y, z)
280    #[inline]
281    fn multiply_connected_portal_distance(&self, other: &Self) -> f32 {
282        topology::TopologyClass::MultiplyConnectedPortal
283            .calculate_distance((self.x, self.y, self.z), (other.x, other.y, other.z))
284    }
285
286    /// Returns true if this is a parallel context tensor (q > 0)
287    #[inline]
288    pub fn is_parallel_context(&self) -> bool {
289        self.q > 0.0
290    }
291}
292
293#[cfg(test)]
294mod tests {
295    use super::*;
296
297    #[test]
298    fn test_tensor_default() {
299        let tensor = Tensor10D::default();
300        assert_eq!(tensor.q, 0.0);
301        assert_eq!(tensor.v, 0.0);
302        assert_eq!(tensor.w, 0.0);
303        assert!(tensor.is_ground_truth());
304        assert!(!tensor.is_parallel_context());
305    }
306
307    #[test]
308    fn test_tensor_new() {
309        let tensor = Tensor10D::new(1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0);
310        assert_eq!(tensor.q, 1.0);
311        assert_eq!(tensor.v, 2.0);
312        assert_eq!(tensor.w, 3.0);
313        assert!(tensor.is_parallel_context());
314    }
315
316    #[test]
317    fn test_ground_truth() {
318        let tensor = Tensor10D::ground_truth(0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 1.0, 0.0, 0.0);
319        assert!(tensor.is_ground_truth());
320        assert!(!tensor.is_parallel_context());
321        assert_eq!(tensor.q, 0.0);
322    }
323
324    #[test]
325    fn test_spatial_distance() {
326        let t1 = Tensor10D::new(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0);
327        let t2 = Tensor10D::new(0.0, 0.0, 0.0, 3.0, 4.0, 0.0, 0.0, 1.0, 0.0, 0.0);
328        let distance = t1.spatial_distance(&t2);
329        assert!((distance - 5.0).abs() < 0.001); // 3-4-5 triangle
330    }
331
332    #[test]
333    fn test_full_distance() {
334        let t1 = Tensor10D::default();
335        let t2 = Tensor10D::default();
336        assert_eq!(t1.full_distance(&t2), 0.0);
337    }
338
339    #[test]
340    fn test_pod_zeroable() {
341        let tensor = Tensor10D::default();
342        assert_eq!(tensor.q, 0.0);
343        assert_eq!(tensor.v, 0.0);
344        let t1 = Tensor10D::new(1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0);
345        let bytes: &[u8] = bytemuck::bytes_of(&t1);
346        assert_eq!(bytes.len(), std::mem::size_of::<Tensor10D>());
347    }
348
349    // P7.9 — Axis-completeness regression guards (option b)
350    #[test]
351    fn p7_9_v0_euclidean_alpha_changes_distance() {
352        let base = Tensor10D::default();
353        let mut perturbed = base;
354        perturbed.alpha += 0.25;
355        assert!(base.full_distance(&perturbed) > 1e-6);
356    }
357
358    #[test]
359    fn p7_9_v0_euclidean_mu_changes_distance() {
360        let base = Tensor10D::default();
361        let mut perturbed = base;
362        perturbed.mu += 0.25;
363        assert!(base.full_distance(&perturbed) > 1e-6);
364    }
365
366    #[test]
367    fn p7_9_v0_euclidean_sigma_changes_distance() {
368        let base = Tensor10D::default();
369        let mut perturbed = base;
370        perturbed.sigma += 0.25;
371        assert!(base.full_distance(&perturbed) > 1e-6);
372    }
373
374    #[test]
375    fn p7_9_v0_euclidean_t_changes_distance() {
376        let base = Tensor10D::default();
377        let mut perturbed = base;
378        perturbed.t += 0.25;
379        assert!(base.full_distance(&perturbed) > 1e-6);
380    }
381
382    #[test]
383    fn p7_9_v1_cyclic_alpha_does_not_change_distance() {
384        let mut base = Tensor10D::default();
385        base.v = 1.0;
386        let mut perturbed = base;
387        perturbed.alpha += 0.25;
388        assert!(base.full_distance(&perturbed) < 1e-6);
389    }
390
391    #[test]
392    fn p7_9_v1_cyclic_sigma_does_not_change_distance() {
393        let mut base = Tensor10D::default();
394        base.v = 1.0;
395        let mut perturbed = base;
396        perturbed.sigma += 0.25;
397        assert!(base.full_distance(&perturbed) < 1e-6);
398    }
399
400    #[test]
401    fn p7_9_v2_hyperbolic_t_does_not_change_distance() {
402        let mut base = Tensor10D::default();
403        base.v = 2.0;
404        let mut perturbed = base;
405        perturbed.t += 0.25;
406        let d_base = base.full_distance(&base);
407        let d_perturbed = base.full_distance(&perturbed);
408        assert!((d_perturbed - d_base).abs() < 1e-6);
409    }
410
411    #[test]
412    fn p7_9_v3_boundary_alpha_does_not_change_distance() {
413        let mut base = Tensor10D::default();
414        base.v = 3.0;
415        let mut perturbed = base;
416        perturbed.alpha += 0.25;
417        assert!(base.full_distance(&perturbed) < 1e-6);
418    }
419
420    #[test]
421    fn p7_9_v0_euclidean_q_does_not_change_distance() {
422        let base = Tensor10D::default();
423        let mut perturbed = base;
424        perturbed.q += 0.25;
425        assert!(base.full_distance(&perturbed) < 1e-6);
426    }
427
428    #[test]
429    fn p7_9_v0_euclidean_w_does_not_change_distance() {
430        let base = Tensor10D::default();
431        let mut perturbed = base;
432        perturbed.w += 0.25;
433        assert!(base.full_distance(&perturbed) < 1e-6);
434    }
435
436    #[test]
437    fn test_extended_topology_distance_dispatch() {
438        let mut t1 = Tensor10D::default();
439        let mut t2 = Tensor10D::default();
440
441        // Spherical Healpix (v=4)
442        t1.v = 4.0;
443        t2.v = 4.0;
444        t1.x = 1.0;
445        t2.y = 1.0;
446        assert!(t1.full_distance(&t2) > 1.0);
447
448        // Lorentzian Spacetime (v=5)
449        t1.v = 5.0;
450        t2.v = 5.0;
451        t1.x = 3.0;
452        t1.y = 0.0;
453        t2.x = 0.0;
454        t2.y = 0.0;
455        t1.t = 5.0;
456        t2.t = 0.0;
457        // ds^2 = -(5)^2 + 3^2 = -16 -> sqrt(16) = 4.0
458        assert!((t1.full_distance(&t2) - 4.0).abs() < 1e-5);
459
460        // Multiply Connected Portal (v=6)
461        t1.v = 6.0;
462        t2.v = 6.0;
463        t1.x = 0.05;
464        t2.x = 0.95;
465        assert!((t1.full_distance(&t2) - 0.1).abs() < 1e-5);
466    }
467}