1use 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
17pub const MAX_RESIDENT_NODES: usize = 4096;
19pub const MAX_KNN_HITS: usize = 32;
20
21pub 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 pub fn new() -> Self {
49 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 pub fn node_count(&self) -> u32 {
81 self.state.read().map_or(0, |state| state.node_count)
82 }
83
84 #[inline]
85 pub fn load_generation(&self) -> u32 {
87 self.state.read().map_or(0, |state| state.load_generation)
88 }
89
90 #[inline]
91 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 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 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 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 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 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]
230pub 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}