Repository navigation
[NEW-SPEC-6] Single source of truth for every version token in the spec and every implementation (generate, don't hand-copy) #144
Description
Problem. THEME-A documents 13 of 18 ports carrying a hand-copied, now-stale SpecVersion literal.
The spec document exhibits the identical failure mode internally: §12.1/§12.2's own JSON examples still
print "spec_version": "0.1" (confirmed present at current HEAD, relay-spec.md:1124 and :1143) in a
document whose title and spec/version.json both say v2.0, and §13.5's Docker LABEL example
similarly still shows io.relay.spec-version="0.1" (relay-spec.md:1239, though the surrounding prose
does note it's illustrative).
Proposal. Modify §19.4 and §13.5, and add a new §19.5: the Go/C++/Rust SpecVersion constants,
the Docker io.relay.spec-version LABEL, and every version literal appearing in the spec document's
own examples (§12.1/§12.2) MUST be generated from spec/version.json rather than hand-written. CI (in
both the spec repo and every port) MUST fail if any emitted constant, label, or example literal
diverges from version.json. This complements REL-SPEC-6 (filed separately in this batch, which binds
a port's declared version to its RELAY dependency) by additionally mandating the generator mechanism
and applying it to the spec text itself, closing the spec's own instance of the drift it asks every
port to avoid.
Filed from the 2026-07-29 ecosystem audit register; independently re-verified against current HEAD before filing.
Activity
SoundMatt commentedon Aug 21, 2026
Implemented and merged in #185 (v2.7 → v2.7.1, PATCH — no normative change to implementations).
What shipped
"spec_version"examples (§12.1, §12.2, §12.4, §17.2, §20.6), theLABEL io.relay.spec-versionexample (§13.5), and §19.4's "Current version" line and Go/C++/Rust snippets — matchesspec/version.json, enforced by this repository's own CI.TestSpecVersionMatchesVersionJSONandTestSpecDocumentVersionLiteralsMatchVersionJSON(version_consistency_test.go) readspec/version.jsonandspec/relay-spec.mdvia the package's own embedded evidence and fail on any of 12 checked literals drifting (5 named anchors + 7spec_versionexample occurrences). NewREQ-RELAY-100, tagged inevidence.go.relay conformcheck and no new §17 Requirement —relay conformverifies binaries, not the spec document that defines it. This sits alongside Requirements 13/14 as a repository-CI-verified discipline, so it correctly ships as PATCH: no change to implementation-facing obligations.Note on the issue's "Problem" text
The specific stale
"0.1"example literals the issue opened with were already fixed by hand in v2.2.3 (closing REL-SPEC-11), independently confirmed at HEAD before starting this work. What remained — and what this PR actually delivers — is the generator/CI-enforcement mechanism itself, so that class of drift can't silently recur.Verification
Local, pre-merge:
go build/vet/testclean,gofmt -l .clean,golangci-lint run0 issues,gofusa check0 errors/PASS,gofusa trace -req-coverage 100100%/100% (100/100 requirements traced).Post-merge, independently re-verified from a fresh clone at
008991f: build/vet/gofmt/test clean,gofusa check0 errors/PASS,gofusa trace100%/100%, and the drift check re-confirmed live on the fresh clone — mutatedspec/version.jsonto a throwaway value, confirmed both tests failed listing the exact stale literals, restored, re-verified green.CI green on the
mainmerge commit (DCO, Lint, Docker build, CodeQL, Security, Test, Self-conformance, go-FuSa full safety lifecycle — all pass).