qualia_core_db/container_10d/
header.rs1use 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
32pub const MAGIC_10D: [u8; 4] = *b"10d\0";
34
35pub const HEADER_VERSION: u16 = 2;
38pub const LEGACY_HEADER_VERSION: u16 = 1;
40pub const SUPPORTED_HEADER_VERSIONS: [u16; 2] = [LEGACY_HEADER_VERSION, HEADER_VERSION];
41
42pub const FLAG_DEFAULT_DISPOSITION_REFUSE: u16 = 1 << 0;
46
47pub const HEADER_BYTE_SIZE: usize = 64;
50
51#[derive(Debug, Clone, PartialEq, Eq)]
53pub enum HeaderParseError {
54 TooShort { got: usize },
56 BadMagic { got: [u8; 4] },
58 UnknownVersion { got: u16 },
60 NonZeroPadding { field: &'static str },
62 UndefinedAxisRole { axis_index: usize, got: u8 },
64 MetricDivergence(String),
67 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
102pub const MAX_SECTION_COUNT: u32 = 1024;
107
108#[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 pub section_table_offset: u32,
142 pub section_count: u32,
146}
147
148impl Default for Container10dHeader {
149 fn default() -> Self {
150 Self::proposed()
151 }
152}
153
154impl Container10dHeader {
155 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 pub fn legacy_v1() -> Self {
180 let mut header = Self::proposed();
181 header.version = LEGACY_HEADER_VERSION;
182 header
183 }
184
185 pub fn encode(&self, out: &mut [u8; HEADER_BYTE_SIZE]) {
188 let bytes: &[u8; HEADER_BYTE_SIZE] = bytemuck::cast_ref(self);
191 *out = *bytes;
192 }
193
194 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 assert_eq!(d.branches[1].folded_axes.count_ones(), 3);
465 assert_eq!(d.branches[2].folded_axes.count_ones(), 3);
466 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
485pub mod prefix;