Skip to main content

qualia_core_db/q42/emf_container/
mod.rs

1//! Standalone `.emf` (`EMF-64`) Electromagnetic & Wave-Optical Field Container Library.
2//!
3//! Output is strictly cache-aligned (64-byte headers, directory rows, and cell records)
4//! and little-endian, featuring 3D Hilbert volumetric brick clustering, CRC-32C,
5//! and complete 256-bit BLAKE3 digests. Legacy prefix checks are migration-only.
6
7pub mod chunk_directory;
8pub mod extension;
9pub mod header;
10pub mod reader;
11pub mod writer;
12
13pub use chunk_directory::*;
14pub use header::*;
15pub use extension::*;
16pub use reader::*;
17pub use writer::*;
18
19#[cfg(test)]
20mod tests {
21    use super::*;
22    use crate::q42::m64_matter::brick3d::encode_hilbert3d_u64;
23
24    #[test]
25    fn test_emf_container_roundtrip_and_brick_lookup() {
26        let mut writer = EmfContainerWriter::new(
27            [10.0, 20.0, 30.0],
28            0.5,
29            [2, 2, 2],
30            1_700_000_000.0,
31        );
32
33        let order = 2; // 4x4x4 brick grid
34        // Create 2 bricks with distinct cells
35        let mut brick0_cells = [EmfCellRecord64::default(); EMF_BRICK_CELLS];
36        let mut brick1_cells = [EmfCellRecord64::default(); EMF_BRICK_CELLS];
37
38        // Put a marker cell at local (3, 2, 1) in brick (0, 0, 0)
39        let local_idx0 = emf_brick_voxel_linear_index(3, 2, 1);
40        brick0_cells[local_idx0].e_field = [100.0, 200.0, 300.0];
41        brick0_cells[local_idx0].b_field = [0.003, -0.001, 0.002];
42        brick0_cells[local_idx0].wavelength_nm = 550.0; // green 550nm
43
44        // Put a marker cell at local (5, 6, 7) in brick (1, 1, 0)
45        let local_idx1 = emf_brick_voxel_linear_index(5, 6, 7);
46        brick1_cells[local_idx1].e_field = [50.0, 0.0, 0.0];
47        brick1_cells[local_idx1].b_field = [0.0, 0.0001, 0.0];
48        brick1_cells[local_idx1].wavelength_nm = 650.0; // red 650nm
49
50        let h0 = encode_hilbert3d_u64(0, 0, 0, order);
51        let h1 = encode_hilbert3d_u64(1, 1, 0, order);
52
53        writer.add_brick_chunk(h0, &brick0_cells, 0, 1, 0).unwrap();
54        writer.add_brick_chunk(h1, &brick1_cells, 0, 1, 0).unwrap();
55
56        let bytes = writer.to_bytes().expect("EMF serialize");
57        assert_eq!(bytes.len(), writer.total_required_bytes().expect("EMF size"));
58
59        // Parse with zero-copy reader
60        let reader = EmfContainerReader::parse(&bytes).expect("valid EMF container");
61        assert_eq!(reader.chunk_count(), 2);
62        assert_eq!(reader.header().grid_dims_bricks, [2, 2, 2]);
63        assert_eq!(reader.header().voxel_size_meters, 0.5);
64
65        // Lookup marker 0
66        let cell0 = reader
67            .lookup_brick_cell(0, 0, 0, 3, 2, 1, order)
68            .expect("found marker 0");
69        assert_eq!(cell0.e_field, [100.0, 200.0, 300.0]);
70        assert_eq!(cell0.wavelength_nm, 550.0);
71
72        // Lookup marker 1
73        let cell1 = reader
74            .lookup_brick_cell(1, 1, 0, 5, 6, 7, order)
75            .expect("found marker 1");
76        assert_eq!(cell1.e_field, [50.0, 0.0, 0.0]);
77        assert_eq!(cell1.wavelength_nm, 650.0);
78
79        // Poynting vector & energy density calculation on marker 0
80        let poynting = cell0.poynting_vector();
81        assert!(poynting[0] != 0.0 || poynting[1] != 0.0 || poynting[2] != 0.0);
82        let u_em = cell0.energy_density();
83        assert!(u_em > 0.0);
84
85        let dense = reader.dense_volume().expect("dense unpack");
86        assert_eq!((dense.nx, dense.ny, dense.nz, dense.nt), (16, 16, 16, 1));
87        // brick (0,0,0) local (lx,ly,lz)=(3,2,1) → x=3, y=2, z=1
88        let idx0 = (1 * 16 * 16) + (2 * 16) + 3;
89        assert_eq!(dense.cells[idx0].e_field, [100.0, 200.0, 300.0]);
90        assert_eq!(dense.cells[idx0].wavelength_nm, 550.0);
91        assert!((dense.cells[idx0].effective_sigma() - 0.5).abs() < 1e-5);
92        // brick (1,1,0) local (5,6,7) → x=13, y=14, z=7
93        let idx1 = (7 * 16 * 16) + (14 * 16) + 13;
94        assert_eq!(dense.cells[idx1].e_field, [50.0, 0.0, 0.0]);
95        assert_eq!(dense.cells[idx1].wavelength_nm, 650.0);
96    }
97
98    #[test]
99    fn test_emf_tampering_detection() {
100        let mut writer = EmfContainerWriter::new([0.0; 3], 1.0, [1, 1, 1], 0.0);
101        let cells = [EmfCellRecord64::default(); EMF_BRICK_CELLS];
102        writer.add_brick_chunk(0, &cells, 0, 1, 0).unwrap();
103
104        let mut bytes = writer.to_bytes().expect("EMF serialize");
105        assert!(EmfContainerReader::parse(&bytes).is_ok());
106
107        // Tamper with chunk payload byte
108        let payload_start = 64 + CHUNK_DIRECTORY_ENTRY_BYTES;
109        bytes[payload_start + 10] ^= 0xAA;
110
111        let res = EmfContainerReader::parse(&bytes);
112        assert_eq!(
113            res.err(),
114            Some(EmfError::FullHashMismatch { chunk_index: 0 }),
115            "Expected FullHashMismatch when payload is tampered"
116        );
117    }
118
119    #[test]
120    fn test_emf_legacy_52b_upgrade() {
121        // Legacy 52-byte tuple: [amp, phase, freq, m0..m9]
122        let legacy: [f32; 13] = [
123            10.0,       // amp
124            1.57,       // phase (pi/2)
125            5e14,       // freq 500 THz (~600nm)
126            0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, // 10D manifold
127        ];
128
129        let cell = EmfCellRecord64::from_legacy_52b(&legacy);
130        assert_eq!(std::mem::size_of::<EmfCellRecord64>(), 64);
131        assert_eq!(cell.e_field[0], 10.0);
132        assert_eq!(cell.coherence_phase, 1.57);
133        assert!(cell.wavelength_nm > 590.0 && cell.wavelength_nm < 610.0);
134        assert_eq!(cell.stokes_q, 0.1);
135        assert_eq!(cell.stokes_u, 0.2);
136        assert_eq!(cell.stokes_v, 0.3);
137        assert_eq!(cell.spectral_sigma, 0.4);
138        assert_eq!(cell.confidence_alpha, 1.0);
139    }
140
141    fn tiny_emf(chunks: u64) -> Vec<u8> {
142        let mut writer = EmfContainerWriter::new([0.0; 3], 1.0, [1, 1, 1], 0.0);
143        let cells = [EmfCellRecord64::default()];
144        for i in 0..chunks {
145            writer.add_brick_chunk(i, &cells, 0, 1, 0).unwrap();
146        }
147        writer.to_bytes().expect("EMF serialize")
148    }
149
150    #[test]
151    fn writer_size_helpers_reject_wrapping_mul() {
152        assert_eq!(
153            EmfContainerWriter::checked_payload_bytes(usize::MAX / 64 + 1),
154            Err(EmfError::ArithmeticOverflow)
155        );
156        assert_eq!(
157            EmfContainerWriter::checked_directory_bytes(usize::MAX / CHUNK_DIRECTORY_ENTRY_BYTES + 1),
158            Err(EmfError::ArithmeticOverflow)
159        );
160        let empty = EmfContainerWriter::new([0.0; 3], 1.0, [0, 0, 0], 0.0);
161        assert_eq!(empty.total_required_bytes().expect("empty EMF size"), 64);
162    }
163
164    #[test]
165    fn parse_with_limits_enforces_file_and_chunk_budgets() {
166        let bytes = tiny_emf(2);
167        assert!(EmfContainerReader::parse(&bytes).is_ok());
168        assert_eq!(
169            EmfContainerReader::parse_with_limits(
170                &bytes,
171                EmfReadLimits {
172                    max_file_bytes: bytes.len() - 1,
173                    max_chunks: 16,
174                }
175            )
176            .err(),
177            Some(EmfError::FileByteLimit)
178        );
179        assert_eq!(
180            EmfContainerReader::parse_with_limits(
181                &bytes,
182                EmfReadLimits {
183                    max_file_bytes: bytes.len(),
184                    max_chunks: 1,
185                }
186            )
187            .err(),
188            Some(EmfError::ChunkLimitExceeded)
189        );
190    }
191
192    #[test]
193    fn parse_rejects_directory_aliasing_header_and_payload_overlap() {
194        let mut bytes = tiny_emf(2);
195        let mut header: EmfContainerHeader = bytemuck::pod_read_unaligned(&bytes[..64]);
196        header.directory_offset = 0;
197        header.update_crc();
198        bytes[..64].copy_from_slice(bytemuck::bytes_of(&header));
199        assert_eq!(
200            EmfContainerReader::parse(&bytes).err(),
201            Some(EmfError::DirectoryBounds)
202        );
203
204        let mut bytes = tiny_emf(2);
205        let dir1 = 64 + CHUNK_DIRECTORY_ENTRY_BYTES;
206        let mut entry: EmfChunkDirectoryEntry =
207            bytemuck::pod_read_unaligned(&bytes[dir1..dir1 + CHUNK_DIRECTORY_ENTRY_BYTES]);
208        entry.byte_offset = 192;
209        entry.update_crc();
210        bytes[dir1..dir1 + CHUNK_DIRECTORY_ENTRY_BYTES].copy_from_slice(bytemuck::bytes_of(&entry));
211        assert_eq!(
212            EmfContainerReader::parse(&bytes).err(),
213            Some(EmfError::PayloadOverlap)
214        );
215    }
216
217    #[test]
218    fn dense_volume_rejects_decoded_cell_cap() {
219        // 17×16×8 bricks × 8³ cells = 1_114_112 > MAX_DENSE_CELLS (1_048_576).
220        // One tiny payload still parses; dense unpack must fail closed before vec![].
221        let mut writer = EmfContainerWriter::new([0.0; 3], 1.0, [17, 16, 8], 0.0);
222        let cells = [EmfCellRecord64::default()];
223        writer.add_brick_chunk(0, &cells, 0, 1, 0).unwrap();
224        let bytes = writer.to_bytes().expect("EMF serialize");
225        let reader = EmfContainerReader::parse(&bytes).expect("tiny payload parses");
226        let err = reader.dense_volume().expect_err("dense volume cap");
227        assert_eq!(
228            err,
229            EmfError::DenseVolumeCap {
230                cells: 1_114_112,
231                cap: MAX_DENSE_CELLS,
232            }
233        );
234        assert_eq!(
235            err.to_string(),
236            "EMF dense volume 1114112 cells exceeds cap 1048576"
237        );
238    }
239}