[NEW-SPEC-2] Normative golden-vector distribution, pinning, and hashing for wire-format conformance vectors #140

Activity

1. SoundMatt

   added

   sev:high

   spec-compliance

   on Jul 30, 2026
2. SoundMatt

   closed this as completedin #181on Aug 21, 2026
3. SoundMatt commented on Aug 21, 2026

   

   SoundMatt

   on Aug 21, 2026

   OwnerAuthor

   More actions

   Implemented and merged in #181 (squash commit 05a5300).

   Scope decision (important)

   The originating issue's proposal had two parts:

   1. Pin/hash/version the vector distribution — implemented.
   2. Extend the vector set itself with byte-for-byte wire-format vectors (MQTT varint boundary, LIN diagnostic-checksum selection, etc.) — explicitly declined. This contradicts RELAY's own pre-existing scope boundary at §1.1/§17.1 (established by REL-SPEC-2, already merged): "RELAY does not define wire formats... so RELAY cannot ship byte-for-byte wire vectors itself without exceeding that boundary." §15.8's new text states this explicitly. Only part 1 shipped.

   What was implemented

   • New §17 Requirement 16 — Vector manifest. A conformant implementation that embeds a local copy of the canonical vectors MUST embed the exact pinned set and MUST have a CI step that fails on any SHA-256 divergence from the published manifest for its targeted vectors_version.
   • New §15.8 defines the relay-vectors/1 manifest shape (kind, manifest_version, vectors_version, vectors[] of {name, sha256}).
   • New embedded schema spec/schemas/vectors-manifest.json.
   • New §20.1 CI gate for manifest regeneration/diffing.
   • Reference implementation: spec/vectors/vectors_manifest.json (16 entries, all hashes independently computed via shasum -a 256), plus VectorsManifest()/ParsedVectorsManifest()/VerifyVectorManifest() in vectors.go.
   • VectorNames() now excludes the manifest file itself — it's metadata about the distribution, not a vector. Required matching fixes in two pre-existing tests (spec_vectors_test.go, cmd/relay/jsonschema_test.go) that globbed spec/vectors/*.json directly.
   • New REQ-RELAY-096.
   • SpecVersion bumped 2.3 → 2.4 (MINOR).

   Verification (double-checked, before and after merge)

   • go build ./... && go vet ./... && go test ./... — clean, both pre-merge and from a fresh post-merge clone of main at 05a5300.
   • gofmt -l . and golangci-lint run (latest, matching CI's pin) — clean (caught and fixed one unused finding on the first push — a leftover dead helper function).
   • gofusa check (pinned v0.48.0): 0 errors. gofusa trace -req-coverage 100: 100% (96/96).
   • Real mutation test: temporarily corrupted one hash in the committed manifest, confirmed TestVerifyVectorManifestClean failed with the exact expected finding, reverted, confirmed clean again.
   • Manually ran the reference VerifyVectorManifest() against the post-merge clone's embedded vectors: 16 vectors (manifest correctly excluded), vectors_version: "2.4", zero findings.
   • All 8 CI checks green on PR feat: pin the golden vector distribution with a relay-vectors/1 manifest, spec §15.8, Requirement 16 #181, and the main CI run for merge commit 05a5300 independently confirmed green (Docker build, Lint, Security, Test, go-FuSa full safety lifecycle, Self-conformance all success).

   Closing.