diff --git a/SPEC.md b/SPEC.md index 2d6c37f..a6b7434 100644 --- a/SPEC.md +++ b/SPEC.md @@ -408,6 +408,22 @@ Byte 8-19: [12-byte nonce] Byte 20+: [ciphertext + 16-byte GCM tag] ``` +### 7.5 Golden Test Corpus + +The wire examples above are illustrative. The authoritative byte-level wire format reference is the **golden test corpus** maintained at [`testdata/wire/`](https://github.com/TeoSlayer/pilotprotocol/tree/main/testdata/wire) in the implementation repository. + +This corpus contains byte-for-byte snapshots of every Pilot Protocol wire frame across layers L1, L4, L5, L6, and L7, including packet headers, relay messages, key exchange frames, encrypted payloads, and SACK acknowledgements. + +Each `.bin` file is parsed by the live production decoders, re-marshalled, and asserted byte-identical by [`TestWireFormatGolden`](https://github.com/TeoSlayer/pilotprotocol/blob/main/tests/zz_wire_golden_test.go). Any wire-format regression — a field reorder, an extra padding byte, a checksum tweak — fails the test and names the offending frame. + +**Regenerating the corpus** is a wire-format change and requires explicit version-bump approval. The generator lives at `cmd/wire-gen/main.go` behind the `wirecorpus` build tag: + +``` +go run -tags=wirecorpus ./cmd/wire-gen +``` + +See the [`testdata/wire/README.md`](https://github.com/TeoSlayer/pilotprotocol/blob/main/testdata/wire/README.md) for the full frame inventory and regeneration instructions. + --- ## 8. Version Negotiation