From af31b67b91c7c3ae500c40cab0139169b9d4d3bd Mon Sep 17 00:00:00 2001 From: matthew-pilot Date: Thu, 18 Jun 2026 11:41:02 +0000 Subject: [PATCH] =?UTF-8?q?docs(spec):=20add=20golden=20test=20corpus=20re?= =?UTF-8?q?ference=20(=C2=A77.5)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a new subsection to §7 Wire Examples referencing the golden test corpus at testdata/wire/ in the implementation repository as the authoritative byte-level wire format reference. Includes links to the corpus directory, the TestWireFormatGolden invariance gate test, and regeneration instructions. Closes PILOT-422 --- SPEC.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/SPEC.md b/SPEC.md index 8b9610f..954b39d 100644 --- a/SPEC.md +++ b/SPEC.md @@ -391,6 +391,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