beads/engdocs/design/bd-serve-v0.md
Julian Knutsen 5439be97ba
feat(httpapi): wire-shape signal — wire_revision, client floor, golden shape digest, param tokens (#7182)
* 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>

* 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>

* fix(wireshape): close four digest-coverage gaps, add gendigest write guard

Opus review of 12c5144ca (HIGH-2, MEDIUM-4). The digest only tracked
Type/Format/Enum/Required on direct properties, missing:

- nullable: true (never read at all)
- array item shape (Issue.labels items string->integer was invisible;
  only object-shaped items got recursed into)
- additionalProperties value shape (IssueCount.groups)
- request bodies entirely (Compute() only walked responses, so
  DeleteIssuesRequest.expected_version string->integer, the other half
  of #6053, was invisible)

Also added defensive oneOf flattening alongside the existing allOf merge
(dormant today -- grep confirms this spec uses oneOf nowhere -- but no
longer silently invisible if that changes).

Extracted the golden-vs-computed comparison into wireshape.Compare(),
shared by TestWireShapeDigest and the new wireshape.SafeToWrite(), which
gendigest now calls before writing: it refuses to overwrite golden.json
with changed/removed entries unless the candidate's wire_revision is
strictly greater than the existing golden's. Pure additions always write.
TestSafeToWrite exercises both guard directions.

golden.json is regenerated. This single regen is a one-time exception to
the new guard, done by writing the digest directly rather than through
gendigest: confirmed via a throwaway diff (not checked in) that every one
of the 57 "changed" entries differs only in the NEW fields the wider walk
now populates (ItemType/ItemFormat/Nullable/AdditionalProps*) -- every
pre-existing Type/Format/Required/Enum value is byte-identical. Nothing on
the wire changed; the measurement got more precise. Bumping
CurrentWireRevision for this would have written a false "the protocol
changed here" entry into the revision history table. Going forward, any
REAL change the guard now reports uses the normal bump-then-regenerate
path, same as before.

Verified against the reviewer's mut.py: nested_type, nullable,
nullable_issue, array_items, addlprops, request_body and format all go RED
on TestWireShapeDigest, each reverted after confirming.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(httpapi): make bd_version wire_revision inference advisory

Opus review of 12c5144ca (HIGH-3). The spec told a client inferring
wire_revision from bd_version to use the release cutoff >= 1.3.0, and said
nothing about what happens when that inference is wrong -- which it
demonstrably is for real builds already in the field:

- main builds up to commit b3ef65c85 report bd_version 1.2.2 (below any
  1.3.0 cutoff) while already sending the string-typed revision/
  expected_version shape (#6053).
- 1.3.0-rc.N pre-release builds sort BELOW the release cutoff 1.3.0 under
  plain string comparison despite already carrying the string shape.
- The bd-enterprise compatibility line at d3ab32773462 reports bd_version
  1.1.0 while also sending strings.

Moved the cutoff to >= 1.3.0-rc.1 (compared as semver-with-prerelease,
which at least captures the rc builds), documented both named exceptions
inline, and made the whole inference explicitly ADVISORY: a client must
accept revision/expected_version as either a string or a number whenever
wire_revision is absent (or probe directly) rather than let the inferred
value choose a decoder, and must never refuse solely because the inferred
revision is 0. Mirrored into engdocs/design/bd-serve-v0.md.

This is spec/doc prose only -- there is no server-side inference code to
change, since this server always sends wire_revision directly; the
inference is guidance for clients reading a pre-signal server's response
(this server, past builds, or an unrelated implementation).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(httpapi): LOW-7/8/9/10 review follow-ups for wire-revision signal

LOW-7: WireRevisionUnsupported now also sets Problem.wire_revision (this
server's CurrentWireRevision) and Problem.bd_version on the
wire_revision_unsupported refusal, alongside the existing
min_wire_revision, so a client logging the refusal has this server's
full self-description without a second /v0/beads/context call.

LOW-8: gazelle + make bazel-sync add the BUILD.bazel entries the prior
commits were missing: wire_revision.go/wire_revision_test.go in
internal/httpapi's srcs, new BUILD.bazel files for wireshape and
wireshape/cmd/gendigest, and a testdata glob on httpapi's go_test so
the pretoken_*.json baselines are visible under `bazel test`. Verified
with `bazel build //internal/httpapi/...` and
`bazel test //internal/httpapi/... --test_env=BEADS_TEST_SKIP=dolt`
(both green) and `python3 tools/bazel/go_srcs.py --check` (clean).

LOW-9: narrowed CHANGELOG.md and engdocs/design/bd-serve-v0.md to
describe the digest's actual final coverage (format/enum/required/
nullable, array items, additionalProperties, request bodies, $ref/
allOf/oneOf recursion, the SafeToWrite revision-bump guard) and the
token rule's actual final shape (three pinned baselines, request-body
members, Capabilities()-membership validation, new-operation
exemption) instead of the original, narrower claims.

LOW-10: Bd-Wire-Revision now parses via a strict decimal-only
parseStrictNonNegativeInt (no leading '+', no leading zero except a
bare "0") instead of strconv.Atoi alone, so two different header
bytes can no longer name the same revision. New malformed-header test
cases: "+1", "01", "007".

Regenerated apigen/types.gen.go (make api-gen) for the new Problem
fields and wireshape/testdata/golden.json (go run
.../wireshape/cmd/gendigest) for the two new additive Problem members;
the latter wrote cleanly through SafeToWrite itself, since both are
pure additions.

go test ./... and bazel test //internal/httpapi/... both green.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(httpapi): re-review LOW follow-ups — retirement test, gendigest -init, docs

1. TestRetiredRevisionsStayBelowTheFloor pins the PRESENCE guarantee the
   wire_revision property doc relies on: CurrentWireRevision >= 2 (so 0
   and 1 stay permanently retired) and MinClientWireRevision <=
   CurrentWireRevision (so this build's own floor never refuses every
   request against itself).

2. gendigest now refuses to create a golden.json that does not exist yet
   unless run with -init. Previously a missing file (moved testdata,
   wrong path, accidental delete) was indistinguishable from a real first
   run and silently wrote a fresh golden with no revision history checked
   against anything. writeGolden() is extracted out of main() so this is
   covered directly: TestWriteGoldenRequiresInitWhenMissing,
   TestWriteGoldenInitCreatesWhenMissing,
   TestWriteGoldenIgnoresInitWhenGoldenExists (the existing-golden path is
   still governed only by SafeToWrite, -init or not).

3. Narrowed the two remaining stale claims that still described the
   digest's original, narrower coverage: the wire_revision property's
   prose in openapi.v0.yaml (regenerated into apigen/types.gen.go via
   make api-gen) and wireshape/doc.go now both list nullable, array item
   shape, additionalProperties value shape, request bodies, and
   $ref/allOf/oneOf recursion, plus the new -init guard.

go test ./internal/httpapi/... and make api-check both green;
bazel test //internal/httpapi/... (httpapi, wireshape, and the new
gendigest test target) green; python3 tools/bazel/go_srcs.py --check
clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* feat(wireshape): cover operation parameters in the wire-shape digest

The digest previously walked only response and request-body schemas, so a
type, enum, required, or removal change on one of the spec's 138 operation
parameters (123 query, 14 path, 1 header) passed the gate silently — the
open item from PR review on #7182.

Each parameter is now recorded as its own Entry, keyed by
"param:"+operationId / location+":"+name (operation-scoped, not
schema-scoped, since two operations' same-named parameter are independent
wire contracts), capturing type, array item shape, enum, required, style,
explode and default. Adding a parameter stays additive; removing,
retyping, narrowing its enum, or changing required/style/explode/default
now trips SafeToWrite exactly like a response or request-body change.

Verified against the live spec: retyping listIssues' `limit` query
parameter from integer to string now fails TestWireShapeDigest (confirmed
red, then reverted — not part of this commit). golden.json regenerated via
gendigest; the new parameter entries are a pure addition, no wire_revision
bump needed. Added TestParameterMutationsAreCaught (remove/retype/narrow-
enum against real golden entries) and updated wireshape's doc.go, the
`wire_revision` spec prose, and the CHANGELOG to describe the new
coverage.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(wireshape): review fixes — stale-golden and lowered-revision arms, effective param serialization, digest boundary

Maintainer fixup from the adopt-pr review loop (iterations 1 and 2), on
top of e17ba924f.

- goldenDrift (A, I): TestWireShapeDigest's comparison moves into a
  goldenDrift helper. An addition alongside a moved wire_revision no
  longer passes with a stale golden: it asks for a regenerate, as a
  changed or removed entry after a bump already did. Every message now
  names response/request-body members AND parameters, and TestGoldenDrift
  pins each arm. This takes only the test half of the stranded fixup
  (adopt-pr/bd-47kdge/stranded-fixup-528cd6095); its doc half, which says
  parameters are outside the digest, is false since e17ba924f and is not
  replayed (J).
- Lowered wire_revision (D): a CurrentWireRevision LOWER than the
  golden's is a wrong constant, not a stale golden, so goldenDrift says to
  restore it instead of regenerating, and SafeToWrite (so gendigest)
  refuses any write at a lower revision, whatever the entries.
- Effective style/explode (B): walkParam records style and explode with
  OpenAPI 3.0's defaults filled in (form for query/cookie, simple for
  path/header; explode defaults to style == form). Adding `explode: false`
  to a query array that relied on form's implicit explode is now a
  changed entry, while spelling out a default changes nothing.
  testdata/golden.json is regenerated with -init: 111 parameter entries
  change only in style/explode (96 to form/true, 15 to simple), 828
  entries before and after, wire_revision stays 2. The golden is new in
  this PR and unreleased, so this needs no bump.
