feat: pin the golden vector distribution with a relay-vectors/1 manifest, spec §15.8, Requirement 16 - #181
Merged
Merged
Conversation
…est, spec §15.8, Requirement 16
- New §17 Requirement 16: implementations that embed a local copy of the
canonical spec/vectors/ golden 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 their 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.
- Explicitly declined the originating issue's proposal to extend the
vector set itself with byte-for-byte wire-format vectors: that would
contradict RELAY's own pre-existing scope boundary (§1.1/§17.1,
established in REL-SPEC-2) that wire formats are out of scope for
RELAY's own embedded vectors. Only the manifest/pinning/hashing
mechanism ships here; documented explicitly in §15.8 and the
CHANGELOG rather than silently narrowing scope.
- Reference implementation: spec/vectors/vectors_manifest.json (16
vectors, hashes independently verified via sha256sum),
VectorsManifest()/ParsedVectorsManifest()/VerifyVectorManifest() in
vectors.go. VectorNames() now excludes the manifest file itself from
the vector set it enumerates (it is metadata about the distribution,
not a vector) — required matching fixes in two pre-existing test
files (spec_vectors_test.go, cmd/relay/jsonschema_test.go) that
globbed spec/vectors/*.json directly and would otherwise have tried
to parse the manifest as a golden vector.
- New REQ-RELAY-096. 6 new tests, including a real mutation test
(temporarily corrupted the manifest, confirmed TestVerifyVectorManifestClean
fails, reverted) and a hash-mismatch-detection unit test.
- SpecVersion bumped 2.3 -> 2.4 (MINOR, same precedent as Requirements
13/14/15).
Closes #140.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Matt <47545907+SoundMatt@users.noreply.github.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Matt <47545907+SoundMatt@users.noreply.github.com>
SoundMatt
added a commit
that referenced
this pull request
Aug 21, 2026
…tation/1), spec §20.6 (#183) - New §20.6 defines the shape an implementation MAY publish to make §20.1's CI gates externally verifiable rather than self-asserted: an in-toto Statement whose subject digest is the SHA-256 of the attested binary file, and whose predicate bundles the full §17.2 conformance manifest, the attestation-generating tool's own embedded vectors_version (§15.8 - explicitly NOT observed from the attested binary, which a black-box invocation cannot introspect), and an optional implementation-defined safety_evidence_summary. - Scope decision, documented in the CHANGELOG rather than silently narrowed: this PR ships spec-only. The originating issue also proposed cryptographic signing, publishing alongside a release's container image, surfacing the digest in version --format json, and having relay probe/relay report treat an unverifiable release as non-conformant. None of that ships here - RELAY's own CI does not currently push container images to any registry, and fabricating an unreal 'signature' without real key management would be worse than not signing at all. predicate.signed MUST be false on an unsigned attestation; this section defines shape only. - New embedded schema spec/schemas/relay-conform-attestation.json. - Reference implementation: relay conform --attestation <binary> in cmd/relay/conform.go. New REQ-RELAY-098. - Real bug found and fixed while implementing this: buildManifest's Requirements slice was missing entry 16 (Vector manifest) - PR #181 added the §17 Requirement 16 spec text and verifier-table row but never added the corresponding code entry, so every relay-conform/1 manifest generated since v2.4 silently omitted it despite the spec's own text mandating 'exactly one entry per §17 requirement (1-16, ...)'. Fixed; the two manifest-shape tests that should have caught this (TestBuildManifestSelf, TestRunConformManifestFlag) were also stale at a hardcoded 15 and are corrected alongside it. Mutation-tested: reverted the fix, confirmed both tests failed, restored. - 6 new tests for the attestation feature, including independent cross-checks: subject digest matches a separately-computed sha256 of the binary file, vectors_version matches the tool's own parsed vectors_manifest.json, and schema validation against the new embedded schema. - SpecVersion bumped 2.5 -> 2.6 (MINOR, new optional format + CLI flag). Closes #142. Signed-off-by: Matt <47545907+SoundMatt@users.noreply.github.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements issue #140 (NEW-SPEC-2): pins the canonical
spec/vectors/golden vector distribution with a machine-checkable, hash-verified manifest — same pattern as #180's conformance manifest, applied to vector distribution instead of §17 requirement status.Scope decision (important)
The originating issue's proposal had two parts:
What's added
vectors_versionit targets.relay-vectors/1manifest shape:kind,manifest_version,vectors_version(bound tospec/version.json),vectors[]({name, sha256}pairs, one per file underspec/vectors/includingspec/vectors/errors/).spec/schemas/vectors-manifest.json.spec/vectors/vectors_manifest.json(16 entries — all hashes independently computed viashasum -a 256and cross-checked againstVerifyVectorManifest()'s own computation), plusVectorsManifest(),ParsedVectorsManifest(), andVerifyVectorManifest()invectors.go.VectorNames()now excludes the manifest file itself from the vector set it enumerates — it's metadata about the distribution, not a vector. This required matching fixes in two pre-existing tests (spec_vectors_test.go,cmd/relay/jsonschema_test.go) that globbedspec/vectors/*.jsondirectly and would otherwise have tried to parse the manifest as arelay.Messagefixture and failed.REQ-RELAY-096in.fusa-reqs.json.Version
SpecVersionbumped2.3→2.4(MINOR), same precedent as Requirements 13/14/15.Verification
VectorNames(), manifest JSON validity + shape, a cleanVerifyVectorManifest()run against the real committed manifest, and a hash-mismatch-detection unit test.spec/vectors/vectors_manifest.json, confirmedTestVerifyVectorManifestCleanfails with the exact expected finding, then reverted and confirmed clean again.go build ./... && go vet ./... && go test ./...— all packages green.gofmt -l .— clean.gofusa check(pinned v0.48.0, matching CI): 0 errors.gofusa trace -req-coverage 100: 100% (96/96 requirements traced).Closes #140.