feat: tighten §17 Requirements 1 and 6 from WARN to FAIL, add multi_protocol capabilities field - #182
Merged
Conversation
…rotocol capabilities field - New optional capabilities field `multi_protocol` (spec §12.2), defaulting to false when absent. A tool that self-declares multi_protocol:true legitimately reports a null protocol/protocol_int and adapt:false — §10.3 scopes the Adapt() contract to protocol packages, so a multi-protocol aggregator (like RELAY's own reference CLI) has no single protocol to declare or per-protocol adapter to export. - §17 Requirements 1 and 6 tightened from WARN to FAIL: a null protocol/protocol_int, or adapt:false, on a capabilities document that does not declare multi_protocol:true is now a conformance FAIL, closing a real audit-flagged gap (THEME-B) that let capabilities silently drift from the shipped binary undetected by non-strict relay conform. Both requirements move from Partial to Full black-box coverage. - Design note: the naive literal implementation (blindly tightening both WARN cases) would have broken RELAY's own reference CLI's passing self-conformance CI job, which is deliberately, legitimately multi-protocol and non-adapting (confirmed via the CI workflow's own explanatory comment). multi_protocol exists specifically so relay conform's black-box CLI can distinguish that legitimate case from a genuine single-protocol implementation bug, which it previously could not do at all. - Scope decision, documented in the CHANGELOG: explicitly declined the originating issue's proposal to verify every declared `commands` string is invocable and to "exercise" every declared `features` string — neither has an existing spec-grounded signal to build on (no "unknown command" exit code distinct from generic "invalid arguments"; §12.2 already states features are compiled-in and explicitly not runtime-probed). Deferred to a dedicated follow-up rather than inventing an unproven convention under this issue's scope. - Fixed two stale doc references found in passing: the Quickstart walkthrough (§step 9) still said "three CI gates" / "partially checks Requirements 1, 6, and 12" after the last two PRs added gates 4 and 5 and this PR promotes Requirements 1 and 6 to full coverage. - Reference implementation: cmd/relay's own capabilities output now declares "multi_protocol": true; validateCapabilitiesDoc implements the gated FAIL logic for both fields. New REQ-RELAY-097. 5 new/rewritten tests, including a real mutation test (reverted the tightening, confirmed the new tests fail, restored). - SpecVersion bumped 2.4 -> 2.5 (MINOR, new optional field). Closes #141. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> 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
Implements a scoped-down version of issue #141 (NEW-SPEC-3), per explicit user decision after a design conflict was found: design a real fix first rather than implementing the WARN→FAIL tightening naively.
The conflict, and how it's resolved
The issue proposed turning
relay conform's missing-protocol/adapt:falsefindings from WARN to FAIL unconditionally. Literally implementing that would have broken RELAY's own reference CLI's passing self-conformance CI job —cmd/relayis deliberately, legitimately multi-protocol (protocol: null) and non-adapting (adapt: false), as CI's own workflow comment already documents.relay conform's black-box CLI had no way to distinguish that legitimate case from a genuine single-protocol implementation bug.Fix: new optional capabilities field
multi_protocol(spec §12.2), defaulting tofalse. A tool that self-declaresmulti_protocol: truelegitimately reports a nullprotocol/protocol_intandadapt: false— §10.3 scopes theAdapt()contract to protocol packages, so a multi-protocol aggregator has no single protocol to declare or per-protocol adapter to export. With that carve-out in place, §17 Requirements 1 and 6 tighten cleanly from WARN to FAIL for everyone else, closing a real audit-flagged gap (THEME-B: capabilities silently drifting from the shipped binary, undetected by non-strictrelay conform).Scope decision (documented in CHANGELOG)
The issue also proposed verifying every declared
commandsstring is invocable and "exercising" every declaredfeaturesstring with a CLI probe. Both explicitly declined this PR: there's no existing, spec-grounded signal distinct from the generic "invalid arguments" exit code (§11.3) to detect an unrecognized command across four languages' implementations, and §12.2 already statesfeaturesare compiled-in and explicitly not runtime-probed. Inventing either now would mean fabricating an unproven convention rather than tightening an existing one — deferred to a dedicated follow-up.What's added
multi_protocolfield,spec/schemas/cli-capabilities.json+ §12.2 prose/example.validateCapabilitiesDocincmd/relay/conform.go: gated FAIL logic for nullprotocolandadapt: false, both exempted whenmulti_protocol: true.cmd/relay's owncapabilitiesoutput now declares"multi_protocol": true.REQ-RELAY-097.SpecVersionbumped2.4→2.5(MINOR, new optional field).Verification
multi_protocol: trueexemption for both — plus the two pre-existing tests updated to match.relay conform ./relay(RELAY's own binary) still exits 0 with only the pre-existing softer version-doc WARN — no new FAIL, confirming the design doesn't break RELAY's own passing CI.relay conform --manifestreports Requirements 1 and 6 asPASS(notFAIL) for RELAY's own binary.go build ./... && go vet ./... && go test ./...— all packages green.gofmt -l .andgolangci-lint run(latest) — clean.gofusa check(pinned v0.48.0): 0 errors.gofusa trace -req-coverage 100: 100% (97/97).Closes #141.