- TestWalkParam (H): a package-internal table test
  (wireshape_internal_test.go) pins every field walkParam extracts,
  through a computeFrom(document, revision) seam that Compute now wraps:
  per-location defaults, $ref'd parameters and items, format, nullable and
  default, content parameters, and the nil returns.
  TestEffectiveSerializationIsCompared pins B end to end through Compare
  and SafeToWrite. BUILD.bazel embeds the library in the go_test, which is
  gazelle's own output.
- Required inputs and the digest boundary (C, E, F; docs only): all five
  prose surfaces (openapi.v0.yaml's wire_revision description and the
  regenerated apigen/types.gen.go, wireshape/doc.go, CHANGELOG.md,
  engdocs/design/bd-serve-v0.md) now say that a new REQUIRED request
  input is recorded as an ordinary addition and needs its own review,
  that value constraints and member-level composition are outside the
  digest, and that object and content parameters are recorded only as
  their container. bd-serve-v0.md also gains the parameter coverage it
  was missing.
- G: a brand-new operation is permanently exempt from the
  capability-token rule; its own review decides its capability story.
- Iteration 2 (nit): walkParam's comment now says that the location
  default it records as a `content` parameter's style and explode is a
  placeholder, since OpenAPI 3.0 applies style and explode only to a
  parameter described by `schema`. All 138 operation parameters in the
  spec use `schema`, so the golden does not change.

