Conformance¶

Content addressing only works if the same logical object always serializes to the same bytes. The conformance corpus is the internal quality gate that guarantees this for TOVIO: it pins the canonical encoding and content address of every object type as frozen fixtures, and the reference implementation is tested against them on every change.

This page describes what the corpus contains and how the reference implementation uses it, versioned alongside the storage format.

Why a corpus exists¶

Canonical encoding is a content-addressing invariant: a non-deterministic encoding is not a style preference, it is a correctness bug, because it changes an object's address. The corpus turns that invariant into a test. If the encoder reproduces every fixture's bytes and address, objects continue to interoperate across TOVIO versions; a divergence on even one byte would compute a different address and break sync and deduplication for already-written repositories.

What the corpus pins¶

The corpus is organized by format version: conformance/<version>/. Version 1 pins an addressed vector for every object kind in the data-model registry — the Phase-0 kinds blob, chunk, chunk-manifest, tree, commit, and conflict; the permission and audit objects policy-blob, policy-chunk, policy-manifest, capability, audit-entry, and obliteration; and the later, additively introduced kinds such as behavioral, symbol-shard, symbol-xref and their sealed forms, lane-ref-update, resolution-op, rationale, and the session and audit-checkpoint objects. New kinds are appended; existing vectors never change.

Each addressed fixture is a JSON entry in vectors.json:

Field	Meaning
`name`	Fixture id (e.g. `blob_hello`, `chunk_manifest`).
`kind`	The object kind (`blob`, `tree`, `commit`, …).
`description`	What the fixture exercises.
`address`	The object's content address, `blake3:<hex>`.
`hex`	The addressed bytes — raw content for `blob`/`chunk`, canonical CBOR for structured objects.

A representative entry:

{
  "name": "blob_hello",
  "kind": "blob",
  "description": "a small text file",
  "address": "blake3:4321fae3f39665682914de5dec718fd33c3be477b162546057f7b321e961dfd3",
  "hex": "68656c6c6f20746f76696f0a"
}

The hex field is the exact, addressable byte sequence. For a blob it is the raw file content; for a tree, commit, or other structured object it is the canonical CBOR including the {"v","t"} envelope (storage format). The address is the BLAKE3-256 of those bytes.

Sibling files in the same directory pin the semantics that sit on top of the bytes, each in a language-neutral form an independent implementation can consume without a Rust encoder:

File	What it pins
`negative.json`	Nine deterministic-CBOR rejection cases with stable error classes — empty input, non-shortest integers, indefinite lengths, unsorted or duplicate map keys, invalid UTF-8, trailing data, floats outside the profile, truncation.
`policy-evaluation.json`	Policy-expression decisions for the exact grammar, precedence, claim-set membership, and caller-supplied expiry instant.
`ref-merge.json`	CRDT lane-register winner decisions through the full deterministic tie-break order.
`enforcement.json`, `token-validity.json`, `delegation.json`	Capability-token scope/allow-deny/clearance order, signed token validity in its normative check order, and delegation-chain narrowing.
`abe.json`	Canonical encodings for the Tier-2 ABE policy and recipient payload.
`shard-map.json`, `path-object-index.json`, `shard-inventory.json`, `replication.json`, `request-proof.json`	Signed Forge routing, inventory, replication, and request-proof structures that need cross-implementation byte parity but are not object kinds.
`manifest.json`	The self-describing inventory: the exact byte length and SHA-256 of every corpus file, and each vector's family and `REQ-*` coverage, so an independent consumer fails closed on drift.

What the corpus checks¶

For every fixture, the reference implementation satisfies all of the following:

Encode identically. Producing the fixture's object through the encoder yields the exact hex bytes — a byte-for-byte match of the canonical CBOR (or raw payload).
Address identically. Hashing those bytes with BLAKE3-256 yields the exact address.
Round-trip cleanly. Decoding the hex and re-encoding it reproduces the same bytes with no changes.
Reject non-canonical input. Each negative.json case is rejected with its exact error class — never silently accepted, and never collapsed into a generic parse failure.
Keep physical forms transparent (filesystem profile). The loose, DEFLATE-coded, and packed physical forms of every corpus object decode to the identical logical bytes and address, and an interrupted repack or GC leaves every reachable object resolvable.

The cryptographic constructions have their own required vector classes — AEAD known-answer tests, the X25519_wrap/unwrap round-trip, age recipient stanzas, signing-payload vectors, domain-separation negatives, and address-hashing vectors for policy-blob/policy-chunk — cross-checked against this corpus. See the crypto envelope summary.

How the reference implementation uses it¶

In the reference (tovio-core) workspace, an integration test regenerates the addressed fixtures from the live encoder and asserts byte-for-byte equality; the Forge-domain and protocol crates do the same for their fixture files. A diff in the corpus therefore means the on-disk format changed — which must be a deliberate format-version bump, not an accident. An independent Go runner, with its own BLAKE3 and deterministic-CBOR implementations and no shared encoder, consumes the same directory and reproduces the addresses, the policy and ref-merge decisions, and the manifest digests.

Regeneration is intentional and rare. On a deliberate format change, the reference implementation regenerates the object vectors with:

TOVIO_RECORD=1 cargo test -p tovio-core --test conformance

(the Forge and protocol fixture files have their own recording tests, and scripts/check_conformance_manifest.py re-verifies the manifest afterwards) …and then bumps the format version and adds a new conformance/<version>/ directory rather than editing an existing one in place. An existing version's fixtures are frozen: they are the contract that already-written repositories rely on.

Frozen fixtures

The conformance corpus is versioned with the storage format. Existing vector bytes, names, addresses, and order are immutable; a backward-compatible v1 contract can be appended with an ADR, a live-encoder vector, an exact manifest update, and independent consumer coverage, while a change to canonical encoding requires a new format version and a new corpus directory.

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure