Skip to content

feat: protocol/model retirement process (§3.2), §17 Requirement 17 - #184

Merged
SoundMatt merged 1 commit into
mainfrom
feat/relay-143-retirement-process
Aug 21, 2026
Merged

feat: protocol/model retirement process (§3.2), §17 Requirement 17#184
SoundMatt merged 1 commit into
mainfrom
feat/relay-143-retirement-process

Conversation

@SoundMatt

Copy link
Copy Markdown
Owner

Summary

Closes #143 (NEW-SPEC-5). Defines a graceful protocol/model retirement
process for RELAY's spec/version.json, and a new §17 Requirement 17
that relay conform enforces against it.

RELAY's existing deprecation policy (§19.2) covers removing a single
MUST requirement, but has nothing to say about retiring a whole
canonical model or protocol the way §15.5's RCP types were replaced
for TC18 conformance — that was an instant, compat-shim-free MAJOR
break. This gives future retirements a since/removal-spaced
window instead.

What's added

  • §3.2 "Retiring a protocol or model" — new spec subsection.
    spec/version.json gains optional retired[]/deprecated[]
    arrays, each entry {name, since, removal, reason}. since and
    removal are spec MINOR-version strings; per §19.2, removal must
    be at least one MINOR release after since.
  • §17 Requirement 17 — a capabilities document (§12.2) whose
    declared spec_version is at or past a retired[] entry's
    removal version MUST NOT still list that entry's name in
    features or commands. Classified as fully black-box
    observable (unlike Requirements 13–16): the check only needs data
    relay conform already fetches over the CLI (declared
    spec_version, features/commands), compared against relay conform's own embedded spec/version.json.
  • Reference implementation (cmd/relay/conform.go):
    checkRetiredCapabilities, specVersionAtLeast,
    parseSpecVersion, loadRetiredCapabilities, wired into
    validateCapabilitiesDoc. New REQ-RELAY-099.
  • Bug fix found while wiring this in: buildManifest's
    Requirement 1 and 6 statuses didn't account for the capabilities
    command failing to run/parse at all (§17.7) as a superset failure
    once findings started being filtered by precise section citation.
    Introduced a shared capsUnreachable check used by Requirements 1,
    6, and 17 alike. Mutation-tested (reverted, confirmed
    TestBuildManifestFailPropagatesToOverall failed, restored).
  • retired[]/deprecated[] ship empty by design — RELAY's own
    pre-TC18 RCP placeholder-model replacement (§15.5, v2.0) predates
    §3.2 and was an instant breaking change with no deprecation window,
    not the kind of graceful retirement this mechanism tracks.
    Force-fitting it in would misrepresent that history.
  • 8 new tests, including a real mutation test on
    checkRetiredCapabilities's core comparison logic.

Version

SpecVersion 2.6 → 2.7 (MINOR — new §17 requirement, new optional
schema fields, per §19.1).

Verification

  • go build ./..., go vet ./... — clean
  • go test ./... — all packages pass
  • gofmt -l . — clean
  • golangci-lint run (pinned to CI's version) — 0 issues
  • gofusa check — 0 errors, PASS
  • gofusa trace -req-coverage 100 — 100%, 99/99 requirements traced
  • Manual end-to-end: built binary, ran relay conform/relay conform --manifest against itself — 17 total requirements, Requirement 17
    PASS, exit 0

Adds a retired[]/deprecated[] array pair to spec/version.json for
gracefully retiring a protocol or model, and a new §17 Requirement 17:
relay conform MUST FAIL a capabilities doc whose declared spec_version
is at or past a retired entry's removal version but still names that
capability in features/commands.

Unlike Requirements 13-16, this is fully black-box observable: both
inputs (spec_version, capabilities) are already fetched by relay
conform over the CLI, compared against relay conform's own embedded
spec/version.json.

Also fixes a real pre-existing bug found while wiring this in:
buildManifest's Requirement 1 and 6 statuses didn't account for the
capabilities command failing to run at all (§17.7) as a superset
failure once findings started being filtered by precise citation.
Introduced a shared capsUnreachable check, mutation-tested.

retired[]/deprecated[] start empty by design — RELAY's own historical
RCP placeholder-model retirement (§15.5, v2.0) predates §3.2 and was
an instant breaking change with no deprecation window, not the kind
of graceful since/removal-spaced retirement this mechanism tracks.

SpecVersion 2.6 -> 2.7 (MINOR). New REQ-RELAY-099. 8 new tests.

Closes #143

Signed-off-by: Matt <47545907+SoundMatt@users.noreply.github.com>
@SoundMatt
SoundMatt merged commit 91cb6be into main Aug 21, 2026
8 checks passed
@SoundMatt
SoundMatt deleted the feat/relay-143-retirement-process branch August 21, 2026 13:15
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-5] Define a formal protocol/model retirement process (spec/version.json retired[]/deprecated[] arrays)

1 participant