feat: protocol/model retirement process (§3.2), §17 Requirement 17 - #184
Merged
Conversation
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>
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
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
Closes #143 (NEW-SPEC-5). Defines a graceful protocol/model retirement
process for RELAY's
spec/version.json, and a new §17 Requirement 17that
relay conformenforces 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-spacedwindow instead.
What's added
spec/version.jsongains optionalretired[]/deprecated[]arrays, each entry
{name, since, removal, reason}.sinceandremovalare spec MINOR-version strings; per §19.2,removalmustbe at least one MINOR release after
since.declared
spec_versionis at or past aretired[]entry'sremovalversion MUST NOT still list that entry'snameinfeaturesorcommands. Classified as fully black-boxobservable (unlike Requirements 13–16): the check only needs data
relay conformalready fetches over the CLI (declaredspec_version,features/commands), compared againstrelay conform's own embeddedspec/version.json.cmd/relay/conform.go):checkRetiredCapabilities,specVersionAtLeast,parseSpecVersion,loadRetiredCapabilities, wired intovalidateCapabilitiesDoc. NewREQ-RELAY-099.buildManifest'sRequirement 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
capsUnreachablecheck used by Requirements 1,6, and 17 alike. Mutation-tested (reverted, confirmed
TestBuildManifestFailPropagatesToOverallfailed, restored).retired[]/deprecated[]ship empty by design — RELAY's ownpre-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.
checkRetiredCapabilities's core comparison logic.Version
SpecVersion2.6 → 2.7 (MINOR — new §17 requirement, new optionalschema fields, per §19.1).
Verification
go build ./...,go vet ./...— cleango test ./...— all packages passgofmt -l .— cleangolangci-lint run(pinned to CI's version) — 0 issuesgofusa check— 0 errors, PASSgofusa trace -req-coverage 100— 100%, 99/99 requirements tracedrelay conform/relay conform --manifestagainst itself — 17 total requirements, Requirement 17PASS, exit 0