Skip to main content

webizen_studio/render/
tensor_buffer.rs

1/// Zero-deserialization view into 10D tensor buffer with binary indexing
2///
3/// Provides stack-allocated access to binary tensor data without
4/// deserialization overhead. The view interprets raw bytes as 10D tensor
5/// projections on-demand using index pointers instead of string IDs.
6///
7/// Zero-heap consideration: The view itself is stack-allocated (Copy type).
8/// Only references to the underlying buffer are held. No heap allocation
9/// occurs when creating or copying the view.
10///
11/// Binary IPC Optimization: Uses u64 index pointers instead of String IDs
12/// to avoid heap allocation during cross-process serialization.
13///
14/// The canonical engine wire format is `Q42*` + a 32-byte header + packed
15/// 10×f32 records (40 bytes). The former Studio-only 10×f64 records (80 bytes)
16/// remain readable for saved previews, but new engine buffers are decoded by
17/// their header and never guessed from their total length.
18pub(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    /// Raw byte buffer containing tensor data
32    buffer: &'a [u8],
33    /// Number of tensors in the buffer
34    count: usize,
35    /// Binary node index table (index -> byte offset relative to record area)
36    index_table: &'a [u64],
37    /// Byte offset of record zero and its encoding.
38    data_offset: usize,
39    format: TensorWireFormat,
40}
41
42impl<'a> TensorBufferView<'a> {
43    /// Create a view from a byte buffer with an index table.
44    ///
45    /// Zero-heap consideration: No allocation, just creates a view struct
46    /// Binary IPC: Index table enables O(1) node lookup without string parsing
47    #[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    /// Create a view from a byte buffer without an index table.
53    /// Reads the canonical Q42 f32 ABI and retains compatibility with legacy
54    /// Studio f64 preview buffers.
55    #[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    /// Get the number of tensors in the buffer
97    #[inline]
98    pub fn len(&self) -> usize {
99        self.count
100    }
101
102    /// Check if the buffer is empty
103    #[inline]
104    pub fn is_empty(&self) -> bool {
105        self.count == 0
106    }
107
108    /// Get a tensor by binary index pointer (zero-heap O(1) lookup)
109    ///
110    /// Zero-heap consideration: Returns stack-allocated Tensor10D struct
111    /// Binary IPC: Uses u64 index instead of String, avoiding heap allocation
112    #[inline]
113    pub fn get_by_index(&self, index: u64) -> Option<Tensor10DView> {
114        // Lookup offset in index table
115        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    /// Get a tensor at a specific byte offset (internal method)
130    ///
131    /// Zero-heap consideration: Stack-allocated reconstruction, no heap
132    #[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    /// Get a tensor at the specified index (legacy method, sequential access)
167    ///
168    /// Zero-heap consideration: Returns stack-allocated Tensor10D struct
169    /// No heap allocation, just byte interpretation
170    #[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    /// Read little-endian f64 from bytes
192    ///
193    /// Zero-heap consideration: Stack-allocated reconstruction, no heap
194    #[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    /// Create a binary index table from sequential tensor buffer
202    ///
203    /// Zero-heap consideration: Returns Vec\<u64\> (heap-allocated, but this is
204    /// a one-time construction cost. The actual runtime access is zero-heap.)
205    /// Binary IPC: This table is sent once, then reused for O(1) lookups
206    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    /// Build record-relative offsets for canonical Q42 `Tensor10D` buffers.
213    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/// Stack-allocated 10D tensor view
219///
220/// Zero-heap consideration: This struct is Copy and stack-allocated
221#[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    /// Combined magnitude across all manifold axes (telemetry / culling helper).
237    #[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    /// Return the canonical EMF spectral tuple `[α, μ, σ]`.
253    #[inline]
254    pub fn emf_spectrum(&self) -> [f64; 3] {
255        [self.alpha, self.mu, self.sigma]
256    }
257
258    /// Human-visible convenience projection of σ. EMF `[α, μ, σ]` remains
259    /// canonical; this display helper must never replace or clamp stored σ.
260    pub fn spectral_color(&self) -> String {
261        // Simple spectral mapping (simplified from full CIE XYZ)
262        let hue = (self.sigma * 360.0) % 360.0;
263        format!("hsl({}, 70%, 50%)", hue)
264    }
265
266    /// Get opacity from alpha value
267    #[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        // Create a buffer with one tensor (80 bytes)
305        let mut buffer = [0u8; 80];
306        // Set sigma = 0.5
307        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        // Create a buffer with two tensors (160 bytes)
320        let mut buffer = [0u8; 160];
321        // Set sigma = 0.5 for first tensor
322        buffer[72..80].copy_from_slice(&0.5_f64.to_le_bytes());
323        // Set sigma = 0.8 for second tensor
324        buffer[152..160].copy_from_slice(&0.8_f64.to_le_bytes());
325
326        // Build index table
327        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        // Test binary index lookup
336        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        // Test legacy sequential access still works
343        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}