* 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>
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-checkfails 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 /healthzandGET /v0/beads/contexttouch no database, which is what keeps them answerable while every connection slot is held. They alone carrybypassSemaphore. - 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
issueopsrole — 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 (PATCHon one issue,POSTandDELETEon one memory) where it is.routes.gostates the rule per row. - Every write carries the same posture. The
actoris 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
busywithRetry-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, withRetry-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.