Skip to main content

qualia_core_db/tensor/
buffer_export.rs

1//! Binary tensor buffer export for Qualia portal GPU upload.
2//!
3//! Layout: header (32 B) + N × Tensor10D (40 B each), little-endian f32.
4
5use bytemuck::{bytes_of, Pod, Zeroable};
6
7use super::Tensor10D;
8
9pub const TENSOR_BUFFER_MAGIC: u32 = 0x5134_322A; // "Q42*"
10pub const TENSOR_BUFFER_VERSION: u16 = 1;
11pub const TENSOR_STRIDE: usize = 40;
12/// Byte offset to the first `Tensor10D` record in a baked buffer blob.
13pub const TENSOR_HEADER_BYTES: usize = std::mem::size_of::<TensorBufferHeader>();
14
15#[repr(C, align(4))]
16#[derive(Clone, Copy, Debug, Default, Pod, Zeroable)]
17pub struct TensorBufferHeader {
18    pub magic: u32,
19    pub version: u16,
20    pub _pad0: u16,
21    pub node_count: u32,
22    pub stride: u32,
23    pub _reserved: [u32; 4],
24}
25
26impl TensorBufferHeader {
27    /// Creates a default `TensorBufferHeader`.
28    pub fn new(node_count: u32) -> Self {
29        Self {
30            magic: TENSOR_BUFFER_MAGIC,
31            version: TENSOR_BUFFER_VERSION,
32            node_count,
33            stride: TENSOR_STRIDE as u32,
34            ..Default::default()
35        }
36    }
37
38    /// `total` size in bytes.
39    pub fn total_bytes(node_count: usize) -> usize {
40        std::mem::size_of::<TensorBufferHeader>() + node_count * TENSOR_STRIDE
41    }
42}
43
44/// Parse header from a tensor buffer blob. Returns (header, header_byte_len).
45#[inline]
46pub fn parse_header(bytes: &[u8]) -> Result<(TensorBufferHeader, usize), &'static str> {
47    let header_len = std::mem::size_of::<TensorBufferHeader>();
48    if bytes.len() < header_len {
49        return Err("buffer too small for header");
50    }
51    let header: TensorBufferHeader = bytemuck::pod_read_unaligned(&bytes[..header_len]);
52    if header.magic != TENSOR_BUFFER_MAGIC {
53        return Err("invalid tensor buffer magic");
54    }
55    if header.stride as usize != TENSOR_STRIDE {
56        return Err("unsupported tensor stride");
57    }
58    Ok((header, header_len))
59}
60
61/// Node count encoded in a tensor buffer (zero-alloc).
62#[inline]
63pub fn tensor_node_count(bytes: &[u8]) -> Result<usize, &'static str> {
64    let (header, _) = parse_header(bytes)?;
65    Ok(header.node_count as usize)
66}
67
68/// Write epistemic `q` for one node (wavefunction collapse). Returns previous q.
69#[inline]
70pub fn write_tensor_q_at(bytes: &mut [u8], index: usize, q: f32) -> Result<f32, &'static str> {
71    let (header, header_len) = parse_header(bytes)?;
72    let count = header.node_count as usize;
73    if index >= count {
74        return Err("tensor index out of range");
75    }
76    let offset = header_len + index * TENSOR_STRIDE;
77    let end = offset + 4;
78    if bytes.len() < end {
79        return Err("buffer truncated");
80    }
81    let prev = f32::from_le_bytes(bytes[offset..offset + 4].try_into().unwrap());
82    bytes[offset..offset + 4].copy_from_slice(&q.to_le_bytes());
83    Ok(prev)
84}
85
86/// Read one `Tensor10D` by index from a buffer (zero-alloc).
87#[inline]
88pub fn read_tensor_at(bytes: &[u8], index: usize) -> Result<Tensor10D, &'static str> {
89    let (header, header_len) = parse_header(bytes)?;
90    let count = header.node_count as usize;
91    if index >= count {
92        return Err("tensor index out of range");
93    }
94    let offset = header_len + index * TENSOR_STRIDE;
95    let end = offset + TENSOR_STRIDE;
96    if bytes.len() < end {
97        return Err("buffer truncated");
98    }
99    Ok(bytemuck::pod_read_unaligned(&bytes[offset..end]))
100}
101
102/// Pack σ / α / q into linear RGBA for viewport shaders (cold path).
103#[inline]
104pub fn tensor_render_color(t: &Tensor10D) -> [f32; 4] {
105    let rgb = crate::render::spectral::sigma_to_linear_rgb(t.sigma);
106    let alpha = (0.35 + t.alpha * 0.55).clamp(0.15, 1.0);
107    [rgb[0], rgb[1], rgb[2], alpha]
108}
109
110/// Write header + tensor slice into caller buffer. Returns bytes written.
111pub fn write_tensor_buffer(tensors: &[Tensor10D], out: &mut [u8]) -> Result<usize, &'static str> {
112    let need = TensorBufferHeader::total_bytes(tensors.len());
113    if out.len() < need {
114        return Err("output buffer too small");
115    }
116    let header = TensorBufferHeader::new(tensors.len() as u32);
117    let header_bytes = bytes_of(&header);
118    out[..header_bytes.len()].copy_from_slice(header_bytes);
119    let mut offset = header_bytes.len();
120    for tensor in tensors {
121        let tb = bytes_of(tensor);
122        out[offset..offset + tb.len()].copy_from_slice(tb);
123        offset += tb.len();
124    }
125    Ok(offset)
126}
127
128/// Export a bounded slice from the resident U1 substrate into a tensor buffer blob.
129pub fn write_tensor_slice_from_resident(
130    substrate: &crate::tensor::resident_substrate::ResidentTensorSubstrate,
131    max_nodes: usize,
132    out: &mut [u8],
133) -> Result<usize, &'static str> {
134    let count = substrate.node_count() as usize;
135    if count == 0 {
136        return Err("no resident tensors");
137    }
138    let export_n = count.min(max_nodes);
139    let need = TensorBufferHeader::total_bytes(export_n);
140    if out.len() < need {
141        return Err("output buffer too small");
142    }
143    let mut offset = std::mem::size_of::<TensorBufferHeader>();
144    let header = TensorBufferHeader::new(export_n as u32);
145    out[..offset].copy_from_slice(bytes_of(&header));
146    for i in 0..export_n {
147        let tensor = substrate
148            .tensor_at(i as u32)
149            .ok_or("resident tensor missing")?;
150        let tb = bytes_of(&tensor);
151        out[offset..offset + tb.len()].copy_from_slice(tb);
152        offset += tb.len();
153    }
154    Ok(offset)
155}
156
157#[cfg(test)]
158mod tests {
159    use super::*;
160
161    #[test]
162    fn header_size_stable() {
163        assert_eq!(std::mem::size_of::<TensorBufferHeader>(), 32);
164        assert_eq!(std::mem::size_of::<Tensor10D>(), 40);
165    }
166
167    #[test]
168    fn write_tensor_slice_from_resident_round_trip() {
169        use crate::tensor::resident_substrate::ResidentTensorSubstrate;
170        let sub = ResidentTensorSubstrate::new();
171        let tensors = [
172            Tensor10D::ground_truth(0.0, 0.0, 0.1, 0.2, 0.3, 0.0, 1.0, 0.0, 0.5),
173            Tensor10D::new(0.5, 0.0, 0.0, 0.4, 0.5, 0.6, 0.0, 1.0, 0.0, 0.75),
174        ];
175        let need = TensorBufferHeader::total_bytes(2);
176        let mut buf = vec![0u8; need];
177        write_tensor_buffer(&tensors, &mut buf).unwrap();
178        sub.load_from_tensor_buffer(&buf, 0).unwrap();
179
180        let mut slice = vec![0u8; need];
181        let n = write_tensor_slice_from_resident(&sub, 2, &mut slice).unwrap();
182        assert_eq!(n, need);
183        assert_eq!(tensor_node_count(&slice).unwrap(), 2);
184        let t1 = read_tensor_at(&slice, 1).unwrap();
185        assert!((t1.q - 0.5).abs() < 1e-5);
186    }
187
188    #[test]
189    fn write_tensor_q_at_collapses_epistemic_field() {
190        let tensors = [Tensor10D::ground_truth(
191            0.0, 0.0, 0.1, 0.2, 0.3, 0.0, 1.0, 0.0, 0.5,
192        )];
193        let need = TensorBufferHeader::total_bytes(tensors.len());
194        let mut buf = vec![0u8; need];
195        write_tensor_buffer(&tensors, &mut buf).unwrap();
196        let prev = write_tensor_q_at(&mut buf, 0, 0.0).unwrap();
197        assert!((prev - 0.0).abs() < 1e-6);
198        let t = read_tensor_at(&buf, 0).unwrap();
199        assert!(t.q.abs() < 1e-6);
200    }
201
202    #[test]
203    fn read_tensor_at_round_trip() {
204        let tensors = [
205            Tensor10D::ground_truth(0.0, 0.0, 0.1, 0.2, 0.3, 0.0, 1.0, 0.0, 0.5),
206            Tensor10D::ground_truth(0.0, 0.0, 0.4, 0.5, 0.6, 0.0, 1.0, 0.0, 0.75),
207        ];
208        let need = TensorBufferHeader::total_bytes(tensors.len());
209        let mut buf = vec![0u8; need];
210        write_tensor_buffer(&tensors, &mut buf).unwrap();
211        assert_eq!(tensor_node_count(&buf).unwrap(), 2);
212        let t1 = read_tensor_at(&buf, 1).unwrap();
213        assert!((t1.x - 0.4).abs() < 1e-5);
214        assert!((t1.sigma - 0.75).abs() < 1e-5);
215    }
216
217    #[test]
218    fn round_trip_write() {
219        let tensors = [
220            Tensor10D::ground_truth(0.0, 0.0, 0.1, 0.2, 0.3, 0.0, 1.0, 0.0, 0.5),
221            Tensor10D::ground_truth(0.0, 0.0, 0.4, 0.5, 0.6, 0.0, 1.0, 0.0, 0.5),
222        ];
223        let need = TensorBufferHeader::total_bytes(tensors.len());
224        let mut buf = vec![0u8; need];
225        let n = write_tensor_buffer(&tensors, &mut buf).unwrap();
226        assert_eq!(n, need);
227        let magic = u32::from_le_bytes(buf[0..4].try_into().unwrap());
228        assert_eq!(magic, TENSOR_BUFFER_MAGIC);
229    }
230}