Skip to content

feat: tighten §17 Requirements 1 and 6 from WARN to FAIL, add multi_protocol capabilities field - #182

Merged
SoundMatt merged 1 commit into
mainfrom
feat/relay-141-multi-protocol-capabilities
Aug 21, 2026
Merged

feat: tighten §17 Requirements 1 and 6 from WARN to FAIL, add multi_protocol capabilities field#182
SoundMatt merged 1 commit into
mainfrom
feat/relay-141-multi-protocol-capabilities

Conversation

@SoundMatt

Copy link
Copy Markdown
Owner

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:false findings from WARN to FAIL unconditionally. Literally implementing that would have broken RELAY's own reference CLI's passing self-conformance CI job — cmd/relay is 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 to false. 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 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-strict relay conform).

Scope decision (documented in CHANGELOG)

The issue also proposed verifying every declared commands string is invocable and "exercising" every declared features string 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 states features are 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

  • New optional multi_protocol field, spec/schemas/cli-capabilities.json + §12.2 prose/example.
  • §17 Requirements 1 and 6 text tightened; black-box narrative and verifier table rows upgraded from "Partial" to "Full".
  • validateCapabilitiesDoc in cmd/relay/conform.go: gated FAIL logic for null protocol and adapt: false, both exempted when multi_protocol: true.
  • cmd/relay's own capabilities output now declares "multi_protocol": true.
  • New REQ-RELAY-097.
  • Fixed two stale doc references found in passing (Quickstart §step 9 said "three CI gates" / "partially checks Requirements 1, 6, and 12" — stale since the last two PRs added CI gates 4/5 and this PR promotes 1/6 to full coverage).
  • SpecVersion bumped 2.42.5 (MINOR, new optional field).

Verification

  • 5 new/rewritten tests: adapt-false FAIL (single-protocol), null-protocol FAIL (single-protocol), and the multi_protocol: true exemption for both — plus the two pre-existing tests updated to match.
  • Real mutation test: temporarily reverted the FAIL tightening back to WARN, confirmed the new FAIL-asserting tests correctly failed, then restored and confirmed green again.
  • Manually verified 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.
  • Manually verified relay conform --manifest reports Requirements 1 and 6 as PASS (not FAIL) for RELAY's own binary.
  • go build ./... && go vet ./... && go test ./... — all packages green.
  • gofmt -l . and golangci-lint run (latest) — clean.
  • gofusa check (pinned v0.48.0): 0 errors. gofusa trace -req-coverage 100: 100% (97/97).

Closes #141.

…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>
@SoundMatt
SoundMatt merged commit 54416fa into main Aug 21, 2026
8 checks passed
@SoundMatt
SoundMatt deleted the feat/relay-141-multi-protocol-capabilities branch August 21, 2026 12:40
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-3] Runtime capabilities-to-binary cross-check; tighten missing-protocol / adapt:false from WARN to FAIL

1 participant