The immutable cryptographic foundation. Every shard sealed. Every claim provable. Nothing changes here without a frozen-spec RFC.
Genesis is the only package in the AXM ecosystem with write access to the signed shard format. Everything else reads. This boundary is the invariant that makes long-term verification possible.
Tamper-evident by construction. Every byte in a shard is covered by a BLAKE3 Merkle tree. The root is signed post-quantum. Tamper any byte — content, graph, evidence, or extension — and verification fails. There is no escape hatch.
The spec is frozen. spec/v1.0/SPECIFICATION.md is normative and sealed. Changes require an RFC in rfcs/, a new spec version, and a migration path. Minor versions add; they never remove.
The gold shard is the definition of correctness. fm21-11-hemorrhage-v1 is never recompiled. A verifier change that breaks the gold shard is rejected — the gold shard wins. CI enforces this on every commit.
Post-quantum by default. New shards use ML-DSA-44 (FIPS 204). Ed25519 shards remain valid indefinitely — backward compatibility is a hard requirement. Cryptographic agility is handled through suite identifiers, not protocol breaks.
Six cryptographic and structural primitives are frozen across all axm-genesis >= 1.x releases. A spoke built against any of these will continue to work without modification.
Two constructions: legacy duplicate-odd-leaf (Ed25519) and domain-separated RFC 6962 odd-leaf promotion (ML-DSA-44). Leaf: BLAKE3(0x00 ‖ path ‖ 0x00 ‖ bytes). Node: BLAKE3(0x01 ‖ left ‖ right). Sorted by UTF-8 path.
FIPS 204 post-quantum signature (Dilithium2). Deterministic: same key and message always produce the same signature. pk=1312 B, sig=2420 B. Identified by suite field axm-blake3-mldsa44 in manifest.
All graph, evidence, and extension tables are Apache Parquet with explicit Arrow schemas. Deterministically written — sorted, compressed with zstd. DuckDB queries extensions at query time with no central registry.
Supersession chains via ext/lineage@1.parquet. Cross-shard claim links via ext/references@1.parquet. Both are Merkle-covered extension tables — optional, additive, and verifiable.
Universal base pass produced by axm-chat distill: topic tags, named people, tools, project references, question text, resolution state, tone — written to ext/episodes@1.parquet. DuckDB-queryable without an LLM.
Gated second pass for technical conversations. Extracts problem statement, graveyard of failed attempts, working solution, and architectural rules — written to ext/engineering@1.parquet.
Suite-aware since v1.1.0 (RFC 0001). The suite field in manifest.json selects the signing algorithm and Merkle construction. Absent means Ed25519 legacy.
| Suite Identifier | Algorithm | Key | Signature | Merkle | Status |
|---|---|---|---|---|---|
(absent) or ed25519 |
Ed25519 | 32 B | 64 B | Duplicate odd-leaf | Stable |
| axm-blake3-mldsa44 | ML-DSA-44 (FIPS 204) | 1312 B | 2420 B | RFC 6962 odd-leaf promotion | Post-Quantum Default |
All three layers use the same Genesis container format. The distinction is semantic — enforced by convention, not by protocol. Genesis seals layers 1 and 2. It never touches layer 3.
The reference verifier axm-verify runs seven checks in sequence. A failure at any step halts the pipeline. Exit 0 = PASS, Exit 1 = FAIL, Exit 2 = malformed layout.
Required root items: manifest.json, sig/, content/, graph/, evidence/. Optional: ext/. Unexpected items trigger E_LAYOUT_DIRTY. Symlinks, dotfiles rejected unconditionally.
manifest.json is read once — the same bytes are used for both Merkle verification and signature verification to prevent TOCTOU swaps. Bounded by 256 KiB limit.
Requires --trusted-key. The shard's publisher.pub must match the trusted key exactly. Then the manifest signature is verified against that key using the suite-appropriate algorithm.
All shard files except manifest.json and sig/ are hashed using the suite-specific Merkle construction. Computed root must match manifest.integrity.merkle_root exactly.
Column names, types, and counts for entities, claims, provenance, and spans are checked against frozen Arrow schemas. Row counts bounded by policy limit. Null values in required columns fail.
Every claim subject and entity-type object must exist in entities. Every provenance and span must reference a content file whose SHA-256 is in sources. Byte ranges are validated and span text is confirmed against file bytes.
If content/cam_latents.bin is present: file magic AXLF verified, then AXLR records scanned for gap-free monotone frame_id sequence. Any gap emits E_BUFFER_DISCONTINUITY. Absent = silent pass.
Spokes that produce shards must satisfy all five requirements. Run the conformance suite with pytest tests/test_conformance.py -v — all 13 tests must pass.
| REQ | Description | Error Codes |
|---|---|---|
| REQ 1 | Manifest integrity — byte-exact signature over the manifest | E_SIG_INVALID E_MERKLE_MISMATCH |
| REQ 2 | Content identity — all content files covered by Merkle tree | E_MERKLE_MISMATCH E_REF_SOURCE |
| REQ 3 | Lineage events — all references valid, no nulls in required columns | E_REF_ORPHAN E_SCHEMA_NULL |
| REQ 4 | Proof bundle — valid signature from a trusted publisher key | E_SIG_INVALID E_SIG_MISSING |
| REQ 5 | Non-selective recording — no gaps in binary hot stream (embodied spokes) | E_BUFFER_DISCONTINUITY |
All error codes are prefixed E_ and defined in axm_verify/const.py. Existing codes are never renamed or removed — only new codes are added in minor versions.
| Code | Meaning |
|---|---|
| Layout | |
| E_LAYOUT_MISSING | Required directory or file absent from shard root |
| E_LAYOUT_DIRTY | Unexpected file or directory found at shard root or in required subdirectory |
| E_DOTFILE | Dotfile found anywhere in the shard tree |
| Manifest | |
| E_MANIFEST_SYNTAX | manifest.json is not valid JSON |
| E_MANIFEST_SCHEMA | manifest.json missing required field or field has wrong type |
| Signature | |
| E_SIG_MISSING | sig/manifest.sig or sig/publisher.pub not found |
| E_SIG_INVALID | Signature does not verify, key mismatch, or wrong key size for suite |
| Integrity | |
| E_MERKLE_MISMATCH | Computed Merkle root does not match stored value in manifest |
| Schema | |
| E_SCHEMA_READ | Parquet file unreadable or exceeds size / row-count limit |
| E_SCHEMA_MISSING | Required Parquet file absent |
| E_SCHEMA_TYPE | Wrong column name, type, or count in a required table |
| E_SCHEMA_NULL | Null value found in a required column |
| E_SCHEMA_ENUM | Invalid object_type or tier value |
| Identity | |
| E_ID_ENTITY | entity_id does not match recomputed hash from namespace + label |
| E_ID_CLAIM | claim_id does not match recomputed hash from subject + predicate + object |
| References | |
| E_REF_ORPHAN | Claim subject or entity-type object not found in entities table |
| E_REF_SOURCE | span or provenance source_hash not in content/, or byte range out of bounds |
| E_REF_READ | Content file unreadable during span byte-range verification |
| Stream Continuity (REQ 5) | |
| E_BUFFER_DISCONTINUITY | Frame gap, bad magic, or truncation in cam_latents.bin (embodied spokes only) |