docs: the ext-api-store documentation tranche — post-#5516 auth sweep, wave doc coherence, role checklist refresh (#5545)

Three beads (ga-uwix0.1, ga-2yaqp.5, ga-2yaqp.6) plus a fable review round.
Docs and spec prose only: all 19 touched .go files are gofmt-normalized,
comment-stripped byte-identical to main. The one exception is deliberate and
reviewed — scripts/check_doc_freshness_test.go gains a data row, because the
delegated gate ruling required it.

ga-uwix0.1 — #5516 gave bd serve optional bearer auth and made it MANDATORY
beyond loopback; fifteen prose sites still said the opposite. The three the
council named are reworded to the stronger true form (the actor is not the
authenticated principal even where a bearer is required; a shared token admits
a client to the WHOLE surface and grants no narrower right). The sweep for a
fourth found eight more in five spellings the audit's grep could not reach,
including claim.go's "any client can claim as any name", release.go's
no-AUTHORIZATION variant, and six memory/settings-plane sites where the true
statement is sharper: a bearer decides WHO may call, never what a caller who
is let in may read. The review round found four more in the CHANGELOG's
UNRELEASED section, which round one had misclassified as released history —
they would have shipped false in the same release as the auth entry.

The serve runbook's "Binding beyond loopback" section was actionably wrong: it
said the flag "prints a warning and changes nothing else", and its refusals
table quoted a string not in the binary. Rewritten against a build, with every
flag, error string, event name and reason value produced by running the
command. It gains the operational trap nobody had written down: /healthz is
auth-exempt and GET /v0/beads/ready is not, so an unauthenticated readiness
probe earns a 401 forever while liveness stays green. The runbook is now IN
scripts/check-doc-freshness.sh, pinned to the four files it is read against.

ga-2yaqp.5 — nine prose defects, every count re-derived rather than trusted;
three of the audit's own numbers had moved again. 38 route rows and 36
capability-bearing ones; thirteen pinned schemas, not twelve or seven; six
missing entries in the no-query-parameter list, not five; twenty-eight role
accessors, not twenty-seven; nineteen patch members, not thirteen. Two prose
"code counts" were counting paragraphs. CodeAlreadyClaimed claimed the holder
is always attached when only one of four producers always attaches it and
releaseIssue never does. MetadataCAS's leaf contradicted its own shipped wire.
The path/operationId inversion is now recorded where a spec author looks.

ga-2yaqp.6 — the role checklist refreshed against what this wave's additions
actually cost, traced to real commits. Step 10 sent people to a name list
#5460 deleted. The "four more edits" claim was stated twice and undercounted
both times: the two freshest wire slices share a nine-file core plus
roles_test.go. The step-with-no-number gained the fact that explains its
instances — write-role decorators wrap, read-role decorators recurse, so the
call lands on the stub, and both real instances are reads. The wave got its
first CHANGELOG entry: six new public operations, not three, and zero new role
accessors in the window.

Review verdict: FIX-REQUIRED then all items addressed. The reviewer
live-falsified the strong auth form and failed to break it, and confirmed
every recount re-derives exact.
This commit is contained in:
Julian Knutsen 2026-08-10 08:05:07 -07:00 • committed by GitHub
commit ff75b45c91
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
27 changed files with 766 additions and 186 deletions

View file

@ -9,6 +9,98 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
- **`bd serve` gets optional bearer authentication, and requires it beyond
loopback** ([#5516](https://github.com/gastownhall/beads/pull/5516)). The
help used to say "no authentication and no TLS", and the first half of that
is what kept the server on a developer's loopback. Two flags answer it, and
both default to today's behavior: a `bd serve` with no arguments is byte for
byte the server it has always been.
`--auth-token-file` names a file of accepted tokens, one per line, all
accepted. Every operation except `GET /healthz` then requires
`Authorization: Bearer <token>` — `GET /v0/beads/context` included, because
it reports the repo root, beads directory and database name. There is
deliberately no `--auth-token`: a credential passed as an argument is
readable out of `ps` by every local user. `BEADS_SERVE_TOKEN_FILE` is the
environment fallback.
**Rotation is a file rewrite, with no restart.** The accepted set is not a
startup snapshot: the file is re-read while the server runs, at most once a
second for the whole process, on the accepting path as well as on a
mismatch — which is what makes REVOCATION work and not just rotation. Write
`{new,old}`, roll the clients, drop `old`; both take effect within about a
second. A failed or empty re-read keeps the last-good set and logs, so a
writer that truncates before writing cannot lock every client out.
**`--allow-non-loopback` now requires a token file.** Beyond loopback,
reaching the address would otherwise be the whole authorization.
`--insecure-no-auth` is the explicit, auditable way to say you meant that
anyway. There is still NO TLS: a deployment beyond loopback supplies
confidentiality itself. `--allowed-host` (repeatable, exact, no wildcards)
adds Host header values to the DNS-rebinding allowlist, which is what a
service deployment behind a DNS name trips over first.
`401` / `unauthenticated` joins the frozen code vocabulary, with
`WWW-Authenticate: Bearer` and a FIXED `detail` that never echoes the
presented credential. A missing header, a wrong scheme and an unrecognized
token are one code deliberately — telling them apart would tell an
unauthenticated caller which guess was closer. **A token is a shared secret
granting the whole surface, not an identity**, so `actor` is still
caller-asserted provenance and not the authenticated principal.
- **Six more v0 operations, and the guarded-write token they compose from**
([#5506](https://github.com/gastownhall/beads/pull/5506),
[#5507](https://github.com/gastownhall/beads/pull/5507),
[#5508](https://github.com/gastownhall/beads/pull/5508),
[#5510](https://github.com/gastownhall/beads/pull/5510),
[#5535](https://github.com/gastownhall/beads/pull/5535),
[#5536](https://github.com/gastownhall/beads/pull/5536),
[#5540](https://github.com/gastownhall/beads/pull/5540)). Each is the wire
half of a role that already existed and was already pinned on three legs.
- `POST /v0/beads/issues/{id}:release` — give a claim back, what `bd
unclaim` spells. **It is NOT idempotent, and that is the one thing to read
before adopting it**: a release over a row holding no claim is `409` /
`not_releasable`, never a 200, because the post-state is anonymous. Do not
read the code as "already released" — it also covers "the status will not
accept a release", which is true of a row that is still ASSIGNED. Read the
row. `expected_assignee` is a compare-and-set on the holder and `force`
ignores it; the two may not be sent together.
- `POST /v0/beads/issues:claimNext` and `POST /v0/beads/issues:batchClose` —
take the next ready bead in one round trip, and close many as one act.
- `GET /v0/beads/issues:count` and `GET /v0/beads/dependencies:count` — the
two counting reads, each with its role's whole filter surface.
`dependencies:count` bounds `issue_id` at 100 anchors.
- `GET /v0/beads/issues/{id}/related` — one anchor's neighbors, direction-
parameterized and type-filterable. The length of `items` is a NEIGHBOR
count and not an EDGE count: a target that is an `external:` reference or
another repository's id has no far end here and is silently not a
neighbor, while the same edge IS a row on `GET /v0/beads/dependencies`.
- `expected_version` on close, reopen and delete, and `revision` on `GET
/v0/beads/issues/{id}` — the row's optimistic-concurrency token, so a
read-modify-write loop can start from a READ instead of seeding its first
guard from a write it did not want to make. A miss is `409` /
`precondition_failed` and writes nothing. **`revision` is deliberately NOT
on the listing rows**: `types.IssueWithCounts` is also the JSONL
interchange record, so a token there would write a per-write-random value
into every `bd export` line and every auto-flushed `issues.jsonl`.
`not_releasable` joins the frozen 409 vocabulary. Every one of these carries
the claim's posture unchanged: `actor` is caller-asserted provenance, hooks
do not fire, the per-command auto-commit machinery does not run, and the only
durable effect is the single storage commit the role makes in its own
transaction.
- **`bd serve` answers a `Bd-Project-Id` header, and says so in
`capabilities`.** A client that knows which workspace it means to address
stamps the request with that workspace's project id; a server that serves a
different one refuses before any database work, so a misdirected read or
write mutates nothing. An ABSENT header is served exactly as before, so this
is additive wire surface and not a new precondition. `GET /healthz` and `GET
/v0/beads/context` are exempt — liveness must answer whatever workspace a
caller believed it reached, and the handshake is where a client LEARNS the id
to stamp with. Detect it with the `project.enforce` capability.
- **A durable events journal, and `bd events` to read it** (bd-opisf). External
tooling that wants to stay in step with a workspace had two options and
neither was a feed: a fire-and-forget script hook that may not run, or polling
@ -93,7 +185,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`200` with `already_closed: true`, a reopen of an open one
`already_open: true`, and each still carries the row.
- `PATCH /v0/beads/issues/{id}` — partial update of one issue. The `patch`
object publishes thirteen members; four of them (`estimated_minutes`,
object publishes nineteen members; four of them (`estimated_minutes`,
`external_ref`, `due_at`, `defer_until`) are nullable, and an explicit
`null` CLEARS them. That set is closed and machine-checked against the
document, so a `null` on any other member is a `400` rather than an
@ -218,15 +310,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
reason move from the Dismissed count to the Responded count. Forward
behavior is unchanged.
- **`bd label add`/`remove` over many issues is no longer one atomic
transaction** (ga-26w10,
[#5489](https://github.com/gastownhall/beads/pull/5489)). Both routes — the
direct one and the proxied-server one — now end at `issueops.Lifecycle` and
`issueops.Reader`, which deletes the four-way `(add|remove) × (wisp|durable)`
switch the proxied route hand-rolled below the roles and the second
implementation of the command that came with it. The plane is resolved
inside the role's own transaction, so the wisp branch is gone rather than
moved.
**The deliberate delta:** a multi-issue edit is N guarded updates rather than
one raw transaction, so `bd label add a b c mylabel` records three history
entries instead of one, and a failure on the third leaves the first two
written where the old shape rolled them back. Neither is obviously right —
the new one attributes each edit to its own issue and lands what it could —
and the atomic shape is expressible today as one `issueops.BatchApplier`
update item per issue. The proxied route's resolution failure also lost its
`label added: ` prefix, which named a write the command never attempted;
both routes now print the direct route's message.
`bd label list-all` and `bd label propagate` are unchanged and stay off the
role: no role answers "every distinct label in this workspace", and
propagate is a search plus a fan-out needing the same batch question.
- **The settings plane no longer serves the KV plane by any read** (bd-rfwtv,
bd-klko9). `bd kv` keys and the `bd remember` memories nested under them are
user data stored as config rows; they ride in the settings table without being
settings. Listing them was already excluded, but a caller naming an exact key
still got the value — and since `bd remember` derives its key from the content
it stores, the keys are guessable, so `bd config get kv.memory.<slug>` and
`GET /v0/beads/config/kv.memory.<slug>` (a surface with no authentication,
whose redaction decides on the key NAME while a memory's secret is in the
VALUE) walked around the exclusion.
`GET /v0/beads/config/kv.memory.<slug>` (a surface whose only credential is
an optional shared bearer, and whose redaction decides on the key NAME while
a memory's secret is in the VALUE) walked around the exclusion.
A point read of a `kv.` key now answers exactly as a key nothing ever stored
does — the echoed key, an empty value, a nil error — so a caller cannot tell a
@ -534,8 +650,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
routes now call. `capabilities` gains `issues.sweep`.
**This is the first DESTRUCTIVE operation on the surface, and nothing it
deletes comes back.** `bd serve` binds loopback and has no authentication, so
anyone who can reach the port can now clear closed beads: `--help` gained a
deletes comes back.** `bd serve` binds loopback, and its bearer — optional,
and where configured a single shared token admitting a client to the whole
surface — grants no narrower right, so anyone who can reach the port with a
credential it accepts can now clear closed beads: `--help` gained a
DESTRUCTIVE OPERATIONS section and the `--allow-non-loopback` warning says so.
A `durable` sweep with neither a cutoff nor a pattern is refused by the role
itself rather than by the handler, and `dry_run: true` costs the same request
@ -543,10 +661,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
**`protect_referenced` defaults to `true` here**, where the CLI's equivalent
(`--ignore-references`) is opt-out. The local flag and the remote member
therefore disagree on purpose: this surface has no authentication, and a
remote caller who omits a member should not get a weaker guard than the
operator typing the same sweep locally. Send `protect_referenced: false` to
match the CLI default.
therefore disagree on purpose: being authenticated here says nothing about
whether this particular deletion was meant — one shared token admits a client
to everything published — so a remote caller who omits a member should not
get a weaker guard than the operator typing the same sweep locally. Send
`protect_referenced: false` to match the CLI default.
- **`GET /v0/beads/config` and `GET /v0/beads/config/{key}` — the workspace's
stored settings over HTTP** (bd-kzepq). `bd serve` now answers for the
@ -559,8 +678,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`notion.token` does — **is published with `redacted: true` and no `value`.**
Withheld values are OMITTED rather than masked, so a client cannot mistake a
placeholder for configuration. The CLI is unchanged and still prints stored
values in full: its caller already holds the database, and this surface has
no authentication.
values in full: its caller already holds the database, while redaction is the
whole control on this surface — a bearer here is optional and, where
configured, shared and surface-wide, so it cannot withhold one value from one
caller.
There is no HTTP WRITE, deliberately. `bd config set` routes most keys to
`config.yaml` or to git config before the database is ever reached, and both

View file

@ -305,8 +305,8 @@ func RunWorkspaceConfigListExcludesTheKVPlane(t *testing.T, ctx context.Context,
// who knew the exact key was a different class of caller, and `bd remember`
// derives its key from the content it stores, so the keys are guessable and
// GET /v0/beads/config/kv.memory.<slug> walked around the wall — on a surface
// with no authentication, whose redaction decides on the key NAME while a
// memory's secret is in the VALUE.
// whose only credential is an optional shared bearer, and whose redaction
// decides on the key NAME while a memory's secret is in the VALUE.
//
// WHAT IT ASSERTS IS AN INDISTINGUISHABILITY, and it takes four probes to say
// so:

View file

@ -119,7 +119,9 @@ record — editing or deleting a bead does not redact it from the journal. And
because this is an HTTP read, any process that can reach the address gets that
history without the filesystem permissions on `.beads/` that `bd events tail`
requires. Weigh both before binding a journal-enabled workspace with
`--allow-non-loopback`; `bd serve` has no authentication.
`--allow-non-loopback` — which requires `--auth-token-file` (or the explicit
`--insecure-no-auth`), and that token is shared and surface-wide: every client
holding it reads the whole journal.
</Warning>
Two refusals are worth wiring into a consumer before it ships. A checkpoint
@ -219,7 +221,8 @@ ignores it does not lose records silently, but it does stall loudly: a bare
</Warning>
The exposure warning above applies identically — a stream is the same history
over the same unauthenticated address, held open — and so does the capability
over the same address and under the same shared credential, held open — and so
does the capability
rule: `events.watch` appears in `/v0/beads/context`'s capabilities on every
build, and says nothing about whether this workspace has a journal.

View file

@ -31,6 +31,37 @@ question (`Count` and `CountByGroup` share a predicate and differ only in
whether the answer is a number or a number per bucket). The rule forbids
APPENDING later, not being born whole.
**And a third question, which the first two do not ask: does a SIBLING already
answer this, and do both survive the answer?** "Different question" is only
half a test, because two roles can each be a different question and still be
one capability split in two — and the split is only worth it if each half is
reachable, contract-pinned and named on its own terms afterwards.
`issueops.BatchCreator` and `issueops.BatchApplier` are the worked example.
Both write many beads in one transaction, and the tempting reading is that the
second subsumes the first: an apply plan of N create items is a batch create.
It is not, and the reason is what to copy:
- **The QUESTIONS differ in what the caller is allowed to say.** `batchCreate`
takes a homogeneous list of creates and answers with the created rows in
request order; `batchApply` takes a heterogeneous plan of creates, updates
and closes over rows that may not exist yet, with intra-plan references and a
per-item guard vocabulary. Folding the first into the second would make every
caller of "create these ten beads" compose a plan.
- **The REFUSALS differ, and a caller dispatches on them.** `batchApply`'s 409
vocabulary carries `item_index`, `item_kind`, `item_key` and
`item_issue_id`, because an item is the unit that failed. `batchCreate` has
no items to name, and inheriting a refusal shape it can never fill would put
four always-absent members on its wire.
- **BOTH SURVIVE, and that is the part to check.** Each has its own contract,
its own capability token, its own operation, and a front door that reaches
it. Neither is a thin wrapper the next reader will ask about.
If a sibling would be left as a shim over the new role — same refusals, same
answer shape, one call through — the honest outcome is one role, not two. Ask
it before writing the leaf, because the answer decides whether you are writing
one contract file or two.
**And one command may be born with TWO roles.** `bd init` is the case:
`Bootstrapper` writes the workspace identity and `InitVerifier` reads it, and
they are separate even though `VersionReconciler` — whose read and write are
@ -183,12 +214,32 @@ in; 13 is the HTTP surface, which lands with the command rather than after it.
today that is the `configStore` stub in `internal/jira/tracker_test.go`.
10. **The decorator enumerations.** Both `role_accessor_decorator_test.go`
files (`internal/storage`, `internal/telemetry`) list the roles by name in
`roleAccessorNames`, declare them on a fake store, implement them on a
shared sentinel, and drive them in two tables each. All five places, in
both files. Add the layering pin in `issue_roles_external_test.go` too:
a write role expects the hook wrapper outermost, a read role expects the
telemetry wrapper.
files (`internal/storage`, `internal/telemetry`) declare the role on a fake
store, implement its methods on a shared sentinel, and drive it in two
tables each — the wrapped/unwrapped table and the error-propagation table.
In the storage file the fake store also needs its field and that field's
line in `newRoleAccessorStore`; in the telemetry file the accessor returns
the single shared surface, so there is no field. Measured against
`issueops.GraphCounter`'s commit: six edits in the storage file, four in
the telemetry one.
**There is NO name list to add to, and there has not been since #5460.**
`roleAccessorNames` is DERIVED by reflection over `DoltStorage`; the
telemetry file duplicates the derivation and runs its own declaration
check, because the storage file's is unexported and in a test package it
cannot import. That is the whole point of the
derivation: the decorators embed `DoltStorage`, so a new accessor is
PROMOTED onto every one of them and everything still compiles, and a
hand-kept list would simply never hear about it. What still costs you an
edit is a fake store and a sentinel, because those are types the compiler
has to see satisfy the interface.
Add the layering pin in `issue_roles_external_test.go` too: a write role
expects the hook wrapper outermost, a read role expects the telemetry
wrapper. And when you touch the storage file's pass-through paragraph — the
one naming which roles return the inner surface unwrapped — add the role
there rather than beside it; the paragraph exists so "recurses" reads as a
decision instead of an omission.
11. **The conformance contract and its three wirings.**
`backend/conformance/<role>_contract.go` holds the cases and the
@ -226,18 +277,46 @@ in; 13 is the HTTP surface, which lands with the command rather than after it.
provider can never be, so a case placed there silently never runs on the
backend most likely to diverge.
**TWO GATES NOW FAIL THE BUILD IF YOU SKIP THIS STEP, and both take a
reasoned waiver rather than silence.** They exist because coverage used to
be aspirational: `issueops.Importer.ImportBatch` had no contract case from
the day it was written and nothing noticed.
- **`TestEveryRoleMethodHasAContractCase`**
(`backend/conformance/role_coverage_gate_test.go`). Every method of every
interface the public facade declares must be CALLED by a contract case in
that package. Both halves of the comparison are derived — the facade
census from source, the call sites by scanning the package — so a new
role method reaches this gate on its own. To waive, add an entry to
`uncoveredRoleMethods` keyed `"<Role>.<Method>"` with a sentence saying
why the contract tier cannot reach it. The gate is shrink-only in the
way that matters: it fails on an entry naming no real method AND on an
entry the package has since covered, so the change that writes the first
case deletes the waiver in the same diff.
- **`unwiredContractEntrypoints`**
(`internal/storage/contract_leg_registry_test.go`). The mirror question,
per LEG: a registered leg is held to every entrypoint the conformance
package exports. To waive, call `registerContractLegWaivers("<leg>",
map[string]string{"<Entrypoint>": "why"})` from an `init()`. Same rules —
a real leg, a real entrypoint, a reason, and removal the moment it is
wired — and a second registration of one entrypoint is REFUSED rather
than merged, so a waiver cannot outlive the reason that justified it.
A leg part-way through adopting the tier uses `adoptionCeiling` instead
of hundreds of identical reasons; it is asserted EXACTLY, so it is a
ratchet and not a budget.
Legs register from an `init()`, never by editing a literal. That is what
lets a distribution built on this repository bring its own leg and its own
waivers in its own file and merge without conflict (#5499).
12. **Both front doors, and the lint that keeps them there.** The CLI handler
and any HTTP handler call the role and nothing else — no filter, no config
load, no unit of work opened by hand. Since the owner's 2026-08-05 scope
decision the HTTP half lands WITH the command: the operation is written into
`internal/httpapi/spec/openapi.v0.yaml` FIRST and the types generated from
it (`make api-gen`), never the other way round. That costs four more edits
the spec tests will name if you miss one — a row in `routeTable`, an
`Op<Name>` constant and an `operationCodes` row in `problem.go`, and the
capability token in `ContextResponse.capabilities`'s prose. A role served
from the store-shaped `Config` source also becomes a required field there,
because `checkDatabaseSource` refuses a half-set source rather than letting
a handler dereference nil on a live server.
it (`make api-gen`), never the other way round. Step 13 has the measured
file list for that half; it is not repeated here, because two copies of one
count is how the last one went stale.
Then close the holes behind them in
`.golangci.yml`: add the step-3 package to the `cmd-bd-role-constructors`
depguard deny list, and if the command no longer names `types.IssueFilter`,
@ -249,10 +328,34 @@ in; 13 is the HTTP surface, which lands with the command rather than after it.
13. **The HTTP half, when the role has one.** The spec is written FIRST —
`internal/httpapi/spec/openapi.v0.yaml`, then `make api-gen` — and the
handler is written against the generated types, never the other way round.
An operation costs four more edits beside the handler: the `Op*` id and the
`operationCodes` row in `problem.go`, the `routeTable` row and its
`capability` token in `routes.go`, and that token in the document's
`capabilities` vocabulary. `make api-check` is the gate.
`make api-check` is the gate: it regenerates and fails if regeneration
changed anything, then runs the spec tests.
**What an operation costs beside the handler, measured against the two
freshest wire slices** — `issueops.GraphCounter`'s (#5536) and
`issueops.Relations`' (#5540), whose full file sets differ (each has its own
handler, its own handler test and its own proxied integration test) around
an identical nine-file core:
| File | Edit |
|---|---|
| `spec/openapi.v0.yaml` | The operation, its schemas, and the capability token in `ContextResponse.capabilities`'s prose — that token is hand-edited; `Capabilities()` itself is derived from the route table |
| `problem.go` | The `Op<Name>` constant and its `operationCodes` row |
| `routes.go` | The `routeTable` row, carrying the `capability` token |
| `server.go` | A required `Config` field, its entry in `sourceRoles`, its name in `roleSourceNames`, the `Server` field, the `Listen` assignment, and the per-request accessor |
| `claim.go` | The `timedProvider` accessor, plus the `uow.<Role>Source` compile-time assertion beside its siblings |
| `cmd/bd/serve.go` | The `serveRoleSource` method, the `serveIssueRoles` row, the `serveRoles` field, and the `httpapi.Config` literal |
| `cmd/bd/serve_source_test.go`, `cmd/bd/serve_store_identity_test.go` | The two serve stubs — a COMPILE ERROR since #5539 if you forget, see "the step with no number" |
Nine files, and the spec tests name most of them if you miss one. Budget
`server.go` in particular: six lines in one file, and the `Config` field is
REQUIRED, so every caller and test that built a Config grows a line too.
**And a tenth both slices paid, which is not in the core because it is a
test:** `internal/httpapi/roles_test.go` needs the role's fake and its entry
in `rolesConfig` — about thirty lines each time, and the compiler does not
ask for them, so it is the one on this list you can finish the operation
without noticing.
**A role may honestly have none, and `issueops.VersionReconciler` is the
one that does.** It answers a startup hook rather than a command: its two
@ -519,6 +622,15 @@ decision if the leaf doc says it: what a facade-only slice buys is ONE place
where the role's rules are stated and held to on three legs, before either
surface has to agree with the other.
**Then go back and update the leaf when a front door lands**, because the same
sentence that made the absence legible makes it a lie the moment it stops being
true. `GET /v0/beads/dependencies:count` landed in #5536 and
`GET /v0/beads/issues/{id}/related` in #5540; the first left `graphcounter.go`
saying it had "no HTTP operation either" and promising a bound "the graph-counts
wire slice sets" in the future tense, over a slice that had already set it. A
facade-only leaf carries a claim with an expiry date on it. The wire slice owns
the expiry.
## When the role's answer carries a JSON value
Two traps, both found in review of `issueops.MetadataCAS` and both invisible to
@ -571,11 +683,33 @@ notifying provider, whose missing accessor makes a caller's type assertion stop
matching; and two `cmd/bd` stub stores that embedded `storage.DoltStorage`. Grep
for the embed, not for the interface.
**A READ ROLE IS THE ONE THAT BITES, and the reason is the decorator, not the
role.** A role whose hook decorator WRAPS produces a surface the caller holds
instead of the stub's, so a missing stub accessor is only reached to build the
wrapper. A read role's decorator RECURSES — `hook_counter.go` and
`hook_graph_counter.go` are three lines each, because nothing completed and
there is no hook to fire — so the call lands on the STUB itself, and a stub
that promoted the accessor off a nil embed dereferences nil right there. Both
roles this actually happened to, `issueops.Counter` and
`issueops.GraphCounter`, are reads.
Neither was found by reasoning about it. `Counter` surfaced only once `bd serve`
began binding the role, and `GraphCounter` (#5508) surfaced as a panic in
`TestServeIssueRolesComeFromBeneathTheHookDecorator` on a full-package CI
shard — a test about hook peeling, which no `-run` pattern anyone reaches for
names, so local runs never touched it. **The sharpened rule: a role bound in
`serveIssueRoles` must be DECLARED on the serve stub store in the same commit.**
Those two `cmd/bd` stubs are the one place this step is now taken FOR you.
`serveIssueRoles` asks for `serveRoleSource` — the accessor subset it actually
reaches — and both stubs declare that subset and assert it, so a role added to
the loop is a compile error naming the missing method instead of a segfault
inside role extraction. Every other surface above is still yours to grep for.
reaches — and both stubs declare that subset, assert it with
`var _ serveRoleSource = (*serveRolesStore)(nil)`, and embed NOTHING, so there
is no promotion to hide behind. A role added to the loop is a compile error
naming the missing method instead of a segfault inside role extraction.
`issueops.Relations` (#5540) is the first role added since, and it measured the
return: `*serveRolesStore does not implement serveRoleSource (missing method
IssueRelations)`, at build time, in the file that has to change. Every other
surface above is still yours to grep for.
And note that `internal/storage/uow`'s own
package run is nine minutes — the parity guards live there, so a role slice that
runs only its contract on the three legs has not run them.

View file

@ -1,8 +1,14 @@
# `bd serve` operator runbook
Last reviewed: 2026-08-09 (freshness sources: the operating-envelope constants
in `internal/httpapi/server.go` and `internal/httpapi/events_watch.go`, and the
fields their `event` emitters write)
Last reviewed: 2026-08-10
Freshness source: `internal/httpapi/server.go`,
`internal/httpapi/events_watch.go`, `cmd/bd/serve.go` and
`internal/httpapi/auth.go` — the operating-envelope constants, the fields their
`event` emitters write, and the flag, posture and token-file rules.
Every flag, error string, event name and reason value quoted below was checked
against a build of those files, not read off the source.
Running the v0 HTTP surface. For the contract it serves — the operations, the
error vocabulary, the cursor, the loopback posture — see
@ -65,15 +71,97 @@ double-forks and expects the child to survive its controlling terminal must
either detach the process from the terminal itself or keep it in the
foreground under the supervisor.
### Authentication
Off by default, and off is the loopback posture: a `bd serve` with no auth
flags is byte for byte the server it has always been.
```
bd serve --addr 127.0.0.1:7777 --auth-token-file /run/secrets/bd-tokens
```
Every operation except `GET /healthz` then requires
`Authorization: Bearer <token>`. `GET /v0/beads/context` is **not** exempt — it
reports the repo root, the beads directory and the database name. `/healthz` is
the one exemption, because a kubelet probe presents no credential and a
liveness endpoint that 401s is a pod that restarts forever.
The file holds **one token per line, and every non-empty line is accepted**.
There is no `--auth-token` flag: an argument is readable out of `ps` by every
local user. `BEADS_SERVE_TOKEN_FILE` is the environment fallback, and it
applies only when the flag was not passed.
**Rotation is a file rewrite, with no restart.** Write the new token alongside
the old, roll the clients over, then delete the old line; both the addition and
the removal take effect within about a second. The server re-reads the file
while it runs — gated to at most one `stat(2)` per second for the whole
process, on the accepting path as well as on a mismatch, which is what makes
revocation work and not just rotation. Write it atomically (temp file plus
rename; a Kubernetes secret mount already does). A failed or empty re-read
keeps the last-good set and logs `event=auth_reload_error`, so a writer that
truncates before writing cannot lock every client out.
Tokens are held and compared as SHA-256 digests in constant time, so the
process holds no raw credential and a heap dump discloses none.
The refusal is `401` with `code: unauthenticated` and `WWW-Authenticate:
Bearer`. Its `detail` is a fixed string and never echoes what was presented; a
missing header, a wrong scheme and an unrecognized token are deliberately one
code. Each one logs `event=auth_refused` with `reason=missing`,
`reason=malformed` or `reason=unknown_token`, which is where an operator tells
a misconfigured client from a stale token. The check runs **before** the
database semaphore, so a storm of refusals costs one SHA-256 each and can never
occupy the slots authenticated clients are waiting for.
A token is a shared secret granting the **whole** surface. It is not an
identity and carries no scopes, so it never makes `actor` an authenticated
principal — `actor` stays caller-asserted provenance for the audit trail, and
any client the token admits can claim as any name.
Confirm the posture from the startup line rather than from the absence of a
flag: `event=startup` carries `auth=none` or `auth=bearer (<path>)`.
### Binding beyond loopback
`--allow-non-loopback` prints a warning and changes nothing else. There is no
authentication and no TLS: every peer that can reach the address can read every
issue and claim work as any actor. Put an authenticating reverse proxy in front
of it, or do not use the flag.
`--allow-non-loopback` **requires `--auth-token-file`**. Beyond loopback,
reaching the address would otherwise be the whole authorization: every peer
that can reach it gets full read and claim access.
One behavioral difference follows the flag: `limit=0` (unlimited) is refused on
both list operations with 400 `invalid_argument`. Clients must page.
```
bd serve --addr 0.0.0.0:7777 --auth-token-file /run/secrets/bd-tokens \
--allowed-host bd.internal.example
```
`--insecure-no-auth` is the explicit, auditable way to bind beyond loopback
with no credential. It applies only beside `--allow-non-loopback` (on loopback
there is nothing to waive) and it contradicts `--auth-token-file`. Use it only
where a network boundary you already trust is doing the job.
Either way a non-loopback bind prints a warning on stderr at startup, and the
two are different sentences — one names the missing credential, the other names
the missing TLS:
```
bd serve: WARNING: --insecure-no-auth binds 0.0.0.0:7777 beyond loopback with no authentication. Any peer that can reach it can read every issue and claim work as any actor.
bd serve: WARNING: 0.0.0.0:7777 is bound beyond loopback with bearer authentication but NO TLS. Tokens and issue data travel in plaintext; deploy it inside a trusted network boundary.
```
**There is still no TLS.** Even with a token, the credential and every issue
body travel in plaintext, so a deployment beyond loopback has to supply
confidentiality itself — a service mesh, or a trusted network boundary. An
authenticating reverse proxy in front is still a reasonable shape; the token
file is what stops the origin being open if it is bypassed.
**The Host allowlist is what a service deployment trips over first.** The
DNS-rebinding check answers only to loopback spellings and the bind address, so
a client dialing a service DNS name gets a `400` on every request. Enumerate
the names it dials with `--allowed-host` (repeatable, matched exactly, no
wildcards). The `event=startup` line prints the effective allowlist.
One behavioral difference follows `--allow-non-loopback`: `limit=0` (unlimited)
is refused on both list operations with 400 `invalid_argument` /
`reason: "invalid_value"`, whether or not a token is configured. Clients must
page.
## Probes
@ -97,6 +185,14 @@ Suggested probe settings: the readiness probe inherits the server's 60s
whole-request deadline as its worst case, so give it a timeout well under that
(2–5s) and let the probe's own failure threshold do the smoothing.
**On a server started with `--auth-token-file`, the readiness probe needs the
token and the liveness probe does not.** `/healthz` is the one auth-exempt
route; `GET /v0/beads/ready` is not, so an unauthenticated readiness probe gets
a `401` — never a 503 — and a load balancer reading only the status class will
book a healthy server as permanently not-ready. Give the readiness probe an
`Authorization: Bearer` header, and alert on `event=auth_refused` with
`op=listReadyWork` as the signal that you forgot.
## Detecting a wedge
The failure mode to plan for is a database that stops answering while the
@ -296,7 +392,9 @@ Other events on the same stream:
| Event | When |
|---|---|
| `startup` | Bound address, mode, workspace, database, host allowlist, capabilities. |
| `startup` | Bound address, mode, workspace, database, host allowlist, capabilities, and `auth` — `none`, or `bearer (<token file path>)`. Check `auth` after a deploy rather than inferring it from a process listing. |
| `auth_refused` | A `401`. Carries `request_id`, `op`, `remote_addr` and `reason` (`missing`, `malformed`, `unknown_token`). A burst of `unknown_token` from one peer is a client left on a rotated-out token; `missing` is a client that was never configured with one. |
| `auth_reload_error` | The token file could not be re-read. **Not** a refusal — the last-good set stays in force — but the file an operator is rotating is unreadable and nothing else says so. |
| `limits` | The operating envelope this build compiled in. Log it, then compare against this page. |
| `request_error` | Accompanies a ≥500, carrying the real error the body withholds. Join on `request_id`. Not emitted when the client hung up (see above). |
| `pool_limits_unavailable` | The unit-of-work provider does not expose the pool knob, so the limits below are *not* applied and the pool is unbounded. Worth alerting on; it changes the connection budget. |
@ -319,6 +417,19 @@ gives the shape, the `request_error` line gives the cause.
|---|---|
| `bd serve requires a Dolt SQL server; this workspace uses embedded Dolt` | Permanent. The embedded backend commits outside the SQL transaction on a separate connection, so this server's per-request atomicity would be a lie there. Refused by `serveDatabaseSource`, which is the only thing refusing it — see "Workspace modes" in the design doc. |
| `bd serve is unavailable under strict readonly` | `--readonly`, or `readonly` in config. Every server this command binds publishes the issue-claim operation and the advertised capability set is a property of the build, not of the flags on the process that started it — so the alternatives were a server advertising a claim it always fails (the store source, where the read-only open reaches the claimer) or a `--readonly` that quietly bought nothing (the provider source, which builds its own writable connection). Drop the flag to serve. |
| `host must be a numeric IP literal, not a name — use 127.0.0.1 rather than localhost` | `--addr` was given a DNS name. |
| `binds beyond loopback; bd serve has no authentication, so this requires --allow-non-loopback` | A non-loopback `--addr` without the flag. |
| `--addr "localhost:7777": host must be a numeric IP literal, not a name — use 127.0.0.1 rather than localhost` | `--addr` was given a DNS name. |
| `--addr "0.0.0.0:7777" binds beyond loopback, which requires --allow-non-loopback (and, with it, --auth-token-file)` | A non-loopback `--addr` without the flag. |
| `--allow-non-loopback requires --auth-token-file (or the explicit --insecure-no-auth): every peer that can reach the address gets full read and claim access` | Binding beyond loopback with no credential and no waiver. |
| `--insecure-no-auth applies only to a bind beyond loopback; on loopback there is nothing to waive, so pass --allow-non-loopback or drop the flag` | The waiver without the bind it waives. |
| `--insecure-no-auth contradicts --auth-token-file; pass one or the other` | Both spellings of the auth decision at once. |
| `--auth-token-file: token file <path>: open <path>: no such file or directory` | The token file is unreadable. Also `is a directory`, `contains no tokens`, and `is larger than 1048576 bytes; that is a mis-pointed path, not a token file`. All four are refusals at startup, never a server that binds anyway. |
| `address already in use` | The fixed-port mutual exclusion working as intended: a second server is already on that port. |
The five auth and bind refusals above are raised by `resolveServeConfig` before
serve opens its database source or listener, independent of the workspace, so
they read the same in every workspace mode. (The root command's
`PersistentPreRunE` still resolves the workspace first, so a directory with no
beads database answers `no beads database found` ahead of any of them.) And
`httpapi.Listen` re-checks the same rules, so a second caller of the package
cannot assemble a `Config` that serves the whole surface to a network with no
credential.

View file

@ -184,18 +184,36 @@ obligation instead of a hidden server-side reconciliation.
## The loopback posture
v0 has no authentication and no TLS. The trust model is the loopback boundary
— the same boundary the database behind it already relies on.
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, it prints a warning naming what it exposes, and nothing
else about the server changes. Every peer that can reach the address gets full
read and claim access.
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. An unauthenticated service on
**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
@ -225,8 +243,10 @@ 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, not authenticated identity — the same thing it has always been on the
CLI, where any local process can pass any `--actor`. The claim's
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.

View file

@ -153,8 +153,10 @@ var secretKeySegments = map[string]bool{
// `bd config set` guard that refuses to write a credential into a git-tracked
// file, and — since the settings surface went on the wire — the redaction in
// internal/httpapi that decides whether GET /v0/beads/config publishes a
// value. `bd serve` has no authentication, so a spelling missing from this
// predicate is a credential served in cleartext.
// value. Redaction is the whole control there: a `bd serve` bearer is optional
// and, where configured, shared and surface-wide, so it cannot withhold one
// value from one caller — and there is no TLS either. A spelling missing from
// this predicate is a credential served in cleartext.
//
// It errs toward over-redacting for that reason: a key wrongly withheld is an
// operator asking why, and a key wrongly published cannot be recalled. The

View file

@ -782,10 +782,11 @@ func TestIsSecretKey(t *testing.T) {
{"some.api-key", true},
// Spellings the wire redaction has to cover. GET /v0/beads/config
// publishes a value for any key this returns false for, and bd serve
// has no authentication, so each of these is a credential in cleartext
// if it regresses. "apikey" in particular is the spelling the
// published schema promises is covered.
// publishes a value for any key this returns false for, and bd serve's
// bearer — optional, and shared and surface-wide where it is
// configured — cannot withhold one value from one caller, so each of
// these is a credential in cleartext if it regresses. "apikey" in
// particular is the spelling the published schema promises is covered.
{"integrations.apikey", true},
{"github.pat", true},
{"github.auth", true},

View file

@ -1139,7 +1139,7 @@ type DeleteIssuesRequest struct {
// Force Delete the named beads and leave their dependents ORPHANED, reported in `orphaned`. Without it and without `cascade`, a named bead with a dependent the request did not name is refused.
//
// It defaults FALSE, which is the guarded mode, and the default is the protection: this surface has no authentication, so an omitted member must not silently choose the answer that changes another bead's graph.
// It defaults FALSE, which is the guarded mode, and the default is the protection. Authentication here is a deployment posture, and where it is configured it is a single shared bearer that admits a client to the WHOLE surface — it names no principal this operation could weigh and grants no narrower right — so an omitted member must not silently choose the answer that changes another bead's graph.
Force *bool `json:"force,omitempty"`
// Ids The beads to delete, exact ids, in either plane. DUPLICATES COLLAPSE. An empty array is a `400` rather than a no-op — a caller whose id list came out empty because its own construction broke would read "deleted 0" and conclude the workspace was already clean.
@ -1395,7 +1395,7 @@ type MemoriesPage struct {
//
// NOT `x-go-type`-PINNED, for the reason `Setting` is not: the CLI marshals an ad-hoc map per verb, so there is no canonical Go struct whose JSON encoding is this contract, and minting one to pin to would mean changing what `bd recall --json` prints in order to satisfy a rule about not changing it.
//
// IT HAS NO `redacted` MEMBER, and that is the deliberate difference from `Setting`. Redaction there is a decision about the KEY NAME, which works because settings keys are configured names; memory keys are derived from the content, so the same rule would withhold a memory about credentials and serve one containing a credential under an innocuous slug. This surface has no authentication and states the exposure rather than implying a protection it does not have.
// IT HAS NO `redacted` MEMBER, and that is the deliberate difference from `Setting`. Redaction there is a decision about the KEY NAME, which works because settings keys are configured names; memory keys are derived from the content, so the same rule would withhold a memory about credentials and serve one containing a credential under an innocuous slug. A configured bearer would not close that either — it admits a client to the whole surface rather than to particular keys — so this schema states the exposure rather than implying a protection it does not have.
type Memory struct {
// Key The memory's key, echoed verbatim.
Key string `json:"key"`
@ -1422,9 +1422,13 @@ type Problem struct {
// ActualVersion With `precondition_failed`: the `revision` the row was found holding, read inside the transaction that refused the guard.
//
// PRESENT ONLY WHERE THE REFUSING OPERATION CAN REPORT IT. An all-or-nothing operation rolls its transaction back, so a value read after the fact would describe a row the refusal never saw; where the role behind an operation does not carry the observed value, this member is omitted rather than reconstructed. Its absence therefore means "this server cannot tell you what it found", never "it found zero".
//
// NO v0 OPERATION EMITS IT TODAY, nor `actual_status` or `actual_assignee`. Every operation that publishes a guard refuses all-or-nothing, and none of the roles behind them carries the observed value out of the rolled-back transaction. The three members are declared so that an operation whose role CAN report what it found is an addition rather than a wire change — a client must not wait for them, and must never read their absence as a value.
ActualVersion *int64 `json:"actual_version,omitempty"`
// Assignee With `already_claimed`: the actor currently holding the issue.
// Assignee With `already_claimed`: the actor currently holding the issue, read inside the transaction that refused.
//
// IT IS OPTIONAL ON EVERY OPERATION BUT THE CLAIM. `POST /v0/beads/issues/{id}:claim` always carries it, because its conflict path reads the row it lost to. `PATCH /v0/beads/issues/{id}` and `POST /v0/beads/issues:batchApply` carry it only when the refusing transaction reported a holder, and `POST /v0/beads/issues/{id}:release` never does — the ownership fence refuses without naming anyone. An absent member means "this refusal could not name the holder", never "nobody holds it"; re-read the row.
Assignee *string `json:"assignee,omitempty"`
// BlockerId With `dependency_cycle`, hierarchy refusal only: the ancestor or descendant the edge named as blocker. See `issue_id`.
@ -1697,9 +1701,9 @@ type ReopenIssueResponse struct {
// Setting One entry of the workspace's stored settings plane.
//
// THIS SCHEMA IS DELIBERATELY NOT `x-go-type`-PINNED, and it is the only response component on this surface that is not. The seven pinned schemas above are pinned because a canonical Go struct already IS the contract — `types.Issue`'s JSON encoding is what `bd show --json` emits. A setting has no such struct: the CLI marshals an ad-hoc `map[string]string` per verb, so there is nothing to pin TO, and minting a type to pin to would mean changing what `bd config get --json` prints in order to satisfy a rule about not changing it.
// THIS SCHEMA IS DELIBERATELY NOT `x-go-type`-PINNED, and it is one of the two ROW schemas on this surface that is not — `Memory` is the other. (Envelopes and page wrappers are unpinned as a class, for a different reason: they are new wire surface with no prior implementation. `TestWireTagBijection`'s `pinnedSchemas` is the authority on what is pinned.) The thirteen pinned schemas above are pinned because a canonical Go struct already IS the contract — `types.Issue`'s JSON encoding is what `bd show --json` emits. A setting has no such struct: the CLI marshals an ad-hoc `map[string]string` per verb, so there is nothing to pin TO, and minting a type to pin to would mean changing what `bd config get --json` prints in order to satisfy a rule about not changing it.
//
// The two surfaces are still one shape where they overlap — `key` and `value` are spelled as the CLI spells them — and they diverge in exactly one deliberate place, `redacted`, which exists because this surface has no authentication and the CLI requires access to the database anyway.
// The two surfaces are still one shape where they overlap — `key` and `value` are spelled as the CLI spells them — and they diverge in exactly one deliberate place, `redacted`, which exists because a bearer on this surface is optional, shared and surface-wide — it cannot decide that one caller may read a credential and another may not — while the CLI requires access to the database anyway.
type Setting struct {
// Key The setting's key, echoed verbatim.
Key string `json:"key"`
@ -1763,7 +1767,7 @@ type SweepRequest struct {
// ProtectReferenced Skip candidates whose id is CITED — as a literal, at word boundaries — in the description, notes or comments of any bead that is not done, so a decision trail a live bead still points at is not deleted out from under it.
//
// It DEFAULTS ON here, unlike the library default, and that is deliberate. This surface has no authentication and this is its only destructive operation, so a caller that omits the member must not get weaker protection than the operator typing `bd prune`, which protects unless `--ignore-references`. The inverse — opt OUT locally, opt IN remotely — is the shape that lets a stray request delete a decision trail nothing brings back.
// It DEFAULTS ON here, unlike the library default, and that is deliberate. This is the only destructive operation on the surface, and the bearer a deployment may configure is not a per-caller right: one shared token admits a client to everything published here, so being authenticated says nothing about whether this particular deletion was meant. A caller that omits the member must therefore not get weaker protection than the operator typing `bd prune`, which protects unless `--ignore-references`. The inverse — opt OUT locally, opt IN remotely — is the shape that lets a stray request delete a decision trail nothing brings back.
//
// It costs a full scan of the not-done set and its comments. Sending `protect_referenced: false` buys the cheaper sweep, and asking for it explicitly is the point: that is the request that should be the deliberate one.
ProtectReferenced *bool `json:"protect_referenced,omitempty"`

View file

@ -46,13 +46,17 @@ const (
// caller-named actor, and the write whose posture every later one adopted.
//
// ACTOR SEMANTICS, stated because adopting this endpoint depends on them. The
// actor is caller-ASSERTED provenance for the audit trail, not authenticated
// identity: this API has no authentication, so any client can claim as any
// name, exactly as any local process can pass any --actor to the CLI. The CAS
// 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. The
// loopback-only bind is what bounds the blast radius of that posture.
// actor is caller-ASSERTED provenance for the audit trail and is NOT the
// authenticated principal, even where a bearer is required: the token a
// deployment configures is shared and surface-wide, so it names nobody and
// cannot confirm or contradict the actor a request sends. Any client that
// reaches this endpoint can claim as any name, exactly as any local process
// can pass any --actor to the CLI. The CAS 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. What bounds the blast radius of that posture is
// the bind: loopback by default, and beyond loopback only with a token file
// (or the explicit --insecure-no-auth).
//
// Two things a CLI claim does that this deliberately does not: hooks do not
// fire (a user-controlled subprocess per mutation is an unbounded latency

View file

@ -101,8 +101,10 @@ func (s *Server) addDependenciesRequest(w http.ResponseWriter, r *http.Request)
return issueops.AddDependenciesRequest{}, false
}
// SkipPerEdgeCycleCheck stays UNPUBLISHED and therefore false: it trades
// validation for speed on a trusted bulk path, and an unauthenticated HTTP
// surface is where a default must be the guarded one.
// validation for speed on a trusted bulk path, and this surface has no way
// to tell a trusted caller from any other — a configured bearer is shared
// and admits a client to the whole surface — so the default must be the
// guarded one.
return issueops.AddDependenciesRequest{Actor: actor, Edges: edges}, true
}

View file

@ -292,8 +292,8 @@ func TestAddDependenciesForwardsEveryEdgeInRequestOrder(t *testing.T) {
if !reflect.DeepEqual(calls[0], want) {
t.Errorf("request = %+v, want %+v", calls[0], want)
}
// SkipPerEdgeCycleCheck is not published, and an unauthenticated surface is
// where a default must be the guarded one.
// SkipPerEdgeCycleCheck is not published, and a surface that cannot tell a
// trusted caller from any other is where a default must be the guarded one.
if calls[0].SkipPerEdgeCycleCheck {
t.Error("the handler skipped the per-edge cycle check; that flag is unpublished on this surface")
}

View file

@ -54,9 +54,23 @@ const (
// not a client bug.
CodeInvalidCursor Code = "invalid_cursor"
CodeNotFound Code = "not_found"
// CodeAlreadyClaimed carries the holder in the `assignee` extension
// member, read inside the same transaction — never parsed out of the
// sentinel's message text.
// CodeAlreadyClaimed reports a live foreign holder. Where the `assignee`
// extension member is present it is the holder, read inside the same
// transaction and never parsed out of the sentinel's message text — but
// PRESENCE IS PER PRODUCER, and there are four:
//
// - claimIssue always attaches it: the claim's conflict path reads the
// row it lost to, so it has the holder in hand.
// - updateIssue and applyBatch attach it CONDITIONALLY, when the refusing
// error carried one. The assignee fence
// (AuthorizeAssigneeTransferWithPools) refuses without naming the
// holder, so an implementation that reported none leaves it absent.
// - releaseIssue NEVER attaches it. It is the same fence pointed the
// other way and it names nobody.
//
// A client therefore treats the member as optional on every operation but
// the claim, and re-reads the row when it is absent. Absence means "this
// refusal could not name the holder", never "nobody holds it".
CodeAlreadyClaimed Code = "already_claimed"
CodeNotClaimable Code = "not_claimable"
// CodeNotReleasable is a row refusing to give up a claim, and it covers

View file

@ -190,11 +190,14 @@ func TestHealthAndContextAnswerDespiteAWrongStamp(t *testing.T) {
}
// TestProjectStampRefusalDoesNotLeakThroughTheHostGate pins the ordering that
// scopes the disclosure. This surface has no authentication layer, so the
// earliest gate a request meets is the Host allowlist middleware, which runs
// before the mux dispatches to route() and therefore before the stamp is ever
// compared. A request that fails BOTH — a foreign Host and a wrong stamp — is
// answered by the Host gate, and that answer must not carry server_project_id.
// scopes the disclosure. On a server with no token file there is no
// authentication layer at all, so the earliest gate a request meets is the
// Host allowlist middleware, which runs before the mux dispatches to route()
// and therefore before the stamp is ever compared. With a token file the 401
// sits between the two — behind the Host gate, ahead of the stamp (route()) —
// so it only widens the guarantee this test pins. A request that fails BOTH —
// a foreign Host and a wrong stamp — is answered by the Host gate, and that
// answer must not carry server_project_id.
//
// It is the OSS analog of the auth-before-check ordering: server_project_id is
// added by exactly one constructor (ProjectMismatch), reached only after every

View file

@ -36,7 +36,9 @@ var releaseRequestMembers = []string{claimActorMember, releaseExpectedAssigneeMe
//
// THE ACTOR IS ALSO THE OWNERSHIP FENCE'S SUBJECT here, which it is on no other
// operation: a release carrying neither guard nor force succeeds only while the
// actor is the holder. That is not authorization — this surface has none — it
// actor is the holder. That is not authorization: the actor is not the
// authenticated principal even where a bearer is required, because the token a
// deployment configures is shared and admits a client to the whole surface. It
// is the anti-yank guard the claim gets from refusing a foreign holder, pointed
// the other way, and it is the role's rather than this handler's.
//

View file

@ -1350,15 +1350,22 @@ func TestConfiguredRolesServeTheSameReadyBytesAsAProvider(t *testing.T) {
// operations against a store-shaped source: none of them can reach a unit of
// work here, because there is no provider to open one.
//
// NOT ALL OF THEM, despite the name: the subtests below drive ten of the
// seventeen capability-bearing operations in routes.go. The other seven —
// dependencies/cycles, dependencies/blocking, dependencies/tree,
// issues:batchCreate, issues:sweep, issues:delete, issues/{id}:casMetadata and
// issues:batchApply — are exercised against a roles source in their own files
// (cycles_test.go, blocking_test.go, tree_test.go, batch_create_test.go,
// sweep_test.go, delete_test.go, metadata_cas_test.go, batch_apply_test.go).
// Either add the eight here or keep this
// paragraph accurate; do not generalize the sentence again.
// NOT ALL OF THEM, despite the name: the subtests below drive the ten
// operations whose roles this test configures — ready, ready:count,
// issues:query, issues, issues/{id}, issues/{id}:claim, config, config/{key},
// stats and dependencies. Every OTHER capability-bearing row in routeTable is
// driven against a roles source in its own file; grep `rolesConfig(` to find
// the one you want. The gap this test's name implies is a file boundary, not a
// coverage hole.
//
// AND NO TOTAL GOES HERE, deliberately. The sentence this replaces said "ten
// of the seventeen capability-bearing operations in routes.go" against a table
// that had already reached thirty-four, then thirty-six; it called the
// remainder "the other seven" and enumerated eight; and it closed by
// instructing the next reader to keep it accurate. A count of a table that
// grows every wire slice is the one thing a comment cannot hold. Keep the ten
// — they are this file's own subtests, and the compiler and the reader both
// see them — and do not generalize the sentence into "every database route".
func TestConfiguredRolesAnswerEveryDatabaseRoute(t *testing.T) {
details := &issueops.IssueDetails{Issue: *seededIssue("bd-1", "alice", types.StatusOpen)}
reader := &roleReader{page: issueops.IssuePage{Items: countedPage(), HasMore: true}, details: details}

View file

@ -62,19 +62,28 @@ info:
* **Unknown query parameter.** Every operation rejects any query parameter
outside its own parameter table with `400` / `code: invalid_argument` /
`reason: "unknown_parameter"` and `param` naming the offending key.
Operations with no parameters at all (`GET /healthz`,
`GET /v0/beads/context`, `GET /v0/beads/dependencies/cycles`,
Operations that declare no QUERY parameter at all reject every query key
the same way. Today that is twenty-two of the thirty-eight operations
here — `GET /healthz`, `GET /v0/beads/context`,
`GET /v0/beads/dependencies/cycles`, `POST /v0/beads/issues`,
`PATCH /v0/beads/issues/{id}`,
`POST /v0/beads/issues/{id}:claim`,
`POST /v0/beads/issues/{id}:release`,
`POST /v0/beads/issues/{id}:close`,
`POST /v0/beads/issues/{id}:reopen`,
`POST /v0/beads/issues/{id}:casMetadata`, `POST /v0/beads/issues:sweep`,
`POST /v0/beads/issues:delete`,
`POST /v0/beads/issues:batchCreate`,
`POST /v0/beads/issues:batchApply`,
`POST /v0/beads/issues:batchClose`, `GET /v0/beads/config`,
`GET /v0/beads/config/{key}`, `POST /v0/beads/dependencies:add`,
`POST /v0/beads/dependencies:remove`) reject every query key the same
way.
`POST /v0/beads/dependencies:remove`, `POST /v0/beads/memories`,
`GET /v0/beads/memories/{key}` and `DELETE /v0/beads/memories/{key}`.
A path parameter is not a query parameter: several of those carry
`{id}` or `{key}` and still take no query key. The authority is each
operation's own `parameters` table, which is what a generated client
reads; this list is a convenience and, being prose, is the half that can
go stale — six entries were missing from it before this revision.
* **Request media type.** Every operation that carries a request body
requires `Content-Type: application/json` and refuses anything else with
@ -186,6 +195,28 @@ info:
switch breaks on the first addition.
## An `operationId` is not derivable from its path
A custom method usually reads the same in both — `:claim` is `claimIssue`,
`:sweep` is `sweepIssues` — and TWO OPERATIONS INVERT IT. Neither is a
typo and neither will be renamed, because an `operationId` is a generated
client's method name and a path is wire surface, so both are one-way doors:
| Path | `operationId` | Capability token |
|---|---|---|
| `POST /v0/beads/issues:batchApply` | `applyBatch` | `issues.batchApply` |
| `POST /v0/beads/issues/{id}:casMetadata` | `compareAndSetMetadata` | `issues.casMetadata` |
The capability token follows the PATH in both cases, not the
`operationId`, so a client probing `capabilities` before calling a
generated method reads two different spellings of one operation. A spec
author adding an operation should spell them alike; a spec author touching
these two should leave both spellings exactly as they are.
## Schema evolution while `/v0` is the newest path version
@ -2113,8 +2144,10 @@ paths:
'409':
description: >-
The request is well-formed and the STATE refuses it, and NOTHING WAS
WRITTEN. Four codes, each inherited from the operation that already
publishes it rather than minted here.
WRITTEN. Five codes, each inherited from the operation that already
publishes it rather than minted here, and described in the four
paragraphs below — `dependency_cycle` and `dependency_exists` share
one, because they are one member reaching the graph.
`precondition_failed` is `expected_version`, `expected_status` or
@ -2408,10 +2441,13 @@ paths:
`POST /v0/beads/issues/{id}:claim`'s reason. HERE IT IS ALSO THE
OWNERSHIP FENCE'S SUBJECT: a release carrying neither
`expected_assignee` nor `force` succeeds only while `actor` is the
current holder. That is not authentication — this surface has none, and
`actor` is caller-asserted provenance exactly as it is on the claim —
it is the same anti-yank guard the claim gets from refusing a foreign
holder, pointed the other way.
current holder. That is not authentication — `actor` is caller-asserted
provenance exactly as it is on the claim, and it is NOT the
authenticated principal even where a bearer is required: the token a
deployment configures admits a client to the whole surface and names
nobody, so it can neither confirm nor contradict the name in `actor`.
The fence is the same anti-yank guard the claim gets from refusing a
foreign holder, pointed the other way.
## NOT IDEMPOTENT, which is the one thing to read before adopting it
@ -3572,8 +3608,10 @@ paths:
'409':
description: >-
The request is well-formed and the STATE refuses it, and NOTHING WAS
WRITTEN. Five codes, and every one of them is a statement a caller
could not have made without reading state it does not hold.
WRITTEN. Six codes, and every one of them is a statement a caller
could not have made without reading state it does not hold. Five
paragraphs cover them: `dependency_cycle` and `dependency_exists`
share one, because they are the graph's own pair.
`precondition_failed` is a guard that missed:
@ -4728,13 +4766,16 @@ paths:
answer.
MEMORY CONTENT IS SERVED IN FULL and this API has no authentication.
Every entry carries its value verbatim; there is no `redacted` member
and nothing is withheld. See `POST /v0/beads/memories` for why a
key-name heuristic would be worse here than no promise at all. This is
the operation that makes stored memories DISCOVERABLE rather than merely
readable by a caller who already knows a key — an operator binding
beyond loopback is accepting exactly that.
MEMORY CONTENT IS SERVED IN FULL, and authentication does not narrow
that. Every entry carries its value verbatim; there is no `redacted`
member and nothing is withheld. A bearer decides WHO may call, not what
a caller who is let in may read, so a token-protected server serves
every memory to every holder of the token. See
`POST /v0/beads/memories` for why a key-name heuristic would be worse
here than no promise at all. This is the operation that makes stored
memories DISCOVERABLE rather than merely readable by a caller who
already knows a key — an operator binding beyond loopback is accepting
exactly that for everyone the token admits.
A memory stored as the EMPTY STRING is enumerated here, because its key
@ -4821,7 +4862,8 @@ paths:
MEMORY CONTENT IS SERVED IN FULL, here and on every other operation of
this plane, and this API has no authentication. There is no `redacted`
this plane, and a bearer does not change that — it gates WHO may call,
never what a caller who is let in may read. There is no `redacted`
member and no value withholding: the settings surface's redaction is a
heuristic over the KEY NAME, and memory keys are derived from the
content, so the same rule would withhold a memory ABOUT tokens while
@ -4905,10 +4947,10 @@ paths:
one way a client can tell the two apart.
MEMORY CONTENT IS SERVED IN FULL and this API has no authentication:
`Memory` carries no `redacted` member and withholds nothing. See
`POST /v0/beads/memories` for why a key-name heuristic would be worse
than no promise at all.
MEMORY CONTENT IS SERVED IN FULL, and a configured bearer does not
narrow it: `Memory` carries no `redacted` member and withholds nothing
from any caller the token admits. See `POST /v0/beads/memories` for why
a key-name heuristic would be worse than no promise at all.
KEYS THIS OPERATION CANNOT REACH. `bd remember --key` accepts any
@ -5630,7 +5672,7 @@ components:
# ---------------------------------------------------------------------
# Pinned schemas.
#
# Each of the twelve below is `x-go-type`-pinned to the canonical Go struct,
# Each of the thirteen below is `x-go-type`-pinned to the canonical Go struct,
# so the generator emits a type ALIAS and no mirror struct exists anywhere.
# `types.Issue`'s JSON encoding IS this contract; the CLI's `--json`, the
# JSONL interchange and these bodies all marshal the same struct.
@ -5642,10 +5684,13 @@ components:
# added to the Go struct without an entry here fails CI, and an entry here
# with no Go field fails CI.
#
# Nine of the twelve are pinned to `internal/types`; `Cycle`, `CycleMember`
# and `IssueBlocking`, which appear after `BondRef`, are pinned to the role
# package `issueops` instead, because that is where those canonical structs
# live.
# Nine of the thirteen are pinned to `internal/types`. The other four are
# pinned where their canonical struct actually lives: `CycleMember`,
# `Cycle` and `IssueBlocking`, which appear after `Statistics`, to the role
# package `issueops`; `EventRecord`, last of the group, to
# `internal/eventsjournal`. TestWireTagBijection's `pinnedSchemas` table is
# the enumeration that is machine-checked; the counts here are prose and go
# stale in silence, so a schema added to that table updates them too.
# ---------------------------------------------------------------------
Issue:
@ -6556,9 +6601,16 @@ components:
`GET /v0/beads/dependencies`.
# ---------------------------------------------------------------------
# Envelope schemas. These have no canonical Go type behind them: they are
# new wire surface, generated normally, and the generated type is the only
# implementation — so there is nothing for them to drift against.
# Envelope schemas. Almost all of these have no canonical Go type behind
# them: they are new wire surface, generated normally, and the generated
# type is the only implementation — so there is nothing for them to drift
# against.
#
# `EventRecord`, further down this region, is the exception and is pinned
# to `eventsjournal.Record`: the journal's published envelope is shared with
# `bd events tail`, so it HAS a canonical implementation to drift against.
# TestWireTagBijection's `pinnedSchemas` is the authority on which schemas
# are pinned; do not read this region's position as the answer.
# ---------------------------------------------------------------------
Health:
@ -6803,9 +6855,12 @@ components:
It defaults FALSE, which is the guarded mode, and the default is
the protection: this surface has no authentication, so an omitted
member must not silently choose the answer that changes another
bead's graph.
the protection. Authentication here is a deployment posture, and
where it is configured it is a single shared bearer that admits a
client to the WHOLE surface — it names no principal this operation
could weigh and grants no narrower right — so an omitted member
must not silently choose the answer that changes another bead's
graph.
dry_run:
type: boolean
default: false
@ -6988,12 +7043,15 @@ components:
It DEFAULTS ON here, unlike the library default, and that is
deliberate. This surface has no authentication and this is its only
destructive operation, so a caller that omits the member must not
get weaker protection than the operator typing `bd prune`, which
protects unless `--ignore-references`. The inverse — opt OUT
locally, opt IN remotely — is the shape that lets a stray request
delete a decision trail nothing brings back.
deliberate. This is the only destructive operation on the surface,
and the bearer a deployment may configure is not a per-caller
right: one shared token admits a client to everything published
here, so being authenticated says nothing about whether this
particular deletion was meant. A caller that omits the member must
therefore not get weaker protection than the operator typing `bd
prune`, which protects unless `--ignore-references`. The inverse —
opt OUT locally, opt IN remotely — is the shape that lets a stray
request delete a decision trail nothing brings back.
It costs a full scan of the not-done set and its comments. Sending
@ -7332,11 +7390,15 @@ components:
One entry of the workspace's stored settings plane.
THIS SCHEMA IS DELIBERATELY NOT `x-go-type`-PINNED, and it is the only
response component on this surface that is not. The seven pinned
schemas above are pinned because a canonical Go struct already IS the
contract — `types.Issue`'s JSON encoding is what `bd show --json`
emits. A setting has no such struct: the CLI marshals an ad-hoc
THIS SCHEMA IS DELIBERATELY NOT `x-go-type`-PINNED, and it is one of
the two ROW schemas on this surface that is not — `Memory` is the
other. (Envelopes and page wrappers are unpinned as a class, for a
different reason: they are new wire surface with no prior
implementation. `TestWireTagBijection`'s `pinnedSchemas` is the
authority on what is pinned.) The thirteen pinned schemas above are
pinned because a canonical Go struct already IS the contract —
`types.Issue`'s JSON encoding is what `bd show --json` emits. A setting
has no such struct: the CLI marshals an ad-hoc
`map[string]string` per verb, so there is nothing to pin TO, and
minting a type to pin to would mean changing what `bd config get
--json` prints in order to satisfy a rule about not changing it.
@ -7344,9 +7406,10 @@ components:
The two surfaces are still one shape where they overlap — `key` and
`value` are spelled as the CLI spells them — and they diverge in
exactly one deliberate place, `redacted`, which exists because this
surface has no authentication and the CLI requires access to the
database anyway.
exactly one deliberate place, `redacted`, which exists because a bearer
on this surface is optional, shared and surface-wide — it cannot decide
that one caller may read a credential and another may not — while the
CLI requires access to the database anyway.
required: [key, redacted]
properties:
key:
@ -7400,9 +7463,10 @@ components:
`Setting`. Redaction there is a decision about the KEY NAME, which works
because settings keys are configured names; memory keys are derived from
the content, so the same rule would withhold a memory about credentials
and serve one containing a credential under an innocuous slug. This
surface has no authentication and states the exposure rather than
implying a protection it does not have.
and serve one containing a credential under an innocuous slug. A
configured bearer would not close that either — it admits a client to
the whole surface rather than to particular keys — so this schema
states the exposure rather than implying a protection it does not have.
properties:
key:
type: string
@ -10145,7 +10209,19 @@ components:
assignee:
type: string
description: >-
With `already_claimed`: the actor currently holding the issue.
With `already_claimed`: the actor currently holding the issue, read
inside the transaction that refused.
IT IS OPTIONAL ON EVERY OPERATION BUT THE CLAIM. `POST
/v0/beads/issues/{id}:claim` always carries it, because its
conflict path reads the row it lost to. `PATCH
/v0/beads/issues/{id}` and `POST /v0/beads/issues:batchApply` carry
it only when the refusing transaction reported a holder, and `POST
/v0/beads/issues/{id}:release` never does — the ownership fence
refuses without naming anyone. An absent member means "this refusal
could not name the holder", never "nobody holds it"; re-read the
row.
issue_status:
type: string
description: >-
@ -10229,6 +10305,16 @@ components:
member is omitted rather than reconstructed. Its absence therefore
means "this server cannot tell you what it found", never "it found
zero".
NO v0 OPERATION EMITS IT TODAY, nor `actual_status` or
`actual_assignee`. Every operation that publishes a guard refuses
all-or-nothing, and none of the roles behind them carries the
observed value out of the rolled-back transaction. The three
members are declared so that an operation whose role CAN report
what it found is an addition rather than a wire change — a client
must not wait for them, and must never read their absence as a
value.
expected_status:
type: string
description: >-

View file

@ -116,12 +116,14 @@ func (s *Server) sweepRequest(w http.ResponseWriter, r *http.Request) (issueops.
// protect_referenced DEFAULTS ON over HTTP, and the default is set here
// rather than left to the zero value on purpose.
//
// This surface has no authentication, and this is the only destructive
// operation on it. A remote caller that omits the member must not get
// weaker protection than the operator typing `bd prune`, which protects
// unless --ignore-references is passed. Leaving the zero value would have
// inverted exactly that: locally you opt OUT of protection, remotely you
// had to opt IN.
// This is the only destructive operation on the surface, and a configured
// bearer is not a per-caller right: one shared token admits a client to
// everything published here, so being authenticated says nothing about
// whether this particular deletion was meant. A remote caller that omits
// the member must not get weaker protection than the operator typing `bd
// prune`, which protects unless --ignore-references is passed. Leaving the
// zero value would have inverted exactly that: locally you opt OUT of
// protection, remotely you had to opt IN.
//
// The cost is a full scan of the not-done set and its comments. A caller
// that wants the cheaper sweep asks for it by sending

View file

@ -108,8 +108,9 @@ func TestSweepDefaultsTheOptionalMembers(t *testing.T) {
}
// protect_referenced ABSENT means TRUE on this surface, which is the one
// default here that deliberately differs from the role's zero value. The
// endpoint is unauthenticated and destructive, so an omitted member must
// not buy weaker protection than `bd prune` gives by default.
// endpoint is destructive and its optional bearer is shared and
// surface-wide, so an omitted member must not buy weaker protection than
// `bd prune` gives by default.
want := issueops.SweepRequest{Tier: issueops.SweepEphemeral, ProtectReferenced: true}
if reqs[0] != want {
t.Errorf("request = %+v, want %+v", reqs[0], want)

View file

@ -68,9 +68,11 @@ func roleAccessorNamesOf(surface reflect.Type) (names, unclassified []string) {
}
// TestEveryStoreRoleAccessorIsClassified fails when DoltStorage hands out an
// interface the census cannot place. Every one of the twenty-seven today is a
// interface the census cannot place. Every one of the twenty-eight today is a
// facade role, so this costs nothing and closes the path where a role surface
// grows a package and the census quietly stops covering it.
// grows a package and the census quietly stops covering it. (roleAccessorNames
// is derived, so the count is prose and only this sentence goes stale — but it
// does go stale, and the last three sweeps found it saying twenty-seven.)
func TestEveryStoreRoleAccessorIsClassified(t *testing.T) {
_, unclassified := roleAccessorNamesOf(reflect.TypeOf((*DoltStorage)(nil)).Elem())
for _, accessor := range unclassified {
@ -148,9 +150,9 @@ func assertRoleAccessorsAreDeclared(t *testing.T, decorator reflect.Type) {
}
}
// roleAccessorStore is a DoltStorage whose only real methods are the twenty-seven
// role accessors, each answering with a distinguishable sentinel so a test can
// tell a decorated surface from a passed-through one.
// roleAccessorStore is a DoltStorage whose only real methods are the
// twenty-eight role accessors, each answering with a distinguishable sentinel
// so a test can tell a decorated surface from a passed-through one.
type roleAccessorStore struct {
DoltStorage
lifecycle issueops.Lifecycle
@ -280,7 +282,9 @@ func (s *roleAccessorStore) Releaser() (issueops.Releaser, error) {
return s.releaser, s.err
}
// roleAccessorSentinel implements twenty-six of the twenty-seven roles at once.
// roleAccessorSentinel implements twenty-seven of the twenty-eight roles at
// once — every one but memoryops.Memories, whose List collides with
// issueops.Reader.List and needs the second sentinel below.
// Nothing calls its methods; identity is the whole point.
type roleAccessorSentinel struct{}

View file

@ -92,9 +92,9 @@ func TestInstrumentedStorageDeclaresEveryRoleAccessor(t *testing.T) {
}
}
// roleAccessorStore is a DoltStorage whose only real methods are the twenty-seven
// role accessors, each answering with a distinguishable sentinel so a test can tell
// an instrumented surface from a passed-through one.
// roleAccessorStore is a DoltStorage whose only real methods are the
// twenty-eight role accessors, each answering with a distinguishable sentinel
// so a test can tell an instrumented surface from a passed-through one.
//
// TWO sentinels rather than one: memoryops.Memories.List and issueops.Reader.List
// are the same method name with different signatures, so no single Go type can
@ -172,7 +172,9 @@ func (s *roleAccessorStore) Releaser() (issueops.Releaser, error) {
return s.surface, s.err
}
// roleAccessorSentinel implements twenty-six of the twenty-seven roles at once.
// roleAccessorSentinel implements twenty-seven of the twenty-eight roles at
// once — every one but memoryops.Memories, whose List collides with
// issueops.Reader.List and needs the second sentinel below.
// Nothing calls its methods; identity is the whole point.
type roleAccessorSentinel struct{}

View file

@ -72,8 +72,9 @@ func ValidateSettingWrite(key, value string) (string, error) {
// keys and the `bd remember` memories nested under them are USER DATA stored as
// config rows beneath kvkeys.Prefix, and an enumeration that returned them
// published that data on `bd config list` and on GET /v0/beads/config alike —
// the latter unauthenticated, and redacting on the KEY NAME while a memory's
// content is in the VALUE. `bd config list` carrying kv rows was never a
// the latter reachable by anything a shared bearer admits, if one is
// configured at all, and redacting on the KEY NAME while a memory's content is
// in the VALUE. `bd config list` carrying kv rows was never a
// design; it fell out of one storage table holding two planes.
//
// THE WHOLE PREFIX GOES, not just kv.memory.: "settings minus one user-data

View file

@ -81,7 +81,8 @@ type EdgeCountRequest struct {
// bound belongs to the WIRE operation, where the request arrives from
// somewhere else and the cost of an unbounded one is a stranger's — the
// split ApplyBatchRequest.Items makes explicitly by bounding at 100. The
// graph-counts wire slice sets it.
// graph-counts wire slice set it: GET /v0/beads/dependencies:count bounds
// `issue_id` at minItems 1, maxItems 100.
IDs []string
// Direction is which edges the count is over, and it is REQUIRED. An empty
@ -250,16 +251,21 @@ type EdgeCountResult struct {
// Deterministic request-validation failures match ErrValidation; result values
// are unspecified when error is non-nil.
//
// THERE IS NO CLI FRONT DOOR IN THE SLICE THAT INTRODUCED THIS ROLE, and no
// HTTP operation either. That is written down here rather than left to be
// inferred, the way VersionReconciler writes down its absent HTTP half and
// BatchApplier its absent CLI. The numbers this role answers are already
// printed by `bd show`, which reads them through internal/workapi's detail
// seam — a seam shared with an HTTP handler, so moving it is its own change
// with its own parity argument — and the wire operation that publishes them
// lands in the graph-counts wire slice. What this slice buys is the facade: one
// place where the direction, the plane span, the missing-anchor rule and the
// status asymmetry are stated once and held to on three legs.
// THERE WAS NO FRONT DOOR AT ALL IN THE SLICE THAT INTRODUCED THIS ROLE,
// neither CLI nor HTTP, and that was written down here rather than left to be
// inferred — the way VersionReconciler writes down its absent HTTP half and
// BatchApplier its absent CLI. What a facade-only slice buys is ONE place where
// the direction, the plane span, the missing-anchor rule and the status
// asymmetry are stated and held to on three legs, before either surface has to
// agree with the other.
//
// THE HTTP HALF HAS SINCE LANDED: GET /v0/beads/dependencies:count publishes
// this role's whole filter surface, and the anchor bound this request
// deliberately leaves to the wire is set there. THE CLI HALF STILL HAS NOT, and
// that is still a decision rather than a gap: the numbers this role answers are
// already printed by `bd show`, which reads them through internal/workapi's
// detail seam — a seam shared with an HTTP handler, so moving it is its own
// change with its own parity argument.
type GraphCounter interface {
// CountEdges returns each anchor's edge cardinality in the requested
// direction.

View file

@ -255,6 +255,29 @@ type UpdateRequest struct {
// It is the update-side spelling of CloseRequest.Force; a command adapter
// that maps one flag to both spells both.
ForceClosePolicy bool
// The three Expected* guards below are this package's FOUNDING spelling of
// the compare-and-set family, and the family's rules are stated once, at
// length, on DeleteRequest.ExpectedVersion (deleter.go) and
// ApplyUpdateItem's guards (batchapplier.go). They hold here unchanged and
// are not restated:
//
// - THE TOKEN IS OPAQUE AND COMPARED FOR EQUALITY ONLY. RowVersion is
// minted afresh on every lifecycle write rather than incremented, so
// "newer" and "older" are not questions a version guard can answer.
// - IT GUARDS THE ROW'S LIFECYCLE STATE, NOT ITS GRAPH. RowVersion is
// reminted by status, assignee and started_at writes and deliberately
// not by label, dependency, rename or is_blocked writes, so a matching
// token does not promise the row's edges are the ones the caller saw.
// - nil DISABLES THE CHECK. Each is a pointer so that "do not check" is
// distinct from a caller requiring the never-written version 0, or the
// empty assignee, which is a real guard meaning "expected unassigned".
// - GUARDS PRESENT TOGETHER MUST ALL HOLD, and each is read inside the
// writing transaction, so there is no internal TOCTOU.
// - A MISS REFUSES AND WRITES NOTHING, with the typed sentinel for the
// guard that missed: ErrVersionMismatch, ErrStatusMismatch,
// ErrAssigneeMismatch. That is the opposite of MetadataCAS, whose miss
// is a result rather than an error; metadatacas.go states why.
//
// ExpectedVersion requires the current row version to match before the claim
// and patch. It is an independent precondition and may be combined with Claim.
ExpectedVersion *int64
@ -262,6 +285,10 @@ type UpdateRequest struct {
// the requested Patch.Assignee transfer: this compare-and-set replaces the
// ordinary anti-steal fence. It must be nil with Claim, and
// ForceAssigneeTransfer must be false when it is non-nil.
//
// THE COMPARISON IS SEPARATOR-INSENSITIVE, exactly as
// ReleaseRequest.ExpectedAssignee documents: a run of ".", "_" or "-"
// matches any other such run, and nothing else is forgiven.
ExpectedAssignee *string
// ExpectedStatus requires the current status to match. It must be nil when
// Claim is true.
@ -310,8 +337,17 @@ type CloseRequest struct {
// Force bypasses only blocker and open-child close policy. It never bypasses
// validation, ExpectedVersion, or lifecycle rules.
Force bool
// ExpectedVersion requires the current row version to match and is checked
// before an idempotent close.
// ExpectedVersion requires the current row version to match, and is checked
// BEFORE the idempotent close — so a re-close of an already-closed issue
// still refuses on a stale token rather than reporting the no-op it would
// otherwise be. That ordering is the whole difference from composing a read
// with a close, and a conformance case pins it.
//
// The rest of the family's rules are UpdateRequest.ExpectedVersion's,
// unchanged: the token is opaque and compared for equality only, it guards
// the row's lifecycle state and not its graph, nil disables the check, and
// a miss refuses with ErrVersionMismatch having written nothing. Force
// bypasses close policy and never this guard.
ExpectedVersion *int64
}

View file

@ -176,9 +176,21 @@ type MetadataCAS interface {
// that; a role's caller here is a retry loop, for which a lost race is the
// ordinary path and an error is the wrong shape for it — and an error
// cannot hand back Current without a bespoke type every caller must
// errors.As before it can read the one field it needs. A FRONT DOOR STILL
// OWES THE LOUD REFUSAL: a CLI or HTTP surface over this role reports a
// false Swapped as a failed precondition, never as success.
// errors.As before it can read the one field it needs.
//
// A FRONT DOOR OWES THE CALLER AN UNMISTAKABLE ANSWER, WHICH IS NOT THE
// SAME AS AN ERROR, and the shipped HTTP spelling is the worked example:
// POST /v0/beads/issues/{id}:casMetadata answers a refused swap with 200
// and `swapped: false` beside `current`, and publishes NO 409 at all,
// because a conflict code would put a retry loop's ordinary iteration into
// the error channel and force the value that loop needs next to travel as
// a problem extension member. What a front door must never do is let a
// false Swapped read as a landed write: `swapped` is the member a client
// dispatches on, and a surface that reported only the status would be
// telling a caller its swap succeeded. A front door whose contract is an
// EXIT CODE — a shell script's, where a swallowed refusal is the hazard
// this role's sibling guards raise ErrAssigneeMismatch for — owes a
// non-zero exit instead, for the same reason spelled in its own vocabulary.
//
// REFUSALS, all before anything is written:
//

View file

@ -25,6 +25,7 @@ DOCS=(
"docs/reference/json-schema.md|cmd/bd/output.go;cmd/bd/errors.go;cmd/bd/protocol/json_contract_test.go"
"docs/recovery/init-safety.md|cmd/bd/init.go;cmd/bd/init_safety.go;cmd/bd/init_safety_test.go"
"engdocs/ERROR_HANDLING.md|cmd/bd/*.go;cmd/bd/errors.go"
"engdocs/SERVE_RUNBOOK.md|internal/httpapi/server.go;internal/httpapi/events_watch.go;cmd/bd/serve.go;internal/httpapi/auth.go"
"engdocs/LINTING.md|.golangci.yml;scripts/ci/pr-lint.sh;Makefile;.github/workflows/pr.yml;.github/workflows/main.yml"
"engdocs/CI_CLEANUP_PLAN.md|engdocs/CI_TEST_SURFACE_AUDIT.md;.github/workflows/*.yml;.buildflags;.golangci.yml;scripts/ci/pr-lint.sh;Makefile"
"engdocs/design/otel/otel-data-model.md|internal/telemetry/;internal/storage/dolt/store.go;internal/compact/haiku.go;cmd/bd/find_duplicates.go;internal/hooks/"

View file

@ -22,6 +22,7 @@ var freshnessDocuments = []struct {
{"docs/reference/json-schema.md", []string{"cmd/bd/output.go", "cmd/bd/errors.go", "cmd/bd/protocol/json_contract_test.go"}},
{"docs/recovery/init-safety.md", []string{"cmd/bd/init.go", "cmd/bd/init_safety.go", "cmd/bd/init_safety_test.go"}},
{"engdocs/ERROR_HANDLING.md", []string{"cmd/bd/*.go", "cmd/bd/errors.go"}},
{"engdocs/SERVE_RUNBOOK.md", []string{"internal/httpapi/server.go", "internal/httpapi/events_watch.go", "cmd/bd/serve.go", "internal/httpapi/auth.go"}},
{"engdocs/LINTING.md", []string{".golangci.yml", "scripts/ci/pr-lint.sh", "Makefile", ".github/workflows/pr.yml", ".github/workflows/main.yml"}},
{"engdocs/CI_CLEANUP_PLAN.md", []string{"engdocs/CI_TEST_SURFACE_AUDIT.md", ".github/workflows/*.yml", ".buildflags", ".golangci.yml", "scripts/ci/pr-lint.sh", "Makefile"}},
{"engdocs/design/otel/otel-data-model.md", []string{"internal/telemetry/", "internal/storage/dolt/store.go", "internal/compact/haiku.go", "cmd/bd/find_duplicates.go", "internal/hooks/"}},