Skip to main content

qualia_core_db/topology/
pullback.rs

1//! 10D manifold frustum pullback and T16 `Epistemic10D` topological projection.
2//!
3//! Tier-1 Zero-Heap (`AGENTS.md` §0 & §0-A): bounded $k$-hop BFS filtered by a 10D coordinate
4//! frustum and ambient metric radius, plus the host-internal T16 morphism projecting
5//! `PoetGeometryHeader` + `HarbouredGraphHeader` + `HomologySummary` into `ManifoldCoordinate10D`.
6
7use crate::modalities::manifold::ManifoldCoordinate10D;
8use crate::tensor::topology::TopologyClass;
9use crate::tensor::Tensor10D;
10use crate::topology::csr_view::HarbouredCsrView;
11use crate::topology::header::{HarbouredGraphHeader, PoetGeometryHeader, TopologyError};
12use crate::topology::invariants::HomologySummary;
13
14/// 10-dimensional axis-aligned bounding frustum and step-metric gate over `Tensor10D`
15/// (`[q, v, w, x, y, z, t, α, μ, σ]`).
16#[derive(Copy, Clone, Debug, PartialEq)]
17pub struct Frustum10D {
18    pub min: [f32; 10],
19    pub max: [f32; 10],
20    pub max_metric_radius: f32,
21    pub topology_class: TopologyClass,
22}
23
24impl Default for Frustum10D {
25    fn default() -> Self {
26        Self::full_range(f32::INFINITY, TopologyClass::Euclidean)
27    }
28}
29
30impl Frustum10D {
31    /// Construct an unbounded 10D frustum gated only by `max_metric_radius` and `topology_class`.
32    #[inline]
33    pub const fn full_range(max_metric_radius: f32, topology_class: TopologyClass) -> Self {
34        Self {
35            min: [f32::NEG_INFINITY; 10],
36            max: [f32::INFINITY; 10],
37            max_metric_radius,
38            topology_class,
39        }
40    }
41
42    /// Returns `true` when all 10 axes `[q, v, w, x, y, z, t, α, μ, σ]` of `t`
43    /// lie within `[self.min[i], self.max[i]]`.
44    #[inline]
45    pub fn contains_tensor(&self, t: &Tensor10D) -> bool {
46        let axes = [
47            t.q, t.v, t.w, t.x, t.y, t.z, t.t, t.alpha, t.mu, t.sigma,
48        ];
49        let mut i = 0usize;
50        while i < 10 {
51            let val = axes[i];
52            if val < self.min[i] || val > self.max[i] {
53                return false;
54            }
55            i += 1;
56        }
57        true
58    }
59}
60
61/// Non-recursive bounded $k$-hop BFS starting at `start_vertex`, pruning any neighbour `w`
62/// outside `frustum` or exceeding `frustum.max_metric_radius` from `u` under `frustum.topology_class`.
63#[allow(clippy::too_many_arguments)]
64pub fn traverse_10d_pullback(
65    csr: &HarbouredCsrView<'_>,
66    coords_10d: &[Tensor10D],
67    start_vertex: u32,
68    max_hops: u8,
69    frustum: &Frustum10D,
70    visited_bits: &mut [u64],
71    queue_v: &mut [u32],
72    queue_depth: &mut [u8],
73    out_vertices: &mut [u32],
74) -> Result<usize, TopologyError> {
75    let v_count = csr.vertex_count();
76    if start_vertex >= v_count {
77        return Err(TopologyError::VertexOutOfRange {
78            vertex: start_vertex,
79            count: v_count,
80        });
81    }
82
83    let n = v_count as usize;
84    let words = (n + 63) / 64;
85    if coords_10d.len() < n
86        || visited_bits.len() < words
87        || queue_v.is_empty()
88        || queue_depth.len() < queue_v.len()
89        || out_vertices.is_empty()
90    {
91        return Err(TopologyError::BufferTooSmall);
92    }
93
94    visited_bits[..words].fill(0);
95
96    if !frustum.contains_tensor(&coords_10d[start_vertex as usize]) {
97        return Ok(0);
98    }
99
100    set_bit(visited_bits, start_vertex as usize);
101    queue_v[0] = start_vertex;
102    queue_depth[0] = 0;
103    out_vertices[0] = start_vertex;
104
105    let mut head = 0usize;
106    let mut tail = 1usize;
107    let mut written = 1usize;
108
109    while head < tail {
110        let u = queue_v[head];
111        let depth = queue_depth[head];
112        head += 1;
113
114        if depth >= max_hops {
115            continue;
116        }
117
118        let cu = &coords_10d[u as usize];
119        let p_u = (cu.x, cu.y, cu.z);
120        let nbrs = csr.out_neighbors(u)?;
121
122        let mut i = 0usize;
123        while i < nbrs.len() {
124            let w = nbrs[i];
125            i += 1;
126            let w_idx = w as usize;
127            if test_bit(visited_bits, w_idx) {
128                continue;
129            }
130            let cw = &coords_10d[w_idx];
131            if !frustum.contains_tensor(cw) {
132                continue;
133            }
134            let dist = frustum
135                .topology_class
136                .calculate_distance(p_u, (cw.x, cw.y, cw.z));
137            if dist > frustum.max_metric_radius {
138                continue;
139            }
140
141            set_bit(visited_bits, w_idx);
142            if tail >= queue_v.len() || written >= out_vertices.len() {
143                return Err(TopologyError::BufferTooSmall);
144            }
145            queue_v[tail] = w;
146            queue_depth[tail] = depth + 1;
147            tail += 1;
148            out_vertices[written] = w;
149            written += 1;
150        }
151    }
152
153    Ok(written)
154}
155
156/// T16 host-internal morphism projecting the active harboured graph's topological state
157/// and cellular homology onto `ManifoldCoordinate10D` (`Epistemic10D`):
158/// - `d[3]` (`topological_spin`): derived from `graph_header.graph_id` and `homology.betti_1`
159/// - `d[9]` (`manifold_curvature`): derived from `geom_header.euler_characteristic` and `homology.euler_characteristic`
160pub fn project_t16_epistemic_10d(
161    geom_header: &PoetGeometryHeader,
162    graph_header: &HarbouredGraphHeader,
163    homology: &HomologySummary,
164    epistemic: &mut ManifoldCoordinate10D,
165) {
166    let folded_id = (graph_header.graph_id ^ (graph_header.graph_id >> 32)) & 0xFFFF;
167    let id_spin_bias = if graph_header.graph_id == 0 {
168        0.0
169    } else {
170        ((folded_id.max(1)) as f32) / 65536.0
171    };
172
173    epistemic.topological_spin = (homology.betti_1 as f32) + id_spin_bias;
174    epistemic.manifold_curvature =
175        (geom_header.euler_characteristic as f32) - 0.5 * (homology.euler_characteristic as f32);
176
177    if graph_header.vertex_count > 0 {
178        epistemic.recurrence_frequency =
179            (homology.betti_1 as f32) / (graph_header.vertex_count as f32);
180    }
181}
182
183#[inline]
184fn test_bit(bits: &[u64], idx: usize) -> bool {
185    (bits[idx >> 6] & (1u64 << (idx & 63))) != 0
186}
187
188#[inline]
189fn set_bit(bits: &mut [u64], idx: usize) {
190    bits[idx >> 6] |= 1u64 << (idx & 63);
191}
192
193#[cfg(test)]
194mod tests {
195    use super::*;
196    use crate::topology::header::CellAnchor;
197
198    #[test]
199    fn pullback_traversal_filters_by_frustum_and_metric_radius() {
200        // 0 -> 1 -> 2, and 0 -> 3 (where 3 is too far in metric distance)
201        let header = HarbouredGraphHeader {
202            graph_id: 0x1234_5678,
203            vertex_count: 4,
204            edge_count: 3,
205            ..Default::default()
206        };
207        let anchors = [CellAnchor::default(); 4];
208        let row_ptr = [0u32, 2, 3, 3, 3];
209        let col_idx = [1u32, 3, 2];
210        let edge_anc = [0u32, 1, 2];
211        let csc_ptr = [0u32, 0, 1, 2, 3];
212        let csc_row = [0u32, 1, 0];
213        let csr = HarbouredCsrView::from_slices(
214            &header, &anchors, &row_ptr, &col_idx, &edge_anc, &csc_ptr, &csc_row, None,
215        )
216        .unwrap();
217
218        let coords = [
219            Tensor10D::new(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0),
220            Tensor10D::new(0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 0.0),
221            Tensor10D::new(0.0, 0.0, 0.0, 2.0, 0.0, 0.0, 2.0, 1.0, 0.0, 0.0),
222            Tensor10D::new(0.0, 0.0, 0.0, 10.0, 0.0, 0.0, 1.0, 1.0, 0.0, 0.0),
223        ];
224
225        let frustum = Frustum10D::full_range(2.0, TopologyClass::Euclidean);
226        let mut bits = [0u64; 1];
227        let mut q_v = [0u32; 4];
228        let mut q_d = [0u8; 4];
229        let mut out = [0u32; 4];
230
231        let n = traverse_10d_pullback(
232            &csr, &coords, 0, 2, &frustum, &mut bits, &mut q_v, &mut q_d, &mut out,
233        )
234        .unwrap();
235        assert_eq!(n, 3);
236        assert_eq!(&out[..3], &[0, 1, 2]);
237
238        let geom_hdr = PoetGeometryHeader {
239            euler_characteristic: 2,
240            ..Default::default()
241        };
242        let homology = HomologySummary {
243            euler_characteristic: 1,
244            betti_0: 1,
245            betti_1: 2,
246            root_count: 1,
247            sink_count: 2,
248        };
249        let mut ep = ManifoldCoordinate10D::default();
250        project_t16_epistemic_10d(&geom_hdr, &header, &homology, &mut ep);
251        assert!(ep.topological_spin > 2.0);
252        assert!((ep.manifold_curvature - 1.5).abs() < 1e-5);
253    }
254}