Skip to content

Commit 7bb297e

Browse files
docs(spec): add golden test corpus reference (§7.5) (#4)
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
1 parent dc02ebf commit 7bb297e

1 file changed

Lines changed: 16 additions & 0 deletions

File tree

SPEC.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -408,6 +408,22 @@ Byte 8-19: [12-byte nonce]
408408
Byte 20+: [ciphertext + 16-byte GCM tag]
409409
```
410410

411+
### 7.5 Golden Test Corpus
412+
413+
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.
414+
415+
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.
416+
417+
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.
418+
419+
**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:
420+
421+
```
422+
go run -tags=wirecorpus ./cmd/wire-gen
423+
```
424+
425+
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.
426+
411427
---
412428

413429
## 8. Version Negotiation

0 commit comments

Comments
 (0)