Skip to main content

qualia_core_db/container_10d/
header.rs

1//! Normative `.10d` container header — the barrier surface every later P0
2//! task consumes.
3//!
4//! Layout: 64 bytes, `repr(C)`, all fields naturally aligned, one explicit
5//! `pad0[2]` field that must be zero. The header carries:
6//!
7//! - magic + version (the parse-rejection gates for bad magic / unknown version)
8//! - `axis_roles[10]` — the normative axis-role taxonomy (one `AxisRole` per
9//!   axis in `AXIS_ORDER`); any `Undefined` entry is rejected
10//! - `metric_descriptor` — the [`super::metric_check::MetricCompletenessDescriptor`]
11//!   verified against `Tensor10D::full_distance`'s actual v-branch behaviour;
12//!   a diverging descriptor is rejected (the "queryability claim == code" gate)
13//! - `header_crc32c` — **spec-reserved in P0.1**: the field exists and is
14//!   written as zero on encode, but P0.3 wires the shared CRC-32C (delegated
15//!   from `q42/p64_weight.rs`) and starts enforcing it. P0.1 does not enforce
16//!   the CRC — that is P0.3's acceptance gate, not P0.1's.
17//! - `reserved[8]` — zero, future use (governance default-disposition flags,
18//!   capability bits, time-base selector — all P0.2+ territory).
19//!
20//! The header is the foundation every later P0 task writes into. Its 64-byte
21//! physical layout stays fixed across v1 and v2; v2 changes the file contract
22//! while preserving a dual-version reader. `header_is_pod_with_exact_size`
23//! asserts the exact layout and zero padding.
24
25use bytemuck::{Pod, Zeroable};
26
27use crate::container_10d::axis_role::PROPOSED_AXIS_ROLES;
28use crate::container_10d::metric_check::{
29    proposed_metric_descriptor, MetricCompletenessDescriptor,
30};
31
32/// `.10d` container magic — ASCII `"10d\0"`.
33pub const MAGIC_10D: [u8; 4] = *b"10d\0";
34
35/// Current `.10d` writer version. V2 formalizes the single-envelope, typed-parts
36/// contract while retaining the v1 header's 64-byte physical layout.
37pub const HEADER_VERSION: u16 = 2;
38/// V1 remains readable for existing assets. New writers emit [`HEADER_VERSION`].
39pub const LEGACY_HEADER_VERSION: u16 = 1;
40pub const SUPPORTED_HEADER_VERSIONS: [u16; 2] = [LEGACY_HEADER_VERSION, HEADER_VERSION];
41
42/// Header flag bit 0: default disposition = Refuse. A reader that ignores the
43/// Governance section still fails closed. Always set in v1 headers produced by
44/// [`Container10dHeader::proposed`].
45pub const FLAG_DEFAULT_DISPOSITION_REFUSE: u16 = 1 << 0;
46
47/// Exact byte size of the header POD. Asserted by the size-of test so a
48/// future field addition cannot silently shift the layout.
49pub const HEADER_BYTE_SIZE: usize = 64;
50
51/// Parse error categories — one per acceptance-gate rejection.
52#[derive(Debug, Clone, PartialEq, Eq)]
53pub enum HeaderParseError {
54    /// Input shorter than `HEADER_BYTE_SIZE`.
55    TooShort { got: usize },
56    /// Magic bytes do not match `MAGIC_10D`.
57    BadMagic { got: [u8; 4] },
58    /// Version is not recognized by this reader.
59    UnknownVersion { got: u16 },
60    /// A padding/reserved field is non-zero (the "zero padding" gate).
61    NonZeroPadding { field: &'static str },
62    /// An axis role byte is not a defined `AxisRole` variant.
63    UndefinedAxisRole { axis_index: usize, got: u8 },
64    /// The metric-completeness descriptor diverges from `full_distance`'s
65    /// actual v-branch behaviour. Carries the divergence detail.
66    MetricDivergence(String),
67    /// The section-table pointer in the header is inconsistent: offset is not
68    /// `0` (no table) and not `>= HEADER_BYTE_SIZE` and within the file, or
69    /// `section_count` exceeds `MAX_SECTION_COUNT`, or exactly one of
70    /// (offset, count) is zero.
71    BadSectionTablePointer { offset: u32, count: u32 },
72}
73
74impl std::fmt::Display for HeaderParseError {
75    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
76        match self {
77            Self::TooShort { got } => write!(
78                f,
79                "10d header too short: got {got} bytes, need {HEADER_BYTE_SIZE}"
80            ),
81            Self::BadMagic { got } => write!(f, "10d bad magic: got {got:?}, need {MAGIC_10D:?}"),
82            Self::UnknownVersion { got } => write!(
83                f,
84                "10d unknown version: got {got}, supported versions are {SUPPORTED_HEADER_VERSIONS:?}"
85            ),
86            Self::NonZeroPadding { field } => write!(f, "10d non-zero padding in field {field:?}"),
87            Self::UndefinedAxisRole { axis_index, got } => write!(
88                f,
89                "10d undefined axis role at index {axis_index}: raw {got}"
90            ),
91            Self::MetricDivergence(msg) => write!(f, "10d {msg}"),
92            Self::BadSectionTablePointer { offset, count } => write!(
93                f,
94                "10d bad section-table pointer: offset={offset}, count={count}"
95            ),
96        }
97    }
98}
99
100impl std::error::Error for HeaderParseError {}
101
102/// Maximum number of section descriptors the parser will accept. Bounds the
103/// section-table allocation against a hostile/malformed file. 1024 is far
104/// beyond any realistic `.10d` (the design's section types number ~10) while
105/// keeping the table trivially small.
106pub const MAX_SECTION_COUNT: u32 = 1024;
107
108/// The normative `.10d` header — v1/v2 are 64 bytes, `repr(C)`, naturally aligned.
109///
110/// Field layout (offsets):
111/// ```text
112/// offset  size  field
113/// 0       4     magic
114/// 4       2     version
115/// 6       2     flags
116/// 8       10    axis_roles          (one AxisRole u8 per AXIS_ORDER axis)
117/// 18      2     pad0                (must be zero — aligns metric_descriptor to 4)
118/// 20      32    metric_descriptor   (4 x MetricBranchDescriptor, 8 bytes each)
119/// 52      4     header_crc32c       (spec-reserved in P0.1; P0.3 wires shared CRC-32C)
120/// 56      4     section_table_offset (byte offset from file start; 0 = no table)
121/// 60      4     section_count        (number of SectionDescriptor rows; 0 = no table)
122/// ```
123///
124/// The `section_table_offset` + `section_count` fields at offsets 56–63 were
125/// the `reserved[8]` field in the initial P0.1 landing; P0.2 defines their
126/// meaning within v1 (the POD layout is unchanged — only a reserved field's
127/// semantics are now specified). See the P0.2 progress-log entry.
128#[repr(C)]
129#[derive(Debug, Clone, Copy, PartialEq, Eq, Pod, Zeroable)]
130pub struct Container10dHeader {
131    pub magic: [u8; 4],
132    pub version: u16,
133    pub flags: u16,
134    pub axis_roles: [u8; 10],
135    pub pad0: [u8; 2],
136    pub metric_descriptor: MetricCompletenessDescriptor,
137    pub header_crc32c: u32,
138    /// Byte offset of the section table from the start of the file. `0` means
139    /// no section table (a bare header — `section_count` must also be `0`).
140    /// Otherwise must be `>= HEADER_BYTE_SIZE` and within the file.
141    pub section_table_offset: u32,
142    /// Number of `SectionDescriptor` rows in the section table. `0` means no
143    /// table (a bare header — `section_table_offset` must also be `0`).
144    /// Must be `<= MAX_SECTION_COUNT`.
145    pub section_count: u32,
146}
147
148impl Default for Container10dHeader {
149    fn default() -> Self {
150        Self::proposed()
151    }
152}
153
154impl Container10dHeader {
155    /// Construct the current v2 header: v1 physical layout, shared typed-part
156    /// envelope semantics, axis-role taxonomy and metric descriptor. CRC is
157    /// sealed by the enclosing writer after the section table is encoded.
158    pub fn proposed() -> Self {
159        let mut axis_roles = [0u8; 10];
160        for (i, role) in PROPOSED_AXIS_ROLES.iter().enumerate() {
161            axis_roles[i] = *role as u8;
162        }
163        Self {
164            magic: MAGIC_10D,
165            version: HEADER_VERSION,
166            flags: FLAG_DEFAULT_DISPOSITION_REFUSE,
167            axis_roles,
168            pad0: [0, 0],
169            metric_descriptor: proposed_metric_descriptor(),
170            header_crc32c: 0,
171            section_table_offset: 0,
172            section_count: 0,
173        }
174    }
175
176    /// Construct a v1 header for compatibility fixtures and migration tests.
177    /// Production writers should use [`Self::proposed`] so newly written files
178    /// advertise the current format revision.
179    pub fn legacy_v1() -> Self {
180        let mut header = Self::proposed();
181        header.version = LEGACY_HEADER_VERSION;
182        header
183    }
184
185    /// Encode the header into a caller-supplied 64-byte buffer (little-endian
186    /// where applicable; the POD is already LE-friendly). Zero-alloc.
187    pub fn encode(&self, out: &mut [u8; HEADER_BYTE_SIZE]) {
188        // SAFETY: Container10dHeader is repr(C) + Pod + size 64. Casting to
189        // bytes is sound; copy into the caller buffer.
190        let bytes: &[u8; HEADER_BYTE_SIZE] = bytemuck::cast_ref(self);
191        *out = *bytes;
192    }
193
194    /// Encode into a freshly-owned 64-byte array. Convenience for tests and
195    /// writers that are not on a zero-heap hot path.
196    pub fn encode_to_vec64(&self) -> [u8; HEADER_BYTE_SIZE] {
197        let mut out = [0u8; HEADER_BYTE_SIZE];
198        self.encode(&mut out);
199        out
200    }
201
202    /// Parse and validate a 64-byte header. Runs every P0.1 acceptance gate:
203    /// bad magic, unknown version, non-zero structural padding, undefined axis
204    /// role, metric-completeness divergence from `full_distance` reality, and
205    /// (P0.2) a consistent section-table pointer.
206    pub fn parse(data: &[u8]) -> Result<Container10dHeader, HeaderParseError> {
207        prefix::parse_header_prefix(data, data.len() as u64).map_err(prefix::PrefixError::into_legacy)
208    }
209}
210
211#[cfg(test)]
212mod tests {
213    use super::*;
214    use crate::container_10d::axis_role::{AxisRole, AXIS_ORDER};
215    use crate::container_10d::metric_check::{MetricKind, BOUNDARY_CLIQUE_BRANCH_INDEX};
216
217    #[test]
218    fn header_is_pod_with_exact_size_and_zero_padding() {
219        assert_eq!(
220            std::mem::size_of::<Container10dHeader>(),
221            HEADER_BYTE_SIZE,
222            "header must be exactly {HEADER_BYTE_SIZE} bytes"
223        );
224        // Offset assertions so doc and code cannot drift.
225        assert_eq!(std::mem::offset_of!(Container10dHeader, magic), 0);
226        assert_eq!(std::mem::offset_of!(Container10dHeader, version), 4);
227        assert_eq!(std::mem::offset_of!(Container10dHeader, flags), 6);
228        assert_eq!(std::mem::offset_of!(Container10dHeader, axis_roles), 8);
229        assert_eq!(std::mem::offset_of!(Container10dHeader, pad0), 18);
230        assert_eq!(
231            std::mem::offset_of!(Container10dHeader, metric_descriptor),
232            20
233        );
234        assert_eq!(std::mem::offset_of!(Container10dHeader, header_crc32c), 52);
235        assert_eq!(
236            std::mem::offset_of!(Container10dHeader, section_table_offset),
237            56
238        );
239        assert_eq!(std::mem::offset_of!(Container10dHeader, section_count), 60);
240        // The proposed (bare) header has zero pad and no section table.
241        let h = Container10dHeader::proposed();
242        assert_eq!(h.version, HEADER_VERSION);
243        assert_eq!(h.pad0, [0, 0]);
244        assert_eq!(h.section_table_offset, 0);
245        assert_eq!(h.section_count, 0);
246    }
247
248    #[test]
249    fn encode_is_bit_identical_across_two_runs() {
250        let h = Container10dHeader::proposed();
251        let mut a = [0u8; HEADER_BYTE_SIZE];
252        let mut b = [0u8; HEADER_BYTE_SIZE];
253        h.encode(&mut a);
254        h.encode(&mut b);
255        assert_eq!(
256            a, b,
257            "two encodes of the same header must be byte-identical"
258        );
259    }
260
261    #[test]
262    fn round_trip_proposed_header() {
263        let h = Container10dHeader::proposed();
264        let bytes = h.encode_to_vec64();
265        let parsed = Container10dHeader::parse(&bytes).expect("proposed header must parse");
266        assert_eq!(parsed, h);
267    }
268
269    #[test]
270    fn v1_header_remains_readable_and_round_trips_without_rewriting_its_version() {
271        let legacy = Container10dHeader::legacy_v1();
272        let bytes = legacy.encode_to_vec64();
273        let parsed = Container10dHeader::parse(&bytes).expect("v1 header remains supported");
274        assert_eq!(parsed.version, LEGACY_HEADER_VERSION);
275        assert_eq!(parsed, legacy);
276    }
277
278    #[test]
279    fn parse_rejects_bad_magic() {
280        let mut bytes = Container10dHeader::proposed().encode_to_vec64();
281        bytes[0] = b'x';
282        let err = Container10dHeader::parse(&bytes).expect_err("bad magic must reject");
283        assert!(matches!(err, HeaderParseError::BadMagic { .. }), "{err}");
284    }
285
286    #[test]
287    fn parse_rejects_unknown_version() {
288        let mut bytes = Container10dHeader::proposed().encode_to_vec64();
289        // version is at offset 4, little-endian u16.
290        bytes[4] = 0xff;
291        bytes[5] = 0xff;
292        let err = Container10dHeader::parse(&bytes).expect_err("unknown version must reject");
293        assert!(
294            matches!(err, HeaderParseError::UnknownVersion { got: 0xffff }),
295            "{err}"
296        );
297    }
298
299    #[test]
300    fn parse_rejects_undefined_axis_role() {
301        let mut bytes = Container10dHeader::proposed().encode_to_vec64();
302        // axis_roles starts at offset 8; set the first (q) to Undefined (0).
303        bytes[8] = AxisRole::Undefined as u8;
304        let err = Container10dHeader::parse(&bytes).expect_err("undefined axis role must reject");
305        assert!(
306            matches!(
307                err,
308                HeaderParseError::UndefinedAxisRole { axis_index: 0, .. }
309            ),
310            "{err}"
311        );
312    }
313
314    #[test]
315    fn parse_rejects_unknown_axis_role_byte() {
316        let mut bytes = Container10dHeader::proposed().encode_to_vec64();
317        // axis_roles[3] (x) — set to an undefined raw value (5).
318        bytes[8 + 3] = 5;
319        let err =
320            Container10dHeader::parse(&bytes).expect_err("unknown axis role byte must reject");
321        assert!(
322            matches!(
323                err,
324                HeaderParseError::UndefinedAxisRole {
325                    axis_index: 3,
326                    got: 5
327                }
328            ),
329            "{err}"
330        );
331    }
332
333    #[test]
334    fn parse_rejects_non_zero_pad0() {
335        let mut bytes = Container10dHeader::proposed().encode_to_vec64();
336        bytes[18] = 1;
337        let err = Container10dHeader::parse(&bytes).expect_err("non-zero pad0 must reject");
338        assert!(
339            matches!(err, HeaderParseError::NonZeroPadding { field: "pad0" }),
340            "{err}"
341        );
342    }
343
344    #[test]
345    fn parse_rejects_section_table_offset_below_header_size() {
346        // section_table_offset at offset 56 (u32 LE). Set it to 8 (< 64) with
347        // a non-zero count — must reject.
348        let mut bytes = Container10dHeader::proposed().encode_to_vec64();
349        bytes[56..60].copy_from_slice(&8u32.to_le_bytes());
350        bytes[60..64].copy_from_slice(&1u32.to_le_bytes());
351        let err = Container10dHeader::parse(&bytes).expect_err("offset < header size must reject");
352        assert!(
353            matches!(err, HeaderParseError::BadSectionTablePointer { .. }),
354            "{err}"
355        );
356    }
357
358    #[test]
359    fn parse_rejects_section_count_without_offset() {
360        // offset = 0 but count != 0 — inconsistent, must reject.
361        let mut bytes = Container10dHeader::proposed().encode_to_vec64();
362        bytes[60..64].copy_from_slice(&1u32.to_le_bytes());
363        let err = Container10dHeader::parse(&bytes).expect_err("count without offset must reject");
364        assert!(
365            matches!(err, HeaderParseError::BadSectionTablePointer { .. }),
366            "{err}"
367        );
368    }
369
370    #[test]
371    fn parse_rejects_offset_without_count() {
372        // offset != 0 but count = 0 — inconsistent, must reject.
373        let mut bytes = Container10dHeader::proposed().encode_to_vec64();
374        bytes[56..60].copy_from_slice(&64u32.to_le_bytes());
375        let err = Container10dHeader::parse(&bytes).expect_err("offset without count must reject");
376        assert!(
377            matches!(err, HeaderParseError::BadSectionTablePointer { .. }),
378            "{err}"
379        );
380    }
381
382    #[test]
383    fn parse_accepts_bare_header_no_section_table() {
384        // The proposed header has offset=0, count=0 — a bare header. Must parse.
385        let bytes = Container10dHeader::proposed().encode_to_vec64();
386        let parsed = Container10dHeader::parse(&bytes).expect("bare header must parse");
387        assert_eq!(parsed.section_table_offset, 0);
388        assert_eq!(parsed.section_count, 0);
389    }
390
391    #[test]
392    fn parse_rejects_metric_completeness_claiming_v1_folds_t() {
393        let mut bytes = Container10dHeader::proposed().encode_to_vec64();
394        // metric_descriptor starts at offset 20. Each branch is 8 bytes:
395        //   v_class@+0, metric_kind@+1, folded_axes@+2 (u16 LE), reserved@+4
396        // Branch 1 (v=1 cyclic) starts at offset 20 + 8 = 28.
397        // Set the t bit (bit 6) in folded_axes at offset 28 + 2.
398        let folded_offset = 28 + 2;
399        bytes[folded_offset] |= 1 << 6;
400        let err =
401            Container10dHeader::parse(&bytes).expect_err("diverging metric descriptor must reject");
402        match err {
403            HeaderParseError::MetricDivergence(msg) => {
404                assert!(msg.contains("v=1"), "message must name v=1: {msg}");
405                assert!(msg.contains("t"), "message must name axis t: {msg}");
406            }
407            other => panic!("expected MetricDivergence, got {other:?}"),
408        }
409    }
410
411    #[test]
412    fn parse_rejects_metric_completeness_claiming_v3_folds_x() {
413        let mut bytes = Container10dHeader::proposed().encode_to_vec64();
414        // Branch 3 (v>=3 catch-all) starts at offset 20 + 3*8 = 44.
415        // folded_axes at offset 44 + 2. Set bit 3 (x).
416        let folded_offset = 44 + 2;
417        bytes[folded_offset] |= 1 << 3;
418        let err =
419            Container10dHeader::parse(&bytes).expect_err("diverging metric descriptor must reject");
420        assert!(
421            matches!(err, HeaderParseError::MetricDivergence(_)),
422            "{err:?}"
423        );
424    }
425
426    #[test]
427    fn parse_rejects_too_short_input() {
428        let short = [0u8; 32];
429        let err = Container10dHeader::parse(&short).expect_err("short input must reject");
430        assert!(
431            matches!(err, HeaderParseError::TooShort { got: 32 }),
432            "{err}"
433        );
434    }
435
436    #[test]
437    fn proposed_header_carries_option_a_taxonomy() {
438        let h = Container10dHeader::proposed();
439        for (i, &raw) in h.axis_roles.iter().enumerate() {
440            let role = AxisRole::from_u8(raw).expect("proposed roles are all defined");
441            assert_eq!(
442                role as u8, PROPOSED_AXIS_ROLES[i] as u8,
443                "axis {}",
444                AXIS_ORDER[i]
445            );
446        }
447        // μ (index 8) is the dual-role coordinate+carrier
448        assert_eq!(h.axis_roles[8], AxisRole::CoordinateCarrier as u8);
449    }
450
451    #[test]
452    fn proposed_header_carries_documented_limitation_descriptor() {
453        let h = Container10dHeader::proposed();
454        let d = &h.metric_descriptor;
455        // v=0 euclidean folds all seven
456        assert_eq!(d.branches[0].v_class, 0);
457        assert_eq!(d.branches[0].metric_kind, MetricKind::Euclidean as u8);
458        assert_eq!(
459            d.branches[0].folded_axes.count_ones(),
460            7,
461            "v=0 must fold all seven coordinate axes"
462        );
463        // v=1 / v=2 fold xyz only (3 bits)
464        assert_eq!(d.branches[1].folded_axes.count_ones(), 3);
465        assert_eq!(d.branches[2].folded_axes.count_ones(), 3);
466        // v>=3 catch-all folds none
467        assert_eq!(d.branches[BOUNDARY_CLIQUE_BRANCH_INDEX].folded_axes, 0);
468        assert_eq!(
469            d.branches[BOUNDARY_CLIQUE_BRANCH_INDEX].metric_kind,
470            MetricKind::BoundaryClique as u8
471        );
472    }
473
474    #[test]
475    fn proposed_header_default_disposition_is_refuse() {
476        let h = Container10dHeader::proposed();
477        assert_ne!(
478            h.flags & FLAG_DEFAULT_DISPOSITION_REFUSE,
479            0,
480            "v1 header must fail closed by default"
481        );
482    }
483}
484
485/// Allocation-free structural prefix validation for bounded selective readers.
486pub mod prefix;