Validated: go test ./internal/httpapi/... (gms_pure_go), make api-check,
go vet for linux/windows/darwin, gofmt, git diff --check, gazelle on the
package (no drift), make bazel-sync-check, and bazel test
//internal/httpapi/wireshape/... in the local processwrapper sandbox
(2 of 2 pass). Overlay mutation probes: dropping the added-after-bump
arm, the lowered-revision arm, SafeToWrite's lowered check, or the
effective-default fill each turns the new tests red.
Iteration 2 changes only that comment; go test
./internal/httpapi/wireshape/... (gms_pure_go), go vet, gofmt and git
diff --check pass again.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-04 22:29:12 -07:00

39 KiB

bd serve — the v0 HTTP surface

bd serve answers the same work surface the CLI answers, over HTTP, for automation clients and orchestrators that would otherwise fork a bd subprocess per call. It exists because the subprocess-per-call shape has two costs a long-running client cannot pay down: process startup on every read, and a contract made of stdout text that clients end up parsing.

This page describes the contract and the decisions behind it. For running one, see SERVE_RUNBOOK.md.

Source of truth, in order:

  • internal/httpapi/spec/openapi.v0.yaml — the wire contract. Types are generated from it (make api-gen); make api-check fails a change that edits one without the other.
  • internal/httpapi/doc.go — what is live in this build and how the anti-drift properties are enforced.
  • issueops/reader.go — the read role both front doors reach.

Nothing here may contradict those three. Where this page summarizes, it says so.

The surface

Everything is under /v0 except liveness. The operation list is not reproduced here, on purpose: internal/httpapi/routes.go is the router, TestSpecRouteParity welds that table to openapi.v0.yaml by exact set equality in both directions, and capabilities on the handshake is derived from the same table. A fourth copy in this page could only ever go stale — as one did — so read the surface from the document, from the route table, or from a running server.

What the shape is, and will stay:

  • Liveness and identity answer from the process. GET /healthz and GET /v0/beads/context touch no database, which is what keeps them answerable while every connection slot is held. They alone carry bypassSemaphore.
  • Reads are collection reads plus one detail read per resource. Issues, ready work, dependencies, config, memories and stats each publish their own, and each hands its whole request to one issueops role — never to a filter built in the handler.
  • Writes come in two spellings. A custom method (:claim, :close, :reopen, :sweep, :delete, :add, :remove, :batchCreate) where the operation is not CRUD, and a plain method (PATCH on one issue, POST and DELETE on one memory) where it is. routes.go states the rule per row.
  • Every write carries the same posture. The actor is caller-asserted provenance, not authenticated identity; hooks do not fire; the per-command auto-commit machinery does not run. Durability is one storage commit per request, inside the role's own transaction. The claim was the first write and the others adopted its posture verbatim; No hooks, No auto-commit and Write throughput state it once for all of them.

GET /v0/beads/context reports which operations this build actually implements, in capabilities. That list is derived from the registered handlers rather than hand-maintained, so a release cut mid-slice cannot advertise an operation that does not work. Clients probe capabilities for operation-level support and a 400 invalid_argument / reason: "unknown_parameter" for per-parameter support; there is no finer-grained capability document, and there is deliberately no field advertising the bind mode.

Response bodies marshal internal/types values directly. There is no wire struct, so the CLI's --json output and these bodies are one compatibility domain — which cuts both ways: a serialized field on types.Issue cannot be renamed or removed without breaking the HTTP contract, not just the CLI's.

What the reads share with the CLI

The reads hold no query logic of their own. Each decodes its parameters and hands the whole request to issueops.Reader — the same role, reached the same way, that bd show --json reaches on a store. Filter construction, the workspace config it depends on, the default limits and the wisp fallback all live inside that role, so a handler cannot half-perform that construction and answer the same question a different way.

The exact scope of that property, and its limits, are stated in The claim below. It is a narrower property than "the CLI and the API cannot disagree", and the difference matters.

The error-code vocabulary

Every non-2xx byte is an RFC 9457 application/problem+json document. There is one error shape. The mapping from sentinel error to status and code lives entirely in internal/httpapi/problem.go and is matched exclusively with errors.Is/errors.As — never err != nil -> status.

code is the machine-readable member and the only member a client may dispatch on.

Code Status Meaning Recovery
invalid_argument 400 Request validation refused it. Carries param and reason. Send something different. Never retry.
invalid_cursor 400 A cursor this server did not issue, cannot decode, or issued under a different encoding version. Restart paging with no cursor.
not_found 404 No issue or wisp with that id. —
already_claimed 409 Another actor holds the claim. Carries assignee. —
not_claimable 409 The issue is not in a claimable state. Carries issue_status. —
not_closable 409 Close policy refused an unforced close: open children, or a blocker. Close the children or clear the blocker, or re-send with force.
dependency_cycle 409 The requested edges would never clear — a scheduling cycle, or a blocking edge against the issue's own ancestor or descendant. The hierarchy case carries issue_id, blocker_id and blocker_is_ancestor; their absence is what identifies the plain cycle. Send different edges. Nothing was written.
dependency_exists 409 The pair already carries an edge of a different type. Carries existing_type and requested_type. Remove the existing edge before re-adding.
busy 503 Retryable contention: the transaction retry budget was spent, or the in-flight limit was saturated. Carries Retry-After. Retry after the header's delay.
db_unavailable 503 Retryable connectivity failure reaching the database. Carries Retry-After. Retry after the header's delay.
internal 500 Anything else. —

