Conformance

An implementation in any language must reach the same identities. Conformance is therefore something you run, not something you claim.

The corpus is not owned here. It is published at gaussia-labs/boltzmann-conformance as spec-level data, and vendored into this package at the version golden.CORPUS_VERSION names. The authority is the corpus; this SDK is one of its consumers, and CI fails if the vendored copy drifts.That split matters. While these files lived here, their location, naming and shape were governed by a Python package layout, and “conforming” quietly degraded into “matches pyboltzmann, bugs included”. A vector this SDK cannot reproduce is now a disagreement to resolve, not a file to edit.

Golden vectors, for any language

The vectors ship inside the wheel as plain JSON, so a non-Python implementation can read them from an installed pyboltzmann without this SDK running any of its own code — or read them straight from the corpus repository, which needs no install at all.

from boltzmann.conformance import golden

golden.CORPUS_VERSION      # which published corpus this package carries
golden.CORPUS_REPOSITORY   # where a disagreement gets resolved

for vector in golden.load("block_ids.json")["vectors"]:
    assert my_implementation.block_id(vector["envelope"]) == vector["block_id"]

golden.load_all()          # every file, by name
golden.registry()          # the schema registry companion

File	Fixes
`serialization.json`	The canonical byte sequence for a given payload — and the documents that MUST be rejected
`block_ids.json`	The identity of a given envelope
`actor_ids.json`	The two forms an actor identifier takes, and the ones that MUST be refused
`schema_selection.json`	The `schema_version` oldest-that-fits assigns a payload against the registered set
`merkle_roots.json`	The root of a given set of block ids
`inclusion_proofs.json`	The audit path for a given leaf and tree size, at sizes 1, a power of two, and odd
`sshsig.json`	The SSHSIG wire format, byte for byte — including the signed-data blob, which tells a framing bug from a signing bug
`signatures.json`	Whole chains, published test key pairs, and the verdict a verifier MUST reach for each of the paper’s worked cases
`reconciliation.json`	The set Equation 4 must produce — and the two reconciliations that MUST be refused

The identity files cover the whole chain from a payload to a version identifier. Agree on all of them and two clients share a brain; disagree on any and they do not, whatever else they implement. The authenticity files cover a different failure: divergence there is not silent identity drift but a verifier accepting what another refuses, which is worse.

A published vector never changes. A case whose expected output would change is either a bug in whatever produced it, or a new serialization identifier — never a corrected vector. Editing one silently would let two implementations agree with the corpus at different times and disagree with each other.

The schema registry

schema_version sits inside the envelope and therefore inside block_id, so “registered” cannot mean “whatever this deployment implements”. The registered set is the companion document the corpus publishes:

golden.registry()["schemas"]["semantic"]   # every registered semantic schema, oldest first

A block is written under the oldest registered schema its payload satisfies, and the proposer does not get to choose. Writing under the newest instead would let a new schema silently re-version every block written afterwards, including blocks that use nothing it added. Defining a block class registers its schema with this process, which is not the same thing as the schema being registered with the protocol. When the two disagree, the SDK says so:

WARNING  MySemanticV9 defines semantic schema_version 9, which the schema registry does not carry.
         Blocks written under it are named in a way no other implementation reproduces...

It warns rather than refuses. Defining a schema is how one comes to be proposed for registration, so an exception would make the SDK unusable for the work that precedes it — the failure being guarded against is doing it silently, and ending up with a per-deployment registry by accident.

The behavioral suite, for Python

A Python implementation inherits the suite directly. These are pytest classes — collect them and they run against your code, so they need pytest:

pip install 'pyboltzmann[conformance]'

Without it, importing one tells you so. The vectors above are unaffected: they need neither pytest nor any extra.

from boltzmann.conformance import BlockStoreConformance


class TestMyStore(BlockStoreConformance):
    def make_store(self):
        return MyStore()

from boltzmann.conformance import BrainReaderConformance


class TestMyClient(BrainReaderConformance):
    def make_reader(self):
        return MyClient(...)

Two suites need no hook at all, because they test the SDK’s own invariants over your types:

from boltzmann.conformance import CompositionConformance, IdentityConformance, MerkleConformance


class TestIdentity(IdentityConformance): pass
class TestMerkle(MerkleConformance): pass
class TestComposition(CompositionConformance): pass

What each suite asserts

IdentityConformance

The three levels of hashes are not interchangeable, and parsing refuses the wrong level rather than coercing it.
Canonicalization erases the order a mapping was built in.
Floats and unsafe integers are refused inside a payload.
block_id matches the published vectors, which other languages also read.

MerkleConformance

The root is a function of the set: two parties that assembled the same blocks obtain the same root.
Duplicates collapse — a set of content-addressed blocks cannot hold the same block twice.
An empty composition still has a well-defined root.
Every leaf proves into the root, at every tree size.
A proof does not verify against another root.

AuthenticityConformance

Every published signatures.json case reaches its stated verdict: the paper’s worked cases — admission by quorum, self-admission failing with no pin, retirement standing where compromise withdraws — as executable oracles over your store.
Signing never changes a snapshot’s identity: detached means detached.
Needs the [authenticity] extra, because authorized without the mathematics is the one claim this role must never make.

CompositionConformance

Dropping yields a new root, and does not disturb the earlier one.
Episodic refuses to drop — append-only by protocol, not by policy.
A diff reports exactly what an incremental update must fetch.

BlockStoreConformance

Storing identical bytes twice is a no-op.
Every memory type round-trips, decoding back to an equal block with the same identity.
A missing block is an error, not an empty result.
Corruption is detected: bytes that do not hash to their digest are refused.
A store must not normalize — non-canonical bytes do not decode.
A tombstoned block is distinguishable from a missing one.
Deleting reclaims both the bytes and the record of them.
The store can enumerate what it holds, which is what mark-and-sweep needs.

BrainReaderConformance

Satisfies the BrainReader contract, and reports what is installed.
A module that is not installed is an error, never an empty module.
Resolves members; refuses to resolve a non-member however it is stored.
Proves membership, and a proof does not verify against another root.
Verifies itself, and reports resolvability three ways.
search returns verified data and not prose, reports the roots it verified against, and honours a memory-type filter.
No match is an answer and not an error.
An unregistered index is refused rather than faked.

Fixtures

Two helpers build valid blocks, so a suite does not need your constructors:

from boltzmann.conformance import sample_canonical, sample_semantic

sample_semantic(label="Fourier series")
sample_canonical(payload=b"%PDF-1.7 lecture notes")

What the SDK asserts about itself

Two tests in the repository are worth knowing about, because they constrain what this package may ever ship:

No NotImplementedError stubs. An unimplemented function is worse than an interface: it looks callable and is not.
Nothing declared and unreachable. Every type, enum member and constant is produced by something.

Together they mean the public surface is exactly what works — there is no aspirational API.

Getting started

Core concepts

Guides

Golden vectors, for any language

The schema registry

The behavioral suite, for Python

What each suite asserts

Fixtures

What the SDK asserts about itself

​Golden vectors, for any language

​The schema registry

​The behavioral suite, for Python

​What each suite asserts

​Fixtures

​What the SDK asserts about itself

Golden vectors, for any language

The schema registry

The behavioral suite, for Python

What each suite asserts

Fixtures

What the SDK asserts about itself