Skip to main content

qualia_core_db/container_10d/header/
prefix.rs

1//! Header-only structural admission with an independently established full extent.
2//! No source authentication or whole-file CRC verification is performed here.
3use super::{
4    Container10dHeader, HEADER_BYTE_SIZE, HeaderParseError, MAGIC_10D, MAX_SECTION_COUNT,
5    SUPPORTED_HEADER_VERSIONS,
6};
7use crate::container_10d::{
8    axis_role::AxisRole,
9    metric_check::{MetricDivergence, verify_descriptor_against_reality},
10};
11/// Preserve structured metric errors on hot paths; no diagnostic string allocation.
12#[derive(Debug, Clone, PartialEq, Eq)]
13pub enum PrefixError {
14    Header(HeaderParseError),
15    Metric(MetricDivergence),
16}
17impl PrefixError {
18    pub(super) fn into_legacy(self) -> HeaderParseError {
19        match self {
20            Self::Header(e) => e,
21            Self::Metric(e) => HeaderParseError::MetricDivergence(e.to_string()),
22        }
23    }
24}
25/// Validate original header bytes without requiring payload/metadata to be resident.
26/// The caller must establish the declared extent independently and check sections.
27pub fn parse_header_prefix(data: &[u8], extent: u64) -> Result<Container10dHeader, PrefixError> {
28    use PrefixError::Header;
29    if data.len() < HEADER_BYTE_SIZE {
30        return Err(Header(HeaderParseError::TooShort { got: data.len() }));
31    }
32    if extent < HEADER_BYTE_SIZE as u64 {
33        return Err(Header(HeaderParseError::TooShort {
34            got: extent as usize,
35        }));
36    }
37    let header: Container10dHeader = bytemuck::pod_read_unaligned(&data[..HEADER_BYTE_SIZE]);
38    if header.magic != MAGIC_10D {
39        return Err(Header(HeaderParseError::BadMagic { got: header.magic }));
40    }
41    if !SUPPORTED_HEADER_VERSIONS.contains(&header.version) {
42        return Err(Header(HeaderParseError::UnknownVersion {
43            got: header.version,
44        }));
45    }
46    if header.pad0 != [0, 0] {
47        return Err(Header(HeaderParseError::NonZeroPadding { field: "pad0" }));
48    }
49    let (off, count) = (header.section_table_offset, header.section_count);
50    let valid = (off == 0 && count == 0)
51        || (off as u64 >= HEADER_BYTE_SIZE as u64
52            && u64::from(off) <= extent
53            && count != 0
54            && count <= MAX_SECTION_COUNT);
55    if !valid {
56        return Err(Header(HeaderParseError::BadSectionTablePointer {
57            offset: off,
58            count,
59        }));
60    }
61    for (i, &raw) in header.axis_roles.iter().enumerate() {
62        if AxisRole::from_u8(raw).is_none() || raw == AxisRole::Undefined as u8 {
63            return Err(Header(HeaderParseError::UndefinedAxisRole {
64                axis_index: i,
65                got: raw,
66            }));
67        }
68    }
69    verify_descriptor_against_reality(&header.metric_descriptor).map_err(PrefixError::Metric)?;
70    Ok(header)
71}
72#[cfg(test)]
73mod tests {
74    use super::*;
75    use crate::specialized_libs::computational_geometry::allocation_counter::AllocGuard;
76    #[test]
77    fn late_table_requires_independent_extent_not_fake_resident_bytes() {
78        let mut h = Container10dHeader::proposed();
79        h.section_table_offset = 4096;
80        h.section_count = 1;
81        let mut raw = [0; 65];
82        raw[1..].copy_from_slice(&h.encode_to_vec64());
83        assert!(Container10dHeader::parse(&raw[1..]).is_err());
84        let guard = AllocGuard::begin("10d-header-prefix", true);
85        assert_eq!(parse_header_prefix(&raw[1..], 8192).unwrap(), h);
86        assert!(parse_header_prefix(&raw[1..], 4095).is_err());
87        assert!(parse_header_prefix(&raw[1..], 63).is_err());
88        guard.check().unwrap();
89    }
90    #[test]
91    fn malformed_metric_rejection_uses_structured_error_without_allocation() {
92        let mut h = Container10dHeader::proposed();
93        h.metric_descriptor.branches[0].metric_kind = 0;
94        let mut raw = [0; 64];
95        h.encode(&mut raw);
96        let guard = AllocGuard::begin("10d-prefix-metric-refusal", true);
97        assert!(matches!(
98            parse_header_prefix(&raw, 64),
99            Err(PrefixError::Metric(_))
100        ));
101        guard.check().unwrap();
102    }
103}