reason splits the two client postures behind a 400 invalid_argument, so telling them apart never requires parsing detail:

  • unknown_parameter — this server does not know that parameter. Version skew; the client degrades or falls back.
  • invalid_value — the server will not act on that value: malformed, outside the vocabulary, or legal-but-refused in this server's configuration.

The vocabulary is a one-way door. Renaming or removing a documented status+code pair breaks the wire; adding one does not, which is why clients are told to default-branch on unknown codes within a status class. TestSpecStatusCodesMatchHandlerTable asserts set-equality in both directions between the handler table and the spec, so an undocumented emission and an unemittable documented status both fail CI.

Two rules govern what a problem body may say. A 5xx detail is a fixed string per code, whatever the underlying error was: driver and dial errors routinely embed the DSN, and query errors can carry SQL fragments, so a verbose 5xx detail becomes an information-disclosure channel the moment the server is bound with --allow-non-loopback. A 4xx detail stays specific, because it reflects the caller's own input back rather than server state. The real error goes to the server log, correlated by the request_id the 5xx body carries — that id is the client's only handle on the one log line that has it.

Why typed conflicts matter for adopting clients

A client that classified claim conflicts by substring-matching error text ("already assigned to", "claimed by") should switch to the typed 409 code. The assignee and issue_status extension members come from a read inside the losing transaction, never from parsing fragments out of the sentinel's message. That substring classification is exactly what an adopting client gets to delete, and it can only delete it because the server never does it either.

The dependency conflicts work the same way and are read the same way. dependency_exists carries existing_type and requested_type; dependency_cycle carries issue_id, blocker_id and blocker_is_ancestor when the refusal is the hierarchy rule, and carries nothing when it is a plain scheduling cycle — the ABSENCE is what tells the two apart. Every one of those members is read off the role's typed error inside the refusing transaction, which is the only place the hierarchy members can come from at all: the conflicting edge may exist only inside the batch that was rolled back.

The cursor contract

GET /v0/beads/issues pages with an opaque keyset cursor. GET /v0/beads/ready does not: the ready sort policies admit no keyset predicate, and the intended usage there is snapshot-and-requery.

Four properties, all normative:

Opaque. Clients must not construct, parse or mutate a cursor. The encoding is server-private and version-prefixed. It is base64 of a small JSON object, which is legible enough that someone will read it — so the contract is enforced by the version prefix rather than by obscurity. A client that mints its own token gets invalid_cursor the moment the encoding moves.

No lifetime. The token carries a position, the ORDER that position is in, and a private encoding version — and nothing else. The server keeps no state for it, so it does not expire, does not become invalid across a restart, and is not tied to the connection that issued it. The only thing that invalidates one is an encoding change, and the one encoding change made so far (v1 → v2, adding the order tag) kept every outstanding v1 token readable as the created-order position it is, so no traversal in flight had to restart.

One recovery. Every failure mode — wrong version, undecodable base64, malformed JSON, an empty position, a position in another order — is the same answer, because it is the same client situation: restart paging with no cursor. Re-sending the value cannot succeed.

Filter misuse is not detectable; ORDER misuse is. Those are two different properties and the difference is the whole of the design here.

Because the token carries no filters, a page fetched with a cursor minted under different filters is not refused. The server applies the current request's filters from the old request's position, silently skipping every row the new filter set would have placed before it. Repeat every filter verbatim for the whole traversal, and start a new traversal when they change. That is a deliberate trade: embedding the filters would make the token a second, opaque copy of the request that can disagree with the request itself, and keeping it a bare position makes the failure mode a documented client obligation instead of a hidden server-side reconciliation.

The ORDER is not a filter, and it does not get the same treatment. A filter selects the SET; the order decides what the position MEANS. The same instant and id name one row's place under sort=created and a different row's place under sort=priority, and there is nothing in the bytes to say which was intended — so a token replayed under a different sort is refused with invalid_cursor rather than reinterpreted. This is not a second copy of the request; it is the position's own type tag, and without it adding sort at all would mean serving skipped-and-duplicated pages with a 200 and no way for a client to notice.

Only orders with a proven total key are served. sort takes created and priority and nothing else, because each value is a keyset contract — a position shape, a strictly-after predicate, an index — rather than a display preference. Both of these keys are total (priority and created_at are non-null, id is unique), so a page boundary inside a run of equal keys resolves on id with no dropped and no repeated row. The seven other orders bd list --sort accepts have no such key: id is a natural-numeric order no database expresses, updated moves on every write, closed is nullable, and status/title/type/assignee are mutable and unindexed. A client that wants one of those still pages in created order and sorts what it received.

priority is itself mutable, which created_at is not, and the consequence is stated rather than hidden: under created only new rows move relative to a walk, while under priority a priority update moves an existing row too, so it can be seen twice or missed. That is the same "a cursor pins a position, not a snapshot" caveat reached by a second route, not a new class of error — unchanged data never skips or repeats under either order.

GET /v0/beads/ready still publishes a sort with a wider vocabulary and no cursor at all, which is consistent rather than contradictory: without a cursor an order is only a display decision, and nothing has to be able to resume into the middle of it.

The loopback posture

v0 has optional bearer authentication and no TLS. On loopback the trust model is the loopback boundary — the same boundary the database behind it already relies on — and a bd serve with no auth flags is byte for byte the server it has always been.

--auth-token-file turns authentication on: every operation except GET /healthz then requires Authorization: Bearer <token>, including GET /v0/beads/context, which reports the repo root, beads directory and database name. The file holds one token per line and every line is accepted; it is re-read while the server runs, so rotation and revocation both take effect within about a second and neither needs a restart. There is deliberately no --auth-token flag: an argument is readable out of the process listing by every local user.

The token is a shared secret that grants the WHOLE surface. It is not an identity, it carries no scopes, and it therefore never makes actor an authenticated principal — see below.

--addr defaults to 127.0.0.1:0. The host must be a numeric IP literal. --allow-non-loopback is the operator decision to bind beyond loopback; it is never taken by default, and it now requires --auth-token-file, because otherwise reaching the address would be the whole authorization: every peer that can reach it would get full read and claim access. --insecure-no-auth is the explicit, auditable way to say you meant that anyway — it applies only beside --allow-non-loopback, contradicts a token file, and logs a warning naming what it exposes.

Three things bound the posture regardless of bind mode:

The Host allowlist, which has no off switch. A service on loopback is reachable from any browser on the host, and a page that re-resolves its own name to 127.0.0.1 issues requests the browser treats as same-origin, so no CORS rule stops them. What the browser does preserve is the attacker's hostname in Host, which is what this rejects. Every bind answers to the loopback spellings and to the bound address itself. A wildcard bind (0.0.0.0, ::) has no single configured address, so it answers to any numeric IP literal and still refuses foreign DNS names — a rebound page cannot produce an IP-literal Host, because the browser sends the hostname from the attacker's URL. Matching is on parsed addresses, so every spelling of an allowed address is allowed.

The JSON-only content type on every body, which is a CSRF control rather than pedantry: a JSON content type is not CORS-"simple", so a cross-origin write always triggers a preflight this server never approves. Accepting text/plain or a form encoding would let a page skip the preflight and drive a write from any browser on the host. The document states the rule once, at the document level, because it holds for every body-carrying operation.

The mode-dependent refusal of an unlimited read. limit=0 means unlimited on both list operations, exactly as bd list --limit 0 does — except under --allow-non-loopback, where it is refused with 400 invalid_argument, param: "limit", reason: "invalid_value". An unlimited read buffers the whole active set and its JSON encoding inside one shared process, which must not be reachable by arbitrary network peers. The bind mode is deliberately not advertised in ContextResponse: a client that wants an unlimited read asks for one and, on that 400, re-issues with an explicit limit and pages with cursor. It is a client-side fix, never a retry.

An actor on an HTTP request is caller-asserted provenance for the audit trail and is not the authenticated principal, even where a bearer is required: one shared token admits a client to everything, so it can neither confirm nor contradict the name a request sends. That is the same thing actor has always been on the CLI, where any local process can pass any --actor. The claim's compare-and-set is therefore a correctness fence against concurrent claims, not an authorization boundary: it guarantees that two racing claimants cannot both win, and guarantees nothing about who either of them really is.

No hooks

Hooks do not fire on any write over this surface. A CLI claim runs on_update; the HTTP one does not, and neither does any write added since.

A hook is a user-controlled subprocess per mutation. In a concurrent server that is an unbounded latency multiplier and an orphaned child at shutdown, and the working-directory-derived hook lookup that finds them is meaningless in a server process that does not share the client's working directory.

This is a contract statement, not a gap to be closed later. A client that needs hook side effects on a mutation runs that mutation through the CLI.

No auto-commit

The per-command auto-commit, export and push maintenance that wraps a CLI invocation does not run here. Durability is per request: a write that changes something commits inside its own transaction, exactly as the proxied CLI does today.

Two consequences worth stating for an adopting client:

  • There is no end-of-process flush. Anything the server did is already durable when the response is written, or it is not going to be.
  • An idempotent write by the party that already got the outcome it asked for writes no commit. A re-claim by the current holder, a re-close of a closed issue, a reopen of an open one: the compare-and-set matched no row because there was nothing to change, and an empty commit message tells the transaction runner to skip the commit — so a polling client cannot mint an empty storage commit per call.

Write throughput

Every mutation on this surface costs a storage commit. Sizing follows from that, not from HTTP:

  • A write that changes something commits. Its throughput ceiling is the store's write path, which serializes commits, and not the request pipeline in front of it. HTTP concurrency does not raise that ceiling.
  • Contention surfaces as a retryable 503, not as a stall. The transaction runner spends a serialization-retry budget internally; exhausting it produces busy with Retry-After: 5. That delay is deliberately not one second: the budget already spans many seconds of observed write contention, and a one-second comeback invites a convoy of retries that each hold a database slot while they wait, starving reads exactly when the server is busiest.
  • Saturation surfaces as the same code with a shorter delay. A request that cannot get a database slot within the bounded wait is also busy, with Retry-After: 1, because slot pressure clears quickly. Shedding load introduces no new status vocabulary — one code, two delays, and the header is the thing to obey.
  • An idempotent write costs no commit (above), so a client polling to confirm it still holds a claim does not consume write throughput.
  • Reads are bounded by slots, not by commits. Every database-touching handler holds one of a fixed number of in-flight slots, and each slot pins one SQL connection. The arithmetic is in SERVE_RUNBOOK.md.

Wisps are not claimable over v0. The claim dispatches to the issues table only, so a wisp id answers 404.

The claim

Carried across from internal/httpapi/doc.go and issueops/reader.go, which are the source of truth for it. Stated once and in full so it can be checked sentence by sentence, and deliberately not strengthened here.

SHARED. GET /v0/beads/ready, GET /v0/beads/issues and GET /v0/beads/issues/{id} go through issueops.Reader, and so does bd show --json's detail view on both its routes. This says nothing about the surface's other reads, which are on sibling roles. bd list and bd ready are not on the role and share instead the request types, the two builders in internal/workapi that their golden files pin, and workapi.FinishPage — bd list on both routes in every mode but the hierarchical --parent tree, bd ready on its proxied route only.

ENFORCED, and by what. depguard (httpapi-transport-boundary) denies internal/workapi from every non-test file of internal/httpapi, so no builder is callable there; a forbidigo rule denies naming types.IssueFilter or types.WorkFilter there at all, so no filter is writable there either. Both are directory-scoped with no per-file exception, so a file added to that package tomorrow is covered the moment it exists. That same forbidigo rule covers cmd/bd deny-by-default with 64 named exceptions, so the files implementing bd list and bd show cannot write a filter, and neither can a file they are split or renamed into unless the new name lands on that list.

NOT ENFORCED. The rule forbids naming those types, not holding a value, so the property is "no filter is written there", not "every filter there came from a builder". Test files are exempt from both rules, because the oracles hold filters in order to inspect them. bd ready's files are among the 64, since its listing and --claim are handed the filter itself and the blocked-issue views in those files name one directly, so it is guarded by the builder and the golden files and not by the linter. GET /healthz and GET /v0/beads/context are not issue queries and are on no role. bd ready's direct route and bd list's hierarchical tree run epilogues of their own. And none of this is a merge gate: the rules run in make ci-pr-lint on every pull request and aggregate into the ci-gate job, but main carries no branch protection beyond deletion and non-fast-forward, so no check is GitHub-required and a red gate binds by convention.

Closing the rest needs more roles — a claim role, an explain role — not more methods on the read one.

Workspace modes

bd serve refuses exactly one workspace mode, permanently: embedded Dolt. Its commit protocol runs outside the SQL transaction on a separate connection, so the per-request atomicity this contract states would be a lie there. That is a property of the backend rather than of what has been built so far, which is what makes the refusal permanent — and it is also why there is no unit-of-work provider for it and will not be one. The refusal names the workspace and what serve needs, and promises nothing further.

WHERE IT IS ENFORCED, stated exactly, because it used to be enforced by construction and no longer is. httpapi.Listen once took a unit-of-work provider or nothing at all, so an embedded-backed server was not constructible — the absence of a provider was itself the refusal. httpapi.Config now also takes the two issue roles as a database source, and the embedded store publishes both accessors, so one is. The gate is serveDatabaseSource in cmd/bd/serve.go, which classifies the workspace and refuses; it is both the gate and the wiring decision, in one function, so the two cannot disagree about one workspace. TestServeRefusalsPromiseNothing pins both that it refuses and that its message promises nothing, and TestServeRefusesAnEmbeddedWorkspaceEndToEnd drives the refusal through runServe. TestServeNamesOneDatabaseSourcePerServerItBuilds pins against the source of cmd/bd that every server bd builds names exactly one complete database source and that a roles-backed one is only ever built where that classification is consulted — so a change that reached for store roles anywhere else fails a test rather than quietly reaching the embedded backend by a path this gate never sees.

NOT ENFORCED. internal/httpapi does not refuse an embedded-backed server and cannot. A role is an interface, and no inspection of one reveals the commit protocol of the backend behind it; every check available at that layer is a self-declaration by the same caller-supplied code being checked, which is the trust it would be replacing rather than a replacement for it. The precondition is therefore stated on Config.Reader/Config.Claimer — each call commits on its own, atomically and durably — and a caller outside bd that hands the server embedded-backed roles gets a server whose per-request atomicity claim is false, with nothing in this repository to stop it.

Every mode with a SQL server behind it is served: proxied (managed or external), and server, external-server and shared-server. In the latter three the root command has already opened a DoltStore that serve never uses; serve builds its own unit-of-work provider from the same connection settings. That idle store matters only for the connection budget — see the runbook.

A REGISTERED BACKEND IS SERVED FROM THE STORE THE ROOT COMMAND OPENED. A downstream distribution registers a backend (internal/storage/backends) whose facade is a store rather than a unit-of-work provider, and PersistentPreRunE already opens it through the same backends.Lookup dispatch every ordinary bd command opens it with. So serve creates nothing on this arm: it takes Config.Reader and Config.Claimer off that store and hands them to Listen. A second handle would double the pools and self-conflict with any backend holding an exclusive workspace lock, and one creation path is the point. PersistentPostRunE closes the store, after runServe returns and therefore after the server has drained.

The roles come from BENEATH the hook decorator ((*storage.HookFiringStore).Unwrap, one layer, never storage.UnwrapStore — the telemetry layer below it must survive). A store's accessors hand out its decorators by design, so the obvious store.IssueClaimer() returns a claimer that runs the workspace's on_update script for every claim it lands, which is exactly what this server documents it does not do. Listen refuses a hook-firing role rather than trusting that anyone read this paragraph.

The classification consults the registry BEFORE any Dolt-mode signal, because the store open already resolves them in that order: a registered workspace opens its registered store even with BEADS_DOLT_SHARED_SERVER=1 exported. Resolving it the other way would build a Dolt provider over a non-Dolt store and answer HTTP from a different database than the CLI reaches in the same directory.

That "one store" claim is pinned as a property rather than as a shape. TestServeAnswersFromTheStoreTheRootCommandOpened wires the registered backend so every open hands back a store whose reader answers with one issue named after that open, and reads the name back off GET /v0/beads/ready: a serve that opened a handle of its own answers as store-2. The end-to-end test counts opens through the registry and requires exactly one for the whole process. Both are needed — the count catches the leak, the name catches the substitution — because a second handle is otherwise invisible: same reads, same claims, same handshake, same clean shutdown.

THE IDENTITY HANDSHAKE IS BACKEND-AWARE. GET /v0/beads/context reported backend="dolt", dolt_mode="embedded", database="beads" for a registered workspace — a full description of the exact topology this command refuses to serve, on the one endpoint automation is told to trust for a server's identity, while the startup line beside it named the registered backend correctly. The cause was in the shared projection: GetContextInfo hardcoded the backend to dolt and copied the Dolt fields unconditionally, and both of those DEFAULT rather than fail (an absent dolt_mode reads "embedded", an absent dolt_database reads "beads").

The fix is in that projection (domain.ContextInfo.SetBackendIdentity), not in bd serve, and the placement is the point: bd context, bd context --json and this endpoint all read their workspace identity through domain.PublishedContext, which exists so the three cannot name one workspace differently. Correcting the value in runServe would have made the HTTP handshake truthful and left the CLI printing backend: dolt in the same directory — reintroducing exactly the drift that projection prevents. It also put the gate beside the one already there: IsDoltServerMode and IsDoltProxiedServerMode are false for any non-Dolt backend, so the bind endpoint and proxied root were already withheld; dolt_mode and database were the two with no such guard.

There were TWO copies of the hardcode, which is why one policy function rather than one edit: the contextinfo use case, and bd context's direct route, which reads the config files itself so it can answer in degraded states where no database opens. Both carried their own Backend: configfile.BackendDolt, so they agreed by telling the same lie — indistinguishable, until now, from agreeing. TestContextRoutesNameOneWorkspaceTheSameWay compares what the two routes publish for one workspace, which is the claim the shared projection has always made and nothing had tested.

A registered backend reports the EMPTY string for both, and that is the only value bd can assert. The backend's Open reads whatever it wants out of the workspace; bd does not implement it and cannot know which logical database it settled on, so any non-empty guess is the same lie made quieter. Both stay required strings on the wire — no field is renamed, retyped or dropped, and the v0 shape is unchanged.

STRICT READONLY IS REFUSED. bd --readonly serve does not bind, on either source, and the gate runs before the workspace is resolved so that the answer cannot depend on the topology. Every server this command builds publishes the same operation set, claim included.

It had degraded differently and silently on each source. On the store source the root command opens through backend.OpenReadOnly and serve took its claimer off that store, so the server bound, kept advertising issues.claim, and answered every claim with an opaque 500, leaving the issue open and unassigned. On the provider source serve builds its own unit-of-work provider from the workspace's connection settings, which carries no read-only posture, so --readonly bought nothing and every claim landed. (Proxied mode never reached either: the root pre-run already refuses strict readonly for it.)

The alternative — dropping issues.claim from a read-only server's advertised capabilities — was rejected as a wire change: capabilities is the documented pre-flight a client checks before calling, and making one operation's presence depend on a flag on the process that started the server gives a client something it cannot discover before connecting. Refusing keeps the published surface a property of the build, and matches how bd already answers this question one layer down, where a backend that cannot guarantee mutation-free access is turned away rather than opened anyway.

The wire-shape signal

capabilities answers which OPERATIONS a build serves. Nothing answered whether an operation's response SHAPE had changed underneath a client already built against it — a client decoding a strict schema against a future server that renamed or retyped a field it depends on would fail wherever it happened to read that field, with no single place to check first. wire_revision and min_client_wire_revision, both on GET /v0/beads/context, are that single place.

wire_revision is a counter, not a semver: it bumps only for a NON-ADDITIVE change to an existing response member's JSON name or type (a new, purely additive member needs no bump). The full history is the wire_revision property's description in openapi.v0.yaml — 0 for every build before this field existed (an integer revision, pre-#6053), 1 for the brief string-typed revision (#6053), 2 for the first build carrying wire_revision itself. A client talking to a build too old to answer this field at all may use bd_version as an ADVISORY hint, never proof: compare it as semver with pre-release identifiers and treat >= 1.3.0-rc.1 (not the release cutoff 1.3.0 — a 1.3.0-rc.N build already carries the string shape and sorts below 1.3.0) as a hint toward 1, else a hint toward 0. Two known builds defeat even that corrected hint: main up to commit b3ef65c85 reports bd_version: "1.2.2" while already sending strings, and the bd-enterprise compatibility line at d3ab32773462 reports "1.1.0" while also sending strings. A client therefore MUST accept revision and expected_version as either a string or a number whenever wire_revision is absent (or probe the shape directly) rather than let the inferred value choose a decoder, and MUST NEVER refuse solely because the inferred revision is 0 — see the wire_revision property's description for the exact language.

min_client_wire_revision is the other half: the oldest revision a build still answers correctly. A client that knows the revision it was compiled against may assert it on ANY request via the optional Bd-Wire-Revision header — not only the handshake — and checkWireRevision refuses a request naming a revision below the floor with 400 invalid_argument/ reason: "wire_revision_unsupported" and a min_wire_revision field pinning the floor that was violated, before the server does any work building a body shaped for a revision the client has already said it cannot decode. The header is optional and absent by default, which is what keeps this additive: an older client that never sends it is served exactly as before. A malformed value (not a non-negative integer) is a different mistake — reason: "invalid_value" — and must never disclose min_wire_revision, which is reserved for a revision the server actually read and understood to be too old.

The check runs on every route but GET /healthz (wireRevisionExempt, routes.go) — including the identity handshake itself, unlike the Bd-Project-Id stamp, which exempts the handshake because that is how a client LEARNS the id it must stamp with. A client that already knows the wire revision it was built for has no equivalent reason to omit it on the very first request, and the handshake is where a floor violation is cheapest to catch: before the client has acted on anything shaped for a revision it cannot decode. Liveness is exempt for the same reason Bd-Project-Id is: a probe carries no notion of either header, and refusing it for one it never had a reason to send would make /healthz lie about the process being alive.

The golden digest. A revision bump is a promise a human makes; nothing enforced that the promise was kept, or that it was even necessary. CI pins one against the other with a golden digest, internal/httpapi/wireshape: wireshape.Compute walks every response's AND every request body's every content-type schema across the whole spec — not only application/json, so application/problem+json and therefore Problem itself is covered too — recursing through $ref and through a schema's own allOf or oneOf, and recording, keyed by schema and member name, each member's JSON name, type, format, enum values, required-ness, and nullability, plus the scalar shape of array items and of additionalProperties map values. It records every operation parameter (query, path, and header) as well, keyed by operationId, location, and name rather than by schema — two operations' same-named parameters are independent contracts — with its type, item shape, enum values, required-ness, style, explode, and default; style and explode are the effective values, OpenAPI's defaults filled in where the document leaves them unset, so spelling a default out changes nothing while flipping one does. The digest is a boundary, not the whole wire: value constraints such as maxLength or pattern (on members and parameters alike) and a composition keyword on a single member's own value are outside it, an object-typed or content-described parameter is recorded only as its container, and a new member or parameter always counts as additive — even a required one an old client will not send — so each of those needs its own review against wire_revision. TestWireShapeDigest fails on any disagreement between golden and spec, and the failure names the fix: a changed or removed entry without a wire_revision bump is drift nobody signed off on; a wire_revision LOWER than the golden's means the constant itself is wrong, since the revision table only ever grows; any other difference — a bumped wire_revision, or entries only added — means the golden is simply stale. Drift and staleness share one explicit fix, go run ./internal/httpapi/wireshape/cmd/gendigest — never run to make a failing test pass on an accidental shape change, only after the revision bump and the openapi.v0.yaml history entry it belongs beside; the command itself refuses to write a changed or removed entry unless wire_revision has moved past what the existing golden recorded, and refuses any write at a lowered wire_revision, so running it cannot silently launder drift into the baseline. A purely additive diff — new members or parameters, with no existing entry changed or removed — writes at the golden's own wire_revision or any later one.

The new-parameter and new-request-body-member token rule. capabilities already required a resource.verb token for a new OPERATION; nothing required one for a new PARAMETER, or new JSON request body member, on an EXISTING operation, so a client had no single place to learn that, say, GET /v0/beads/issues's sort parameter had started accepting a value. issues.list.sort is the first deliberate use of the same convention one level down: the token lives in the parameter's (or body member's) own description, exactly as capabilities members carry theirs, enforced by TestNewParameterOnExistingOperationHasABehaviorToken against three frozen baselines (internal/httpapi/testdata/pretoken_parameters.json, pretoken_request_body_members.json, pretoken_operations.json) describing every parameter, body member, and operation the document already had the day the rule was written — written once and pinned never to grow (TestPretokenBaselinesNeverGrow), since only something pre-existing and untokened ever belongs on them, and a brand-new operation is permanently exempt from the rule: its own review decides its capability story, not a baseline written before it existed. A backticked a.b(.c)-shaped span in a description is not enough on its own: the rule also checks the token against Capabilities()'s own served list, so Go identifiers or example values that merely look like a token (workapi.DefaultReadyLimit, status.custom) do not satisfy it. TestUntokenedParameterRuleFires and TestUntokenedRequestBodyMemberRuleFires prove the checker itself still distinguishes tokened, grandfathered, and untokened parameters and body members — including a real-but-unrelated token, which correctly passes, since Capabilities() has no per-parameter binding to check a token's relevance against, only its existence — against synthetic fixtures rather than the real spec, so the rule's own logic is covered independently of whether the current document happens to exercise every branch.