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:
parent
8ac3e6ea04
commit
ff75b45c91
27 changed files with 766 additions and 186 deletions
145
CHANGELOG.md
145
CHANGELOG.md
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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},
|
||||
|
|
|
|||
|
|
@ -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"`
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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")
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
//
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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: >-
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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{}
|
||||
|
||||
|
|
|
|||
|
|
@ -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{}
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
//
|
||||
|
|
|
|||
|
|
@ -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/"
|
||||
|
|
|
|||
|
|
@ -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/"}},
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue