Conformance — ANLA-MVP v0.1

Everything needed to check an independent implementation of the specification, and everything the two reference implementations check about each other.

What is here

The Python side of the suite lives in 0 and drives run_node.mjs through a subprocess, so one pytest run exercises both implementations.

Running it

In a browser, with nothing installed: <https://anla.evemisslab.com/demo/> runs 76 of these assertions live, including the byte-for-byte comparison against the hashes committed here. It fetches nothing — the fixtures and vectors are compiled into the page — so a red row there is a real defect on your platform.

Locally:

python -m pytest python/tests -q

201 tests. The cross-implementation tests skip themselves if node is not on PATH; everything else runs with nothing but a Python interpreter.

Individual pieces, if you want them separately:

node conformance/run_node.mjs selftest
python conformance/make_vectors.py --check
node conformance/run_node.mjs verify conformance/vectors/basic-store.anla

T-AUX-1 is worth singling out, because it is easy to write as a test that cannot fail. Comparing a manifest with a copy of itself passes no matter what the code under test did. The assertion here rewrites the archive — anla strip does the same thing from the command line — and then compares the rewritten archive's extraction against the original's.

Why the fixtures are shaped this way

fixtures.json is deliberately not generated by either implementation. Both read it and pack the same trees with the same plan and the same fixed variable inputs, and the suite then asserts the outputs are equal byte for byte. A fixture emitted by one of the implementations under test would only prove that implementation is self-consistent.

Two details are worth knowing before writing a third implementation:

Paths are sometimes given as code points. The interesting Unicode cases — a precomposed/decomposed pair, an emoji with a variation selector — are exactly the ones an editor, a filesystem or a copy-paste can silently normalize. A byte-exactness test whose fixture can be rewritten in transit tests nothing, so those paths are carried as path_codepoints arrays.

Not every case is byte-exact across implementations. Cases flagged byte_exact_across_implementations: false use DEFLATE, and two DEFLATE encoders legitimately produce different valid output for the same input. For those, the promise is mutual readability and per-implementation reproducibility, not equal bytes. This is stated in SPEC.md §10 rather than quietly worked around.

The assertions

Implementing ANLA-MVP v0.1 elsewhere

The order that makes this least painful:

1. Read. Parse the header, the footer, then the manifest. Verify the manifest hash against the footer before parsing it. Every frozen vector should open.
2. Verify. Check each chunk descriptor against its record, each stored payload hash, each decoded chunk against its content id, then each file's coverage and hash. Now T-CHK, T-COV and T-ORG-1 should pass.
3. Refuse. Work through the T-HDR, T-FTR, T-REC, T-PTH and T-BMB rows. This is where a decoder either becomes trustworthy or does not.
4. Write. Emit store-only archives first and compare against basic-store.anla byte for byte. If the bytes differ, the difference is almost always canonical JSON key ordering, integer formatting, or object ordering — see SPEC.md §6 and §8.1.
5. Compress. Add deflate, remembering it is the zlib wrapper (RFC 1950), not raw DEFLATE.

Differential fuzzing

python tools/fuzz_differential.py -n 20000 --seed 1 --keep

The suite proves the two implementations agree on the inputs someone thought of, which is a weaker statement than it looks. The fuzzer mutates the frozen vectors — bit flips, truncation, hostile length and offset fields with the covering CRC repaired, and manifest-level defects re-sealed so every hash is correct — and asks one question of each mutant: do both implementations reach the same verdict?

Not "is the verdict right": that needs an oracle. Agreement needs none, and disagreement is always a defect in an implementation or in this specification for having left the case open.

Two grades:

• Divergence — one accepts, the other refuses. Always a bug. Fails the run.
• Code mismatch — both refuse, with different codes. SPEC.md fixes the verification order, so for a mutant with one defect the codes should match. This is reported, kept as a file, and does not fail the run, because it may be a specification gap and the triage belongs to a person.

It has produced two findings so far, and both were invisible to the hand-written suite:

1. A 64-bit field above Number.MAX_SAFE_INTEGER was a resource-limit error in JavaScript and a malformed-manifest error in Python. Both refused; one was misclassifying. SPEC.md §11 now says which.
2. Record sequence was specified and unchecked. The spec said "1-based, strictly increasing" and neither implementation looked at the field. Python accepted sequence = 2^63; JavaScript refused it only because it could not represent the number. The rule is now stated as arithmetic a reader can actually evaluate (SPEC.md §4.3) and both enforce it.

The second one is the argument for the whole exercise: no amount of writing more tests by hand would have found it, because the tests and the implementations shared the same blind spot.

If a vector disagrees with your reading of the specification, the specification is what is wrong — open an issue. A frozen vector and a normative document that disagree is a defect in the document, because the vectors are what third parties will actually test against.