Commit graph

3 commits

Author SHA1 Message Date
Julian Knutsen
ff75b45c91
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.
2026-08-10 08:05:07 -07:00
CI Bot
4bf7b4baba feat(httpapi): publish addDependencies on the v0 surface
Completes the graph write side: a batch of edges asserted as ONE
transaction, or none of them, over issueops.DependencyEditor.

All-or-nothing is the role's shape rather than a policy choice here.
Edges asserted together describe a graph, and half a graph is a graph
nobody asked for — the cycle a caller was refused for is exactly the
state a partial commit would leave behind. That is batchCreateIssues'
posture (fix the payload, resend unchanged), not BatchCloser's
keep-the-survivors one, and it is proved where a fake role cannot prove
it: a batch whose later edge closes a cycle is read back through a real
`bd serve` against real Dolt and leaves zero edges.

Two frozen codes, both 409, both statements about state the client
cannot see without reading it — the claim's not_claimable situation, so
the claim's answer:

  dependency_cycle covers BOTH never-makes-progress refusals, the plain
  scheduling cycle and the blocking edge against the issue's own
  ancestor or descendant. One code because they have one client
  recovery and no force bypass, and codes are the vocabulary of
  recovery. The typed distinction is not lost: the hierarchy refusal
  additionally carries issue_id, blocker_id and blocker_is_ancestor,
  read from *DependencyHierarchyConflictError inside the refusing
  transaction, and member PRESENCE is the discriminator. The three are
  enough to rebuild the typed error whole, both polarities included,
  which is why the boolean travels through a pointer and is emitted
  when false. Nothing can recover them after the fact — the conflicting
  hierarchy may exist only inside the batch that was rolled back.

  dependency_exists is a pair carrying another type, with
  existing_type and requested_type from
  *DependencyTypeConflictError's fields.

The endpoint refusals PR #5415 typed are mapped to their 400 and named
by finding the refused edge in the request by BOTH endpoints, which is
what DependencyEndpointNotFoundError carries the whole edge for. A
target may legitimately be an `external:` reference or another
repository's id, so only a locally-visible absence refuses; the proxied
test pins both sides of that line.

A self-dependency is refused at the wire edge as a value, not a
conflict: it is invalid whatever the graph holds, and answering it here
is what lets the refusal name the offending edge.
SkipPerEdgeCycleCheck stays unpublished — an unauthenticated surface is
where a default must be the guarded one.

Co-Authored-By: Claude Fable <noreply@anthropic.com>
2026-08-08 00:19:48 +00:00
CI Bot
63b74e26ca feat(httpapi): publish removeDependency on the v0 surface
The dependency graph has been read-only over HTTP: a client could list
edges, walk the tree and find cycles, but had to fork `bd dep remove` to
unwire one. This adds the first graph WRITE, a thin adapter over
issueops.DependencyEditor.remove.

POST /v0/beads/dependencies:remove is a collection-level custom method
rather than a DELETE. An edge is named by TWO endpoints, so there is no
single-segment resource path for a DELETE to mean, and a DELETE carrying
a body is the shape proxies mangle; the forgetMemory precedent cuts the
other way because that one names a single resource and carries no body.

The operation is idempotent and its code set has NO 404, deliberately.
An edge that is not there is `removed: false` inside a 200, and an
endpoint id that names nothing holds no edge either, so this operation
probes no id's existence and has nothing it could report a miss on. An
agent replaying its own teardown must not have to classify an error to
discover it already ran.

The role reaches the server the way every other one does: a required
Config field, an accessor built OVER the timing wrapper on the provider
path, and a serveIssueRoles binding off the peeled store. That peel is
load-bearing here — HookFiringStore.DependencyEditor recurses and fires
the workspace's update hook per edited source — so RoleFiresHooks learns
the type, and Listen refuses a hook-firing editor rather than trusting
the comment that says not to pass one.

TestServeIssueRolesComeFromBeneathTheHookDecorator grows the editor the
way it already carries the reader and the claimer: an identifiable value
per layer, a precondition that the decorator's own accessor answers
RoleFiresHooks true, and a post-peel assertion that the role is the
middle store's own. Without the precondition the peel assertion would
pass on a predicate that answers false for everything, which is what
holds the new RoleFiresHooks case in place — a comment cannot.

The actor decode was the third copy of the same eighteen lines, so it is
now one shared requiredActorMember and the claim and batch-create paths
call it.

Co-Authored-By: Claude Fable <noreply@anthropic.com>
2026-08-08 00:19:48 +00:00