conformance specification
| field | value |
|---|---|
| version | 0.2 |
| status | implemented — stack snapshot in soft3 |
| authors | mastercyb |
| date | October 2026 |
canonical encoding
every Conformant type defines exactly one byte sequence as its canonical encoding. canonicity rules:
- fixed-width integers in little-endian
- variable-length values prefixed by length (varint)
- sets and maps in lexicographic order of canonical key encoding
- floats forbidden in any
Conformanttype - nested
Conformantvalues inlined under the same rules
a Conformant impl that admits two encodings of the same value is a bug.
fingerprint
fingerprint(value) = hemera(canonical_encoding(value))
hemera is cyber-hemera 0.3 (Poseidon2 over Goldilocks, 32-byte output); a different output width is a different fingerprint function and does not compile. 32 bytes, Goldilocks-field-aligned, proof-friendly. the fingerprint is the snapshot.
encoding snapshot file
the stack snapshot lives in soft3/conformance/snapshots/encoding.snap
(per-crate conformance/ directories adopt the same format as each crate
promotes its own types). shape — fingerprints are 64 hex digits, shortened here:
# generated by `cargo conformance --bless`; do not edit by hand
# encoding.snap — canonical encodings
hemera::params@v1 tier=gamma hb246...0a1e
nebu::Goldilocks@v1 tier=gamma h5276...e31c
nox::atom@v1 tier=gamma h4e3a...cb37
one line per type. one fingerprint per line. tier inline. @vN suffix permits parallel encodings during migration.
mechanism snapshot file
soft3/conformance/snapshots/mechanism.snap (same per-crate convention):
# generated by `cargo conformance --bless`; do not edit by hand
# mechanism.snap — mechanism outputs on fixed scenarios
nox::reduce@v1 :: "spec-add" tier=gamma h…
nox::trace@v1 :: "spec-add" tier=gamma h…
zheng::verify@v1 :: "quote-add" tier=gamma h…
scenario name is the lookup key. the fingerprint binds the mechanism's canonical output bytes for the named scenario — for nox, the reduction outcome and the trace; for zheng, the proof bytes and the verifier's verdicts.
tiers
| tier | meaning | drift in CI | bless ceremony |
|---|---|---|---|
| alpha | mutable | silent rewrite | none |
| beta | tracked | note | commit message notes change |
| gamma | enforced | fails build | cargo conformance --bless |
| delta | locked | fails build | --bless --tier delta + commit tag [conformance:delta] |
| epsilon | governed | fails build | bless + detached signature appended to .snap file |
promotion is one-way: alpha → beta → gamma → delta → epsilon. demotion requires the same ceremony as breaking a snapshot at the target tier.
tooling
cargo conformance --check # regenerate, compare byte for byte; CI and the release train invoke this
cargo conformance --bless [--tier <t>] # regenerate snapshots + proof fixtures, print the entry diff
cargo conformance show <substring> # print current fingerprint and tier of matching keys
cargo conformance manifest # print the protocol stability root of the current build
a clean checkout has no installed subcommand, so the runner is built from
soft3/conformance/rs (cyber-conformance, binary cargo-conformance):
cargo run --locked --manifest-path soft3/conformance/rs/Cargo.toml \
--bin cargo-conformance -- conformance --check
the crate closes over the stack by path: its siblings (hemera, strata,
nox, lens, zheng, tade, bbg, foculus, cybergraph, inf, tru,
tok) sit beside soft3 — the release train's origin-default checkout
layout. --stack <dir> and --conformance <dir> override the locations.
snapshot directory
| path | written by | read by --check |
|---|---|---|
conformance/snapshots/encoding.snap |
bless | yes, byte for byte |
conformance/snapshots/mechanism.snap |
bless | yes, byte for byte |
conformance/snapshots/manifest.snap |
bless | yes, byte for byte — counts and root |
conformance/snapshots/provenance.toml |
bless | no — the sibling revisions and date of the last bless |
conformance/fixtures/nox/*.nox |
hand | input programs |
conformance/fixtures/zheng/*.proof |
bless | committed proof wire bytes, verified by the current verifier |
each .snap file is a pure function of its entries: two comment lines, then
one line per entry sorted by key, the key column padded to the longest key.
check
--check regenerates every entry from the current build and compares each
file with the committed bytes. any difference is explained entry by entry:
| change | fails |
|---|---|
| entry added or removed | always — the stable surface changed shape |
| fingerprint drift | at gamma, delta, epsilon (as committed); reported as a note at alpha/beta |
| tier changed | always — promotion and demotion are bless ceremonies |
| bytes differ, entries equal | always — hand edit |
| manifest root differs, entries equal | always — hand edit |
| fixture on disk read by no surface | always |
| invariant violated | always (below) |
invariants hold independently of the snapshot: hemera agrees with its own
published vectors (hemera/vectors/hemera.json; the tree section is the
fixed-chunk tree, fixed_chunk_root), intt(ntt(x)) = x, fixture programs
that state an outcome (result, cost, error, halt) produce it, every
freshly produced proof verifies, and every committed proof fixture verifies
under the current verifier.
bless
--bless regenerates the snapshots, rewrites the proof fixtures from the
current prover, deletes fixtures no surface reads, records
provenance.toml, and prints every change (added, removed, drift,
retier). it writes nothing when an invariant fails, or when a change
touches an entry above the allowed tier: gamma by default, --tier delta
for delta entries (with the [conformance:delta] commit tag); epsilon
entries never move without a detached governance signature. snapshots are
blessed from the stack at its origin default branches — never from
integration lines — and committed in the same pull request as the change
that moved them.
surfaces
| owner | encodings | mechanisms |
|---|---|---|
| hemera | params |
hash (published vectors, sponge rate boundaries 55/56/57/112 bytes, 1000-byte ramp), hash_secret (= hash, invariant), keyed_hash, derive_key, tree::root_hash (content-defined) and tree::fixed_chunk_root across the 4 KiB chunk boundary, the raw permutation |
| nebu (strata) | Goldilocks (canonical reduction) |
add/sub/mul over edge×edge and ramp×ramp, neg/square/pow7/inv, exp, sqrt + legendre, batch_inv, ntt (8, 32), multilinear_eval, bytes_to_field_elements, Fp2/Fp3/Fp4 |
| nox | atom, pair, tree, wire push/request/response |
reduce (outcome: result tree + cost, halt, or error kind) and trace (the rows zheng proves) for every fixtures/nox/*.nox program — the pattern spec's test vectors and one per pattern — and every nox/jets/*.nox formula |
| zheng | ProofParams::default, Statement |
per scenario: commit (fresh proof wire bytes) and verify (verdict on the committed fixture plus nine single-bit tamperings). scenarios: three trace proofs without opening rows, the hash-binding proof [15 [1 42]], the Brakedown PCS open/verify_eval |
| tade | every chunk constructor, LEB128 varints | the incremental reader in 7-byte feeds, through Molecule and back |
| cybergraph | — | a file's particle, bbg::axon_id, bbg::balance_key, private_network, Scope::hash, Signal::hash and content_id, the bbg root after two signals pass the link verb |
zheng's ZHENGPF1 profiles (0 public, 3 state-public, and the rest) live on
the 0.4 integration line, not on zheng's default branch; each enters this
surface as a commit/verify scenario pair when it lands there.
manifest construction
manifest_root = hemera(
canonical_encoding(
sort_by_name(all_encoding_snapshots ∪ all_mechanism_snapshots)
)
)
the manifest binds the entire conformance state of the workspace into a single 32-byte root. a verifier that holds the root and a zheng proof learns the workspace's stability fingerprint at that git revision.
dependencies
| crate | role |
|---|---|
| hemera | fingerprint function |
| nox | mechanism simulator (deterministic VM) |
| zheng | proves a manifest; manifest root is public input |
conformance depends downward only. soft3 re-exports verify_conformance(root, proof) for clients that check a manifest without running the harness.
non-goals
conformance asserts that encodings and mechanism outputs do not drift. it does not assert correctness — a stable-but-wrong encoding still passes conformance. correctness lives in each crate's own test suite. conformance is the layer beneath correctness: it guarantees that yesterday's correct answer and today's are the same answer.
status
implemented in rs/ as cyber-conformance 0.2 with the cargo-conformance
runner; the release train's conformance-snapshot gate runs --check
(soft3 specs/releases.md). first bless: 2026-10-10, from the origin default
branches recorded in snapshots/provenance.toml; evidence in
audit/conformance-first-bless-2026-10-10.md. every entry starts at tier gamma.
next: per-crate Conformant adoption (mudra candidate), the ZHENGPF1
profile scenarios when they reach zheng's default branch, and a zheng proof
over the manifest root.