miniopenenv

docs/CONFORMANCE.md → html

The conformance ledger

build/conformance/expectations.json is the machine-readable verdict for every exchange in the captured reference corpus — the corpus being tests/fixtures/reference-corpus.json, the exchanges recorded byte for byte from real reference servers. This page is what the ledger contains, how to regenerate it, and how a second implementation grades itself with it.

The ledger holds one entry per HTTP message and per WebSocket frame. Each entry carries three things: the verdict tests/t_replay.c reached (REPLAYED, REFUSED, UNREPRODUCIBLE, or NOT-YET), the sentence explaining any divergence, and the normalisation to apply before comparing. A totals block closes the file, with the same subtotals the test asserts.

Regenerate it from the repository root with make conformance. That target sets OE_CONFORMANCE_LEDGER=build/conformance/expectations.json and replays the corpus through the pure functions; the variable gates the write. An ordinary make test produces no ledger. make check regenerates it, and fails if its entry count ever drifts from the total the test asserts.

The file exists for a second-language implementer — somebody writing the server in Go, Rust, or anything else. You grade yourself from this file alone, never reading a line of C. Replay each corpus request through your own code, apply the entry's named normalisation, and require the bytes to match the corpus response for every REPLAYED entry. Each REFUSED, UNREPRODUCIBLE, or NOT-YET entry marks a response you are free — or, for UNREPRODUCIBLE, unable — to answer differently, with the reason given in full.

Your conformance score is then the fraction of REPLAYED entries your implementation reproduces byte for byte. It reads straight off the ledger: no interpreter, no corpus archaeology, and no C.