1use bytemuck::{bytes_of, Pod, Zeroable};
6
7use super::Tensor10D;
8
9pub const TENSOR_BUFFER_MAGIC: u32 = 0x5134_322A; pub const TENSOR_BUFFER_VERSION: u16 = 1;
11pub const TENSOR_STRIDE: usize = 40;
12pub 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 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 pub fn total_bytes(node_count: usize) -> usize {
40 std::mem::size_of::<TensorBufferHeader>() + node_count * TENSOR_STRIDE
41 }
42}
43
44#[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#[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#[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#[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#[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
110pub 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
128pub 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}