Skip to main content

Module conformance

qualia_core_db::container_10d

Module conformance 

Source
Expand description

.10d v1 normative-spec conformance vectors + layout-table drift gate (P0.7 scaffold).

This module is the conformance harness — the single place where the .10d format’s golden vectors and layout tables are pinned. It has two jobs:

  1. Golden vectors (encode∘decode = identity). Each golden vector is a pinned byte sequence produced by the current implementation encoding a known input. The conformance test decodes the golden bytes, re-encodes the decoded content, and asserts the re-encoded bytes are byte-identical to the golden bytes. If any field offset, encoding order, CRC algorithm, or padding rule drifts, the golden vector won’t reproduce and the test breaks. Each golden vector also has a pinned content hash (CRC-32C over the golden bytes) — a double lock so a silent byte change is caught even if the re-encode path has a compensating bug.

  2. Layout-table drift gate. The size and offset of every field in Container10dHeader, SectionDescriptor, NodeMiniHeader, and MetricBranchDescriptor is asserted here in one place, so the spec’s layout tables and the Rust structs cannot drift apart. (The individual module tests also have offset_of assertions; this centralizes them as the spec’s single source of truth.)

Scaffold status (P0.7 partial): the golden vectors for the P0.1–P0.5 container (header + section table + CRC + NODE section) are pinned here. The mesh-section golden vectors (P0.4) are a clearly-marked placeholder — they will be added when P0.4 lands. The normative .10d v1 spec document (the prose layout tables, magic bytes, version number, etc.) is the execution plan’s P0.7 deliverable; this module is the executable conformance check, not the prose spec.

Constants§

GOLDEN_BARE_HEADER
Golden vector 1: a bare header (no section table). The proposed header with header_crc32c = 0 (unsealed — the seal is applied at the container level, not the bare-header level).
GOLDEN_BARE_HEADER_CRC
Pinned CRC-32C over GOLDEN_BARE_HEADER. Double lock: if the golden bytes are silently edited, this hash won’t match. Pinned 2026-07-04.
GOLDEN_MESH_ONLY_CRC
Pinned CRC-32C over the golden MESH-only container bytes (the unit cube encoded as a QuantizedMesh section in a .10d container, sealed with the whole-file CRC). Pinned at runtime — see the conformance test.
GOLDEN_NODE_ONLY_CRC
Golden vector 2: a NODE-only container — the proposed header + a section table with one Tensor10DNodes section containing 3 nodes in AoS layout. The header_crc32c is sealed (whole-file CRC).

Functions§

assert_layout_invariants
Assert every layout invariant the .10d v1 spec pins. Called from the conformance test; also callable from any test that wants to confirm the structs haven’t drifted.