Skip to main content

qualia_core_db/q42/m64_matter/
layout.rs

1//! M64 Matter-64 Container Byte Layout and Header.
2//!
3//! A sibling of the parameter/probabilistic `.p64` weight container.
4//! Carrying independent section magic `b"m64\0"`, `.m64` represents the physical
5//! and material universe: geodetic point-tensors, biological morphogenesis,
6//! multi-layer subsurface strata stacks, and stationary-action phase junctures.
7//!
8//! Every record and header is strictly 64 bytes (L1 cache-line DOD).
9
10use crate::container_10d::crc32c::{crc32c, crc32c_update};
11use bytemuck::{Pod, Zeroable};
12
13pub use super::chunk_directory::{M64ChunkDirectoryEntry, M64Error, CHUNK_DIRECTORY_ENTRY_BYTES};
14
15/// Magic identifier for .m64 matter container files: ASCII `m64\0`.
16pub const M64_MAGIC: [u8; 4] = *b"m64\0";
17
18/// Backward-compatible magic identifier for early .e64 prototypes: ASCII `e64\0`.
19pub const E64_MAGIC: [u8; 4] = *b"e64\0";
20
21/// Current container format version.
22pub const M64_VERSION: u32 = 2;
23
24/// Standard record byte length across all M64 modes.
25pub const M64_RECORD_BYTES: usize = 64;
26
27/// Mode 0x00: Raw LiDAR / Geodetic surface anchor points & spectral reflectance.
28pub const M64_MODE_POINT: u8 = 0x00;
29/// Mode 0x01: Holographic biological entity & allometric morphogenesis.
30pub const M64_MODE_HOLO: u8 = 0x01;
31/// Mode 0x02: Multi-layer subsurface strata column & fluid depth stack.
32pub const M64_MODE_STRATA: u8 = 0x02;
33/// Mode 0x03: Quantum q-branch boundary conditions & CSG tool excavation.
34pub const M64_MODE_PHASE_JUNCTURE: u8 = 0x03;
35/// Mode 0x04: Radial-Edge B-Rep shell face records (per-record CRC-32C).
36pub const M64_MODE_SHELL: u8 = 0x04;
37/// Mode 0x05: Biological constitutive, densitometric & fiber records (per-record CRC-32C).
38pub const M64_MODE_BIO_TISSUE: u8 = 0x05;
39
40/// Canonical M64 chunk record mode discriminant.
41#[repr(u8)]
42#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
43pub enum M64CellMode {
44    Point = M64_MODE_POINT,
45    Holo = M64_MODE_HOLO,
46    Strata = M64_MODE_STRATA,
47    PhaseJuncture = M64_MODE_PHASE_JUNCTURE,
48    Shell = M64_MODE_SHELL,
49    BioTissue = M64_MODE_BIO_TISSUE,
50}
51
52impl M64CellMode {
53    #[inline]
54    pub const fn as_u8(self) -> u8 {
55        self as u8
56    }
57}
58
59impl TryFrom<u8> for M64CellMode {
60    type Error = M64Error;
61
62    #[inline]
63    fn try_from(value: u8) -> Result<Self, Self::Error> {
64        match value {
65            M64_MODE_POINT => Ok(Self::Point),
66            M64_MODE_HOLO => Ok(Self::Holo),
67            M64_MODE_STRATA => Ok(Self::Strata),
68            M64_MODE_PHASE_JUNCTURE => Ok(Self::PhaseJuncture),
69            M64_MODE_SHELL => Ok(Self::Shell),
70            M64_MODE_BIO_TISSUE => Ok(Self::BioTissue),
71            other => Err(M64Error::InvalidRecordMode(other)),
72        }
73    }
74}
75
76/// Flag indicating chunks are organized as 16x16x16 3D volumetric bricks.
77pub const M64_FLAG_3D_BRICK_16X16X16: u16 = 1 << 4;
78/// Flag indicating local relative metric (LRM3) frame is active (SRID = 0).
79pub const M64_FLAG_LOCAL_METRIC_LRM3: u16 = 1 << 5;
80
81/// Local micrometer spatial reference ID (SRID = 0) used with LRM3.
82pub const M64_SRID_LOCAL_MICROMETER: u32 = 0;
83
84/// Return `true` if slice begins with `m64\0` or `e64\0`.
85#[inline]
86pub fn has_m64_magic(data: &[u8]) -> bool {
87    data.starts_with(&M64_MAGIC) || data.starts_with(&E64_MAGIC)
88}
89
90/// Fixed 64-Byte M64 Container Header (cache-line DOD).
91#[repr(C, align(64))]
92#[derive(Debug, Copy, Clone, PartialEq, Pod, Zeroable)]
93pub struct M64Header {
94    /// 0x00..0x04: ASCII Magic `m64\0` (or `e64\0`)
95    pub magic: [u8; 4],
96    /// 0x04..0x08: Format version (1/2, or explicit developmental georaster 3)
97    pub version: u32,
98    /// 0x08..0x10: Header size (64 for v1/v2; 192 for opt-in georaster v3)
99    pub header_size: u64,
100    /// 0x10..0x18: Total file size in bytes
101    pub total_file_size: u64,
102    /// 0x18..0x20: Geodetic Reference Origin: [latitude, longitude] in degrees
103    pub spatial_origin: [f32; 2],
104    /// 0x20..0x28: Elevation datum: [base_altitude_m, vertical_scale_factor]
105    pub elevation_datum: [f32; 2],
106    /// 0x28..0x30: Byte offset to chunk directory table
107    pub chunk_table_offset: u64,
108    /// 0x30..0x38: Number of spatial chunk partitions
109    pub chunk_count: u64,
110    /// 0x38..0x3C: CRC-32C of bytes 0x00..0x38 and 0x3C..0x40 (excludes this field)
111    pub header_crc32c: u32,
112    /// 0x3C..0x40: Container flags (covered by header CRC-32C)
113    pub container_flags: u32,
114}
115
116pub type E64Header = M64Header;
117
118impl Default for M64Header {
119    fn default() -> Self {
120        Self {
121            magic: M64_MAGIC,
122            version: M64_VERSION,
123            header_size: 64,
124            total_file_size: 64,
125            spatial_origin: [0.0, 0.0],
126            elevation_datum: [0.0, 1.0],
127            chunk_table_offset: 64,
128            chunk_count: 0,
129            header_crc32c: 0,
130            container_flags: 0,
131        }
132    }
133}
134
135impl M64Header {
136    /// CRC-32C over header bytes excluding the CRC field (0x00..0x38 and 0x3C..0x40).
137    #[inline]
138    pub fn compute_crc32c(&self) -> u32 {
139        let bytes: &[u8; 64] = bytemuck::cast_ref(self);
140        Self::crc_covering_flags(bytes)
141    }
142
143    /// Legacy CRC-32C over the first 56 bytes (does not cover `container_flags`).
144    #[inline]
145    fn crc_legacy_first_56(bytes: &[u8; 64]) -> u32 {
146        crc32c(&bytes[..56])
147    }
148
149    #[inline]
150    fn crc_covering_flags(bytes: &[u8; 64]) -> u32 {
151        let mut crc = crc32c_update(0xFFFF_FFFF, &bytes[..0x38]);
152        crc = crc32c_update(crc, &bytes[0x3C..0x40]);
153        !crc
154    }
155
156    /// Update `header_crc32c` with the flags-covering CRC-32C.
157    #[inline]
158    pub fn update_crc(&mut self) {
159        self.header_crc32c = self.compute_crc32c();
160    }
161
162    /// Validate magic, version, header size, and CRC-32C.
163    ///
164    /// Accepts the flags-covering digest (current writers) or the legacy first-56
165    /// digest so existing files remain readable.
166    #[inline]
167    pub fn validate(&self) -> Result<(), M64Error> {
168        if !has_m64_magic(&self.magic) {
169            return Err(M64Error::InvalidMagic);
170        }
171        if !matches!(self.version, 1 | 2 | 3) {
172            return Err(M64Error::InvalidVersion(self.version as u16));
173        }
174        let required_size = if self.version == 3 { 192 } else { 64 };
175        if self.header_size != required_size {
176            return Err(M64Error::InvalidHeaderSize);
177        }
178
179        let bytes: &[u8; 64] = bytemuck::cast_ref(self);
180        let covering = Self::crc_covering_flags(bytes);
181        if self.header_crc32c == covering || self.header_crc32c == Self::crc_legacy_first_56(bytes)
182        {
183            Ok(())
184        } else {
185            Err(M64Error::ChecksumMismatch {
186                stored: self.header_crc32c,
187                computed: covering,
188            })
189        }
190    }
191}