1pub(crate) const Q42_TENSOR_MAGIC: u32 = 0x5134_322A;
19pub(crate) const Q42_TENSOR_VERSION: u16 = 1;
20pub(crate) const Q42_TENSOR_HEADER_BYTES: usize = 32;
21pub(crate) const Q42_TENSOR_STRIDE: usize = 40;
22const LEGACY_TENSOR_STRIDE: usize = 80;
23
24#[derive(Debug, Clone, Copy, PartialEq, Eq)]
25enum TensorWireFormat {
26 Q42F32,
27 LegacyF64,
28}
29#[derive(Debug, Clone, Copy)]
30pub struct TensorBufferView<'a> {
31 buffer: &'a [u8],
33 count: usize,
35 index_table: &'a [u64],
37 data_offset: usize,
39 format: TensorWireFormat,
40}
41
42impl<'a> TensorBufferView<'a> {
43 #[inline]
48 pub fn new_with_index(buffer: &'a [u8], index_table: &'a [u64]) -> Self {
49 Self::new_inner(buffer, index_table)
50 }
51
52 #[inline]
56 pub fn new(buffer: &'a [u8]) -> Self {
57 Self::new_inner(buffer, &[])
58 }
59
60 fn new_inner(buffer: &'a [u8], index_table: &'a [u64]) -> Self {
61 let (format, data_offset, count) = if buffer.len() >= 4
62 && u32::from_le_bytes(buffer[..4].try_into().unwrap()) == Q42_TENSOR_MAGIC
63 {
64 let valid = buffer.len() >= Q42_TENSOR_HEADER_BYTES
65 && u16::from_le_bytes(buffer[4..6].try_into().unwrap()) == Q42_TENSOR_VERSION
66 && u32::from_le_bytes(buffer[12..16].try_into().unwrap()) as usize
67 == Q42_TENSOR_STRIDE;
68 if !valid {
69 (TensorWireFormat::Q42F32, Q42_TENSOR_HEADER_BYTES, 0)
70 } else {
71 let count = u32::from_le_bytes(buffer[8..12].try_into().unwrap()) as usize;
72 let required = count
73 .checked_mul(Q42_TENSOR_STRIDE)
74 .and_then(|bytes| Q42_TENSOR_HEADER_BYTES.checked_add(bytes));
75 match required.filter(|required| *required <= buffer.len()) {
76 Some(_) => (TensorWireFormat::Q42F32, Q42_TENSOR_HEADER_BYTES, count),
77 None => (TensorWireFormat::Q42F32, Q42_TENSOR_HEADER_BYTES, 0),
78 }
79 }
80 } else {
81 (
82 TensorWireFormat::LegacyF64,
83 0,
84 buffer.len() / LEGACY_TENSOR_STRIDE,
85 )
86 };
87 Self {
88 buffer,
89 count,
90 index_table,
91 data_offset,
92 format,
93 }
94 }
95
96 #[inline]
98 pub fn len(&self) -> usize {
99 self.count
100 }
101
102 #[inline]
104 pub fn is_empty(&self) -> bool {
105 self.count == 0
106 }
107
108 #[inline]
113 pub fn get_by_index(&self, index: u64) -> Option<Tensor10DView> {
114 let tensor_index = usize::try_from(index).ok()?;
116 if tensor_index >= self.count || tensor_index >= self.index_table.len() {
117 return None;
118 }
119
120 let Some(offset) = usize::try_from(self.index_table[tensor_index])
121 .ok()
122 .and_then(|offset| self.data_offset.checked_add(offset))
123 else {
124 return None;
125 };
126 self.get_by_offset(offset)
127 }
128
129 #[inline]
133 fn get_by_offset(&self, offset: usize) -> Option<Tensor10DView> {
134 let stride = self.record_stride();
135 let Some(end) = offset.checked_add(stride) else {
136 return None;
137 };
138 if end > self.buffer.len() || offset < self.data_offset {
139 return None;
140 }
141 let relative = offset.checked_sub(self.data_offset)?;
142 let data_bytes = self.count.checked_mul(stride)?;
143 if relative % stride != 0 || relative.checked_add(stride)? > data_bytes {
144 return None;
145 }
146
147 let bytes = &self.buffer[offset..end];
148 let mut values = [0.0; 10];
149 match self.format {
150 TensorWireFormat::Q42F32 => {
151 for (i, value) in values.iter_mut().enumerate() {
152 let at = i * 4;
153 *value = f32::from_le_bytes(bytes[at..at + 4].try_into().ok()?) as f64;
154 }
155 }
156 TensorWireFormat::LegacyF64 => {
157 for (i, value) in values.iter_mut().enumerate() {
158 let at = i * 8;
159 *value = self.read_f64_le(&bytes[at..at + 8]);
160 }
161 }
162 }
163 Some(Tensor10DView::from_values(values))
164 }
165
166 #[inline]
171 pub fn get(&self, index: usize) -> Option<Tensor10DView> {
172 if index >= self.count {
173 return None;
174 }
175
176 let offset = self
177 .record_stride()
178 .checked_mul(index)?
179 .checked_add(self.data_offset)?;
180 self.get_by_offset(offset)
181 }
182
183 #[inline]
184 fn record_stride(&self) -> usize {
185 match self.format {
186 TensorWireFormat::Q42F32 => Q42_TENSOR_STRIDE,
187 TensorWireFormat::LegacyF64 => LEGACY_TENSOR_STRIDE,
188 }
189 }
190
191 #[inline]
195 fn read_f64_le(&self, bytes: &[u8]) -> f64 {
196 let mut arr = [0u8; 8];
197 arr.copy_from_slice(bytes);
198 f64::from_le_bytes(arr)
199 }
200
201 pub fn build_index_table(count: usize) -> Vec<u64> {
207 (0..count)
208 .map(|i| (i * LEGACY_TENSOR_STRIDE) as u64)
209 .collect()
210 }
211
212 pub fn build_q42_index_table(count: usize) -> Vec<u64> {
214 (0..count).map(|i| (i * Q42_TENSOR_STRIDE) as u64).collect()
215 }
216}
217
218#[derive(Debug, Clone, Copy)]
222pub struct Tensor10DView {
223 pub q: f64,
224 pub v: f64,
225 pub w: f64,
226 pub x: f64,
227 pub y: f64,
228 pub z: f64,
229 pub t: f64,
230 pub alpha: f64,
231 pub mu: f64,
232 pub sigma: f64,
233}
234
235impl Tensor10DView {
236 #[inline]
238 pub fn manifold_energy(&self) -> f64 {
239 let sum = self.q * self.q
240 + self.v * self.v
241 + self.w * self.w
242 + self.x * self.x
243 + self.y * self.y
244 + self.z * self.z
245 + self.t * self.t
246 + self.alpha * self.alpha
247 + self.mu * self.mu
248 + self.sigma * self.sigma;
249 sum.sqrt()
250 }
251
252 #[inline]
254 pub fn emf_spectrum(&self) -> [f64; 3] {
255 [self.alpha, self.mu, self.sigma]
256 }
257
258 pub fn spectral_color(&self) -> String {
261 let hue = (self.sigma * 360.0) % 360.0;
263 format!("hsl({}, 70%, 50%)", hue)
264 }
265
266 #[inline]
268 pub fn opacity(&self) -> f64 {
269 self.alpha.clamp(0.0, 1.0)
270 }
271}
272
273impl Tensor10DView {
274 fn from_values(values: [f64; 10]) -> Self {
275 Self {
276 q: values[0],
277 v: values[1],
278 w: values[2],
279 x: values[3],
280 y: values[4],
281 z: values[5],
282 t: values[6],
283 alpha: values[7],
284 mu: values[8],
285 sigma: values[9],
286 }
287 }
288}
289
290#[cfg(test)]
291mod tests {
292 use super::*;
293
294 #[test]
295 fn test_tensor_buffer_view_empty() {
296 let buffer = [];
297 let view = TensorBufferView::new(&buffer);
298 assert!(view.is_empty());
299 assert_eq!(view.len(), 0);
300 }
301
302 #[test]
303 fn test_tensor_buffer_view_single() {
304 let mut buffer = [0u8; 80];
306 let sigma_bytes = 0.5_f64.to_le_bytes();
308 buffer[72..80].copy_from_slice(&sigma_bytes);
309
310 let view = TensorBufferView::new(&buffer);
311 assert_eq!(view.len(), 1);
312
313 let tensor = view.get(0).unwrap();
314 assert_eq!(tensor.sigma, 0.5);
315 }
316
317 #[test]
318 fn test_tensor_buffer_view_with_index_table() {
319 let mut buffer = [0u8; 160];
321 buffer[72..80].copy_from_slice(&0.5_f64.to_le_bytes());
323 buffer[152..160].copy_from_slice(&0.8_f64.to_le_bytes());
325
326 let index_table = TensorBufferView::build_index_table(2);
328 assert_eq!(index_table.len(), 2);
329 assert_eq!(index_table[0], 0);
330 assert_eq!(index_table[1], 80);
331
332 let view = TensorBufferView::new_with_index(&buffer, &index_table);
333 assert_eq!(view.len(), 2);
334
335 let tensor0 = view.get_by_index(0).unwrap();
337 assert_eq!(tensor0.sigma, 0.5);
338
339 let tensor1 = view.get_by_index(1).unwrap();
340 assert_eq!(tensor1.sigma, 0.8);
341
342 let tensor0_legacy = view.get(0).unwrap();
344 assert_eq!(tensor0_legacy.sigma, 0.5);
345 }
346
347 #[test]
348 fn reads_canonical_q42_f32_buffer_and_emf_without_color_conversion() {
349 let mut buffer = [0u8; Q42_TENSOR_HEADER_BYTES + Q42_TENSOR_STRIDE];
350 buffer[0..4].copy_from_slice(&Q42_TENSOR_MAGIC.to_le_bytes());
351 buffer[4..6].copy_from_slice(&Q42_TENSOR_VERSION.to_le_bytes());
352 buffer[8..12].copy_from_slice(&1_u32.to_le_bytes());
353 buffer[12..16].copy_from_slice(&(Q42_TENSOR_STRIDE as u32).to_le_bytes());
354 let values = [0.25_f32, 2.0, 3.0, -1.0, 0.5, 4.0, 7.0, 0.8, 0.3, 1.75];
355 for (i, value) in values.iter().enumerate() {
356 let offset = Q42_TENSOR_HEADER_BYTES + i * 4;
357 buffer[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
358 }
359
360 let view = TensorBufferView::new(&buffer);
361 assert_eq!(view.len(), 1);
362 let tensor = view.get(0).unwrap();
363 assert_eq!(tensor.q, 0.25);
364 assert_eq!(tensor.x, -1.0);
365 let emf = tensor.emf_spectrum();
366 assert!((emf[0] - 0.8).abs() < 1e-6);
367 assert!((emf[1] - 0.3).abs() < 1e-6);
368 assert_eq!(emf[2], 1.75);
369 assert_eq!(tensor.sigma, 1.75, "σ must not be clamped to display gamut");
370 }
371
372 #[test]
373 fn q42_index_offsets_are_relative_to_record_area() {
374 let mut buffer = [0u8; Q42_TENSOR_HEADER_BYTES + 2 * Q42_TENSOR_STRIDE];
375 buffer[0..4].copy_from_slice(&Q42_TENSOR_MAGIC.to_le_bytes());
376 buffer[4..6].copy_from_slice(&Q42_TENSOR_VERSION.to_le_bytes());
377 buffer[8..12].copy_from_slice(&2_u32.to_le_bytes());
378 buffer[12..16].copy_from_slice(&(Q42_TENSOR_STRIDE as u32).to_le_bytes());
379 buffer[Q42_TENSOR_HEADER_BYTES + Q42_TENSOR_STRIDE + 36..]
380 .copy_from_slice(&0.625_f32.to_le_bytes());
381 let offsets = TensorBufferView::build_q42_index_table(2);
382 let view = TensorBufferView::new_with_index(&buffer, &offsets);
383 assert_eq!(view.get_by_index(1).unwrap().sigma, 0.625);
384 assert!(view.get_by_index(u64::MAX).is_none());
385 }
386
387 #[test]
388 fn rejects_truncated_canonical_q42_buffer() {
389 let mut buffer = [0u8; Q42_TENSOR_HEADER_BYTES];
390 buffer[0..4].copy_from_slice(&Q42_TENSOR_MAGIC.to_le_bytes());
391 buffer[4..6].copy_from_slice(&Q42_TENSOR_VERSION.to_le_bytes());
392 buffer[8..12].copy_from_slice(&1_u32.to_le_bytes());
393 buffer[12..16].copy_from_slice(&(Q42_TENSOR_STRIDE as u32).to_le_bytes());
394 assert!(TensorBufferView::new(&buffer).is_empty());
395 }
396
397 #[test]
398 fn test_binary_index_table_builder() {
399 let table = TensorBufferView::build_index_table(5);
400 assert_eq!(table.len(), 5);
401 assert_eq!(table[0], 0);
402 assert_eq!(table[1], 80);
403 assert_eq!(table[2], 160);
404 assert_eq!(table[3], 240);
405 assert_eq!(table[4], 320);
406 }
407}