Skip to content

docs: mandate spec document's own version literals match spec/version.json (§19.5) - #185

Merged
SoundMatt merged 1 commit into
mainfrom
feat/relay-144-version-literal-generation
Aug 21, 2026
Merged

docs: mandate spec document's own version literals match spec/version.json (§19.5)#185
SoundMatt merged 1 commit into
mainfrom
feat/relay-144-version-literal-generation

Conversation

@SoundMatt

Copy link
Copy Markdown
Owner

Summary

Closes #144 (NEW-SPEC-6). Adds §19.5 "This document's own version
literals" and the CI mechanism that enforces it: the spec document's
own text must never drift from spec/version.json the way its
"0.1" example literals once did (fixed by hand in v2.2.3).

Background

Requirement 14 (§17) already obligates an implementation's declared
spec_version to trace back to spec/version.json rather than a
hand-copied literal kept in sync by memory. This repository's own
spec document was never held to the same standard for its own text —
§12.1/§12.2's JSON examples and §13.5's Docker LABEL example drifted
to "0.1", three major versions stale, before being manually fixed in
v2.2.3. That fix closed the immediate symptom but not the underlying
gap: nothing stopped it from recurring.

What's added

  • §19.5: normative MUST that every version literal in this
    document's own text — the "spec_version" examples (§12.1, §12.2,
    §12.4, §17.2, §20.6), the LABEL io.relay.spec-version example
    (§13.5), and §19.4's "Current version" line and Go/C++/Rust snippets
    — matches spec/version.json, with this repository's own CI
    enforcing it.
  • TestSpecVersionMatchesVersionJSON and
    TestSpecDocumentVersionLiteralsMatchVersionJSON
    (version_consistency_test.go): read spec/version.json and
    spec/relay-spec.md via the package's own embedded evidence
    (evidence.go) and fail the build on any drift across all 12
    checked literals (5 named anchors + 7 spec_version example
    occurrences).
  • New REQ-RELAY-100, tagged in evidence.go where the two embedded
    artifacts (spec/version.json, spec/relay-spec.md) originate.
  • Not a relay conform check and no new §17 Requirement.
    relay conform verifies binaries, not the spec document that
    defines it — this is a repository-CI-verified discipline alongside
    Requirements 13/14, with no change to implementation-facing
    obligations
    .

Version

PATCH (v2.7 → v2.7.1) — doc addition, no normative change to existing
conformant implementations. SpecVersion unchanged.

Verification

  • go build/vet/test clean, gofmt -l . clean, golangci-lint run 0
    issues
  • gofusa check 0 errors/PASS, gofusa trace -req-coverage 100
    100%/100% (100/100 requirements traced)
  • Mutation-tested: bumped spec/version.json to a throwaway value and
    confirmed both tests failed with a precise per-literal diff for all
    12 checked literals; separately reworded one anchor's surrounding
    prose and confirmed the test reports "pattern not found" rather than
    silently passing (guards against the anchors going stale
    themselves). Both restored, re-verified green.

….json (§19.5)

Adds §19.5 "This document's own version literals": the spec document's
own text (§12.1/§12.2/§12.4/§17.2/§20.6 spec_version examples, §13.5's
Docker LABEL example, §19.4's Current-version line and Go/C++/Rust
snippets) MUST match spec/version.json, with this repository's own CI
enforcing it — closing the spec's own instance of the exact hand-copied-
literal drift Requirement 14 already asks every implementation to avoid.

Reference implementation: TestSpecVersionMatchesVersionJSON and
TestSpecDocumentVersionLiteralsMatchVersionJSON (version_consistency_test.go)
read spec/version.json and spec/relay-spec.md via the package's own
embedded evidence and fail on any drift across all 12 checked literals
(5 named anchors + 7 spec_version example occurrences). New REQ-RELAY-100,
tagged in evidence.go where the two embedded artifacts originate.

Mutation-tested: bumped spec/version.json to a throwaway value and
confirmed both tests failed with a precise per-literal diff; separately
reworded one anchor's surrounding prose and confirmed the test reports
'pattern not found' rather than silently passing. Both restored, re-verified
green.

Not a relay conform check and no new §17 Requirement — this is a
repository-CI-verified discipline on the spec document itself, alongside
Requirements 13/14, with no change to implementation-facing obligations.
PATCH (v2.7 -> v2.7.1); SpecVersion unchanged.

Closes #144

Signed-off-by: Matt <47545907+SoundMatt@users.noreply.github.com>
@SoundMatt
SoundMatt merged commit 008991f into main Aug 21, 2026
8 checks passed
@SoundMatt
SoundMatt deleted the feat/relay-144-version-literal-generation branch August 21, 2026 13:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[NEW-SPEC-6] Single source of truth for every version token in the spec and every implementation (generate, don't hand-copy)

1 participant