Commit graph

2 commits

Author SHA1 Message Date
Julian Knutsen
f629867311 fix(httpapi): rename issues.listSort to issues.list.sort, harden token rule
Opus review of 12c5144ca (HIGH-1, MEDIUM-5):

- Rename the capability token issues.listSort -> issues.list.sort to match
  bd-enterprise's client (httpstore/wire/handshake.go:121, DESIGN.txt S4e),
  and widen capabilityToken to accept an optional third segment.
- untokenedParameters() now requires the extracted token to be one
  Capabilities() actually serves, not just backtick-shaped text. This
  catches real false positives that existed in the spec already
  (workapi.DefaultReadyLimit, status.custom) which only shape-matched the
  old regex; they're added to the pretoken baseline as genuinely
  pre-existing untokened parameters.
- Extend the rule to request body members (new
  testdata/pretoken_request_body_members.json baseline) and exempt
  brand-new operations via a frozen testdata/pretoken_operations.json
  snapshot.
- Add TestPretokenBaselinesNeverGrow pinning all three baseline sizes so
  a future change can't hand-add an exemption instead of a token.
- Update spec prose for the widened rule scope.

go test ./internal/httpapi/... and the reviewer's pmut.py all pass as
expected: plain/bogus modes go RED, reuse (real-but-unrelated token) stays
green, matching the review's literal ask ("a token must be one advertised
by Capabilities()").

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-05 04:54:47 +00:00
Julian Knutsen
ea5a2b702d feat(httpapi): wire-shape signal — wire_revision, floor header, golden digest, param tokens
S0 of the HTTP role-parity program: give a client a single place to learn
whether this build's wire shape has moved under it, and give CI a gate that
catches an undocumented move.

- GET /v0/beads/context reports wire_revision (bumps only on a non-additive
  response-shape change) and min_client_wire_revision. An optional
  Bd-Wire-Revision request header lets a client declare the revision it was
  built for; checkWireRevision refuses a declared revision below the floor
  with 400 invalid_argument/reason=wire_revision_unsupported and a
  min_wire_revision field, on every route but /healthz (wireRevisionExempt) —
  including the identity handshake, where catching the mismatch is cheapest.
  Absent header is today's behavior; malformed value is invalid_value, never
  wire_revision_unsupported. The floor lives in Server.minClientWireRevision
  (defaulting to the MinClientWireRevision constant) so a test can raise it.
- internal/httpapi/wireshape: a golden digest over every response's every
  content-type schema (including application/problem+json) across the whole
  spec, keyed by schema+member. TestWireShapeDigest fails closed when a
  member's JSON name or type changes without wire_revision bumping to match;
  regenerate with `go run ./internal/httpapi/wireshape/cmd/gendigest`.
- GET /v0/beads/issues' `sort` parameter now carries the issues.listSort
  capability token, the same convention `capabilities` entries use.
  TestNewParameterOnExistingOperationHasABehaviorToken requires every new
  parameter on an existing operation to carry one, checked against a
  write-once grandfather baseline (testdata/pretoken_parameters.json) of
  parameters that predate the rule; TestUntokenedParameterRuleFires proves
  the checker itself against a synthetic fixture.
- Docs: engdocs/design/bd-serve-v0.md gets a "The wire-shape signal" section;
  CHANGELOG.md gets an Added entry.

Live-mutated and reverted three RED demonstrations during development:
retyping api_version in the spec failed TestWireShapeDigest; short-circuiting
checkWireRevision's floor comparison failed
TestWireRevisionBelowFloorRefusesEveryEnforcedRoute; adding an untokened
query parameter to listIssues failed
TestNewParameterOnExistingOperationHasABehaviorToken. All three now pass
against the unmutated tree.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-05 04:54:46 +00:00