Skip to main content

qualia_core_db/tensor/
resident_substrate.rs

1//! Fixed-capacity resident graph–tensor SOA for U1 background search (Track B3.3).
2//!
3//! Cold path may parse heap buffers; hot path (`tensor_search_into`) uses caller stack only.
4
5use std::sync::{OnceLock, RwLock};
6
7use super::buffer_export::{parse_header, read_tensor_at};
8use super::q42_integration::{
9    Q42TensorView, TensorMetadata, TensorVolumeConfig, TensorVolumeError,
10};
11use super::Tensor10D;
12use crate::NQuin;
13#[path = "resident_snapshot.rs"]
14mod snapshot;
15pub use snapshot::ResidentSnapshot;
16
17/// Maximum nodes pinned in U1 ledger (structural cap, not heap growth).
18pub const MAX_RESIDENT_NODES: usize = 4096;
19pub const MAX_KNN_HITS: usize = 32;
20
21/// Process-wide resident substrate (U1 pin). Writer: cold load; reader: U1 producer.
22/// Each call observes one complete load; separate calls may observe different generations.
23pub struct ResidentTensorSubstrate {
24    state: RwLock<ResidentState>,
25}
26
27struct ResidentState {
28    nquins: [NQuin; MAX_RESIDENT_NODES],
29    metadata: [TensorMetadata; MAX_RESIDENT_NODES],
30    subject_hashes: [u64; MAX_RESIDENT_NODES],
31    node_count: u32,
32    load_generation: u32,
33}
34
35const fn empty_nquin() -> NQuin {
36    NQuin {
37        subject: 0,
38        predicate: 0,
39        object: 0,
40        context: 0,
41        metadata: 0,
42        parity: 0,
43    }
44}
45
46impl ResidentTensorSubstrate {
47    /// Creates a default `ResidentTensorSubstrate`.
48    pub fn new() -> Self {
49        // Constant initialization avoids large intermediate arrays on debug-build stacks.
50        const {
51            Self {
52                state: RwLock::new(ResidentState {
53                    nquins: [empty_nquin(); MAX_RESIDENT_NODES],
54                    metadata: [TensorMetadata {
55                        tensor: Tensor10D {
56                            q: 0.0,
57                            v: 0.0,
58                            w: 0.0,
59                            x: 0.0,
60                            y: 0.0,
61                            z: 0.0,
62                            t: 0.0,
63                            alpha: 1.0,
64                            mu: 0.0,
65                            sigma: 0.0,
66                        },
67                        has_tensor: false,
68                        tensor_version: 1,
69                    }; MAX_RESIDENT_NODES],
70                    subject_hashes: [0u64; MAX_RESIDENT_NODES],
71                    node_count: 0,
72                    load_generation: 0,
73                }),
74            }
75        }
76    }
77
78    #[inline]
79    /// Published node count, or zero after a writer panic poisons the substrate.
80    pub fn node_count(&self) -> u32 {
81        self.state.read().map_or(0, |state| state.node_count)
82    }
83
84    #[inline]
85    /// Wrapping load generation, or zero if the substrate is poisoned.
86    pub fn load_generation(&self) -> u32 {
87        self.state.read().map_or(0, |state| state.load_generation)
88    }
89
90    #[inline]
91    /// Published subject hash, or zero for a missing index or poisoned substrate.
92    pub fn subject_hash_at(&self, index: u32) -> u64 {
93        let Ok(state) = self.state.read() else {
94            return 0;
95        };
96        if index >= state.node_count {
97            return 0;
98        }
99        state.subject_hashes[index as usize]
100    }
101
102    #[inline]
103    /// Copies a published tensor, or returns `None` if missing or poisoned.
104    pub fn tensor_at(&self, index: u32) -> Option<Tensor10D> {
105        let state = self.state.read().ok()?;
106        if index >= state.node_count {
107            return None;
108        }
109        let meta = state.metadata[index as usize];
110        if meta.has_tensor {
111            Some(meta.tensor)
112        } else {
113            None
114        }
115    }
116
117    /// Cold-path load from exported tensor buffer (spatial encode, daemon slice).
118    /// Invalid buffers leave the published generation unchanged.
119    pub fn load_from_tensor_buffer(
120        &self,
121        bytes: &[u8],
122        default_subject_hash: u64,
123    ) -> Result<u32, &'static str> {
124        let (header, _header_len) = parse_header(bytes)?;
125        let count = header.node_count as usize;
126        if count > MAX_RESIDENT_NODES {
127            return Err("resident substrate capacity exceeded");
128        }
129
130        // Validate every record before replacing any published data.
131        for i in 0..count {
132            read_tensor_at(bytes, i)?;
133        }
134        let mut state = self
135            .state
136            .write()
137            .map_err(|_| "resident substrate poisoned")?;
138
139        for i in 0..count {
140            let tensor = read_tensor_at(bytes, i)?;
141            let subject = if default_subject_hash != 0 {
142                default_subject_hash ^ (i as u64)
143            } else {
144                crate::q_hash(&format!("tensor:node:{i}"))
145            };
146            state.nquins[i] = synthesize_nquin_for_tensor(i, subject, &tensor);
147            state.metadata[i] = TensorMetadata::from_nquin_and_tensor(&state.nquins[i], tensor);
148            state.subject_hashes[i] = subject;
149        }
150
151        state.node_count = count as u32;
152        state.load_generation = state.load_generation.wrapping_add(1);
153        Ok(count as u32)
154    }
155
156    /// Zero-heap kNN into caller buffer (U1 producer / SIMD path).
157    /// A poisoned substrate reports `TensorVolumeError::MismatchedStorage`.
158    pub fn tensor_search_into(
159        &self,
160        query: &Tensor10D,
161        max_distance: f32,
162        out: &mut [usize],
163    ) -> Result<usize, TensorVolumeError> {
164        let state = self
165            .state
166            .read()
167            .map_err(|_| TensorVolumeError::MismatchedStorage)?;
168        let count = state.node_count as usize;
169        if count == 0 {
170            return Ok(0);
171        }
172        let config = TensorVolumeConfig::default();
173        let view = Q42TensorView::new(&state.nquins[..count], &state.metadata[..count], &config)?;
174        view.tensor_search_into(query, max_distance, out)
175    }
176
177    /// Load tensors directly (native encode path without full buffer round-trip).
178    pub fn load_from_tensors(
179        &self,
180        tensors: &[Tensor10D],
181        subject_hash: u64,
182    ) -> Result<u32, &'static str> {
183        if tensors.len() > MAX_RESIDENT_NODES {
184            return Err("resident substrate capacity exceeded");
185        }
186        let mut state = self
187            .state
188            .write()
189            .map_err(|_| "resident substrate poisoned")?;
190
191        for (i, tensor) in tensors.iter().enumerate() {
192            let subject = if subject_hash != 0 {
193                subject_hash ^ (i as u64)
194            } else {
195                crate::q_hash(&format!("tensor:node:{i}"))
196            };
197            state.nquins[i] = synthesize_nquin_for_tensor(i, subject, tensor);
198            state.metadata[i] = TensorMetadata::from_nquin_and_tensor(&state.nquins[i], *tensor);
199            state.subject_hashes[i] = subject;
200        }
201
202        state.node_count = tensors.len() as u32;
203        state.load_generation = state.load_generation.wrapping_add(1);
204        Ok(tensors.len() as u32)
205    }
206}
207
208#[inline]
209fn synthesize_nquin_for_tensor(index: usize, subject: u64, tensor: &Tensor10D) -> NQuin {
210    let xi = ((tensor.x * 1000.0).clamp(-524288.0, 524287.0) as i32) as u64 & 0xFFFFF;
211    let yi = ((tensor.y * 1000.0).clamp(-524288.0, 524287.0) as i32) as u64 & 0xFFFFF;
212    let zi = ((tensor.z * 1000.0).clamp(-524288.0, 524287.0) as i32) as u64 & 0xFFFFF;
213    let object = (xi << 40) | (yi << 20) | zi;
214    let predicate = super::bake_pipeline::PRED_GEO_VERTEX;
215    let context = crate::q_hash("urn:qualia:context:tensor_substrate");
216    let metadata = index as u64;
217    NQuin {
218        subject,
219        predicate,
220        object,
221        context,
222        metadata,
223        parity: subject ^ predicate ^ object ^ context,
224    }
225}
226
227static RESIDENT_SUBSTRATE: OnceLock<Box<ResidentTensorSubstrate>> = OnceLock::new();
228
229#[inline]
230/// `ResidentTensorSubstrate::global_resident_substrate`.
231pub fn global_resident_substrate() -> &'static ResidentTensorSubstrate {
232    RESIDENT_SUBSTRATE.get_or_init(|| Box::new(ResidentTensorSubstrate::new()))
233}
234
235#[cfg(test)]
236mod tests {
237    use super::*;
238    use crate::specialized_libs::computational_geometry::allocation_counter::assert_zero_alloc;
239    use crate::tensor::buffer_export::{write_tensor_buffer, TensorBufferHeader};
240
241    #[test]
242    fn initial_state_matches_metadata_default() {
243        let sub = ResidentTensorSubstrate::new();
244        let state = sub.state.read().unwrap();
245        assert_eq!(state.node_count, 0);
246        assert_eq!(state.load_generation, 0);
247        for i in 0..MAX_RESIDENT_NODES {
248            assert_eq!(state.nquins[i], NQuin::default());
249            assert_eq!(state.metadata[i], TensorMetadata::default());
250            assert_eq!(state.subject_hashes[i], 0);
251        }
252    }
253
254    #[test]
255    fn malformed_reload_preserves_published_generation() {
256        let sub = ResidentTensorSubstrate::new();
257        let original = Tensor10D::default();
258        sub.load_from_tensors(&[original; 2], 42).unwrap();
259        let changed = Tensor10D {
260            x: 10.0,
261            ..original
262        };
263        let mut bytes = vec![0; TensorBufferHeader::total_bytes(2)];
264        write_tensor_buffer(&[changed; 2], &mut bytes).unwrap();
265        bytes.pop();
266
267        assert_eq!(
268            sub.load_from_tensor_buffer(&bytes, 99),
269            Err("buffer truncated")
270        );
271        assert_eq!(sub.node_count(), 2);
272        assert_eq!(sub.load_generation(), 1);
273        for i in 0..2 {
274            assert_eq!(sub.tensor_at(i), Some(original));
275            assert_eq!(sub.subject_hash_at(i), 42 ^ u64::from(i));
276        }
277        assert_eq!(sub.tensor_at(2), None);
278        assert_eq!(sub.subject_hash_at(2), 0);
279        let mut hits = [usize::MAX; 2];
280        assert_eq!(sub.tensor_search_into(&original, 0.5, &mut hits), Ok(2));
281        assert_eq!(hits, [0, 1]);
282    }
283
284    #[test]
285    fn concurrent_reloads_publish_complete_generations() {
286        const RELOADS: usize = 500;
287        let sub = ResidentTensorSubstrate::new();
288        let near = [Tensor10D::default(); 32];
289        let far = [Tensor10D {
290            x: 10.0,
291            ..Tensor10D::default()
292        }; 16];
293        let mut bytes = vec![0; TensorBufferHeader::total_bytes(far.len())];
294        write_tensor_buffer(&far, &mut bytes).unwrap();
295        sub.load_from_tensors(&near, 32).unwrap();
296        let start = std::sync::Barrier::new(5);
297
298        std::thread::scope(|scope| {
299            for _ in 0..2 {
300                scope.spawn(|| {
301                    start.wait();
302                    for _ in 0..RELOADS {
303                        sub.load_from_tensor_buffer(&bytes, 16).unwrap();
304                        sub.load_from_tensors(&near, 32).unwrap();
305                        std::thread::yield_now();
306                    }
307                });
308            }
309            for _ in 0..2 {
310                scope.spawn(|| {
311                    start.wait();
312                    let mut generation = 0;
313                    let mut hits = [usize::MAX; 32];
314                    for _ in 0..RELOADS {
315                        let n = sub.tensor_search_into(&near[0], 0.5, &mut hits).unwrap();
316                        assert!(n == 0 || n == near.len());
317                        for (index, hit) in hits[..n].iter().enumerate() {
318                            assert_eq!(*hit, index);
319                        }
320                        assert!(matches!(sub.node_count(), 16 | 32));
321                        assert!(matches!(sub.subject_hash_at(0), 16 | 32));
322                        let tensor = sub.tensor_at(0).unwrap();
323                        assert!(tensor == near[0] || tensor == far[0]);
324
325                        let state = sub.state.read().unwrap();
326                        assert!(state.load_generation >= generation);
327                        generation = state.load_generation;
328                        let expected = if state.node_count == 32 {
329                            near[0]
330                        } else {
331                            far[0]
332                        };
333                        for i in 0..state.node_count as usize {
334                            assert_eq!(state.metadata[i].tensor, expected);
335                            assert_eq!(
336                                state.subject_hashes[i],
337                                u64::from(state.node_count) ^ i as u64
338                            );
339                            assert_eq!(state.nquins[i].subject, state.subject_hashes[i]);
340                        }
341                    }
342                });
343            }
344            start.wait();
345        });
346        assert_eq!(sub.load_generation(), 1 + 4 * RELOADS as u32);
347    }
348
349    #[test]
350    fn poisoned_substrate_fails_closed() {
351        let sub = ResidentTensorSubstrate::new();
352        let tensor = Tensor10D::default();
353        let mut bytes = vec![0; TensorBufferHeader::total_bytes(1)];
354        write_tensor_buffer(&[tensor], &mut bytes).unwrap();
355        sub.load_from_tensors(&[tensor], 42).unwrap();
356        assert!(std::panic::catch_unwind(|| {
357            let _guard = sub.state.write().unwrap();
358            panic!("interrupt resident reload");
359        })
360        .is_err());
361
362        assert_eq!(sub.node_count(), 0);
363        assert_eq!(sub.load_generation(), 0);
364        assert_eq!(sub.tensor_at(0), None);
365        assert_eq!(sub.subject_hash_at(0), 0);
366        assert_eq!(
367            sub.load_from_tensors(&[tensor], 42),
368            Err("resident substrate poisoned")
369        );
370        assert_eq!(
371            sub.load_from_tensor_buffer(&bytes, 42),
372            Err("resident substrate poisoned")
373        );
374        assert_eq!(
375            sub.tensor_search_into(&tensor, 1.0, &mut [0; 1]),
376            Err(TensorVolumeError::MismatchedStorage)
377        );
378    }
379
380    #[test]
381    fn resident_reads_are_zero_heap() {
382        let sub = ResidentTensorSubstrate::new();
383        let tensor = Tensor10D::default();
384        sub.load_from_tensors(&[tensor; 2], 42).unwrap();
385        let mut hits = [0; 2];
386        sub.tensor_search_into(&tensor, 0.5, &mut hits).unwrap();
387        assert_zero_alloc("resident tensor reads", || {
388            for _ in 0..32 {
389                assert_eq!(sub.node_count(), 2);
390                assert_eq!(sub.load_generation(), 1);
391                assert_eq!(sub.tensor_at(0), Some(tensor));
392                assert_eq!(sub.subject_hash_at(0), 42);
393                assert_eq!(sub.tensor_search_into(&tensor, 0.5, &mut hits), Ok(2));
394            }
395        });
396    }
397
398    #[test]
399    fn load_and_search_resident_substrate() {
400        let sub = ResidentTensorSubstrate::new();
401        let tensors = [
402            Tensor10D::new(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0),
403            Tensor10D::new(0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0),
404        ];
405        let need = TensorBufferHeader::total_bytes(2);
406        let mut buf = vec![0u8; need];
407        write_tensor_buffer(&tensors, &mut buf).unwrap();
408        assert_eq!(sub.load_from_tensor_buffer(&buf, 42).unwrap(), 2);
409
410        let query = Tensor10D::new(0.0, 0.0, 0.0, 0.1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0);
411        let mut hits = [0usize; MAX_KNN_HITS];
412        let n = sub.tensor_search_into(&query, 0.5, &mut hits).unwrap();
413        assert!(n >= 1);
414        assert_eq!(hits[0], 0);
415    }
416}