Re-cut of the burned v1.2.0: that tag failed pre-publish in goreleaser on
the freebsd cross-compile break (no artifacts were published), and a
burned tag is never reused (v1.1.1 precedent), so the same content ships
as 1.2.1 with the fix (#5661) included. The [1.2.0] changelog section is
renamed to [1.2.1] with a note; versionChanges rides along. Also the
first bump to regenerate the tracked .githooks markers via the previous
commit's update-versions.sh fix, clearing the main-red from fa3d8cc5c.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Cuts the [Unreleased] changelog (1,223 commits since the v1.1.2 hotfix,
mainline's first release since v1.1.0) as 1.2.0. Headliners in
versionChanges: migration 0062 (events -> dolt_ignored, one-time
self-committing flip), bd sync, --brief listings, defer auto-wake,
telemetry startup + eventsData bounding. Includes the uv.lock refresh
(the v1.1.1 lesson: the MCP gate must never meet a stale lock after the
tag exists).
Resolve user config candidates through a shared absolute-native-path gate, preserve precedence, and keep display fallbacks out of filesystem operations. Add focused and native Windows process coverage for unsafe profile environments.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
Worktree operations use only Git and filesystem state. Mark the parent as store-free and lock the inherited command inventory with an absent-store behavioral guard.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
Measure GC before/after bytes through ActiveDatabaseSizer so sibling databases cannot distort reclaimed-space reporting. Keep unavailable measurements best-effort and omit them from JSON.
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
doltServerConfig() copied ServerHost, ServerPort and ServerUser out of
metadata.json but left ServerTLS and ServerPassword at their zero values.
Every federation check therefore dialled the configured Dolt server in
plaintext and unauthenticated, so a server with require_secure_transport
rejected all four of them:
failed to check if database "x" exists on server host:3307:
Error 1105 (HY000): unknown error: Code: UNAVAILABLE
server does not allow insecure connections, client must use SSL/TLS
The two sibling open paths already do this correctly, which is why normal
CRUD and the non-federation doctor checks work against the same server:
- internal/storage/dolt/open.go (applyResolvedConfig) sets both
- cmd/bd/doctor/dolt.go (openDoltDB) builds a ServerDSN with
TLS: cfg.GetDoltServerTLS() and the port-keyed password
Verified against a remote TLS-only Dolt server (dolt_server_tls: true,
password in ~/.config/beads/credentials): FEDERATION goes from 2/6 to 5/6
passing, and the remaining warning is an unrelated local-server one.
Peer Connectivity, Sync Staleness, Federation Conflicts and Dolt Mode all
connect instead of erroring.
Signed-off-by: Ary Rabelo <aryrabelo@gmail.com>
Select timeout or gtimeout only after a successful GNU coreutils identity probe, validate BEADS_HOOK_TIMEOUT as positive whole seconds, and preserve the Perl and warned direct fallbacks under inherited shell options.
Keep GNU and Perl deadlines soft and backend-scoped, preserve natural status 137, regenerate every tracked hook artifact, and exercise the real process boundary through the required three-host preflight.
Fixes#5503
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
Every other free-text field on an issue — description, design, notes,
acceptance criteria, comments — reaches the terminal through
uimd.RenderMarkdown, which word wraps at the terminal width and indents
two spaces. The close reason did not. It was formatted straight into the
metadata block beside Owner: and Created:, so it never wrapped, never
indented, and was never rendered.
For `Close reason: Closed` that is correct and this change keeps it. But
`bd close --reason-file` exists so agents can write structured multi-
paragraph close reports, and those came out corrupted rather than merely
ugly: the reason's second and later lines land in the metadata block as
peers of the metadata lines, so a blank line and a bare "- bullet one"
read as separate metadata entries directly under Created:.
So the rule is now the one the metadata block always implied — a
metadata line holds a one-liner. A reason that still contains a newline
once trimmed, or that is wider than the renderer's own wrap width, is
body text and gets a CLOSE REASON section rendered by the same call
every other body field makes. Short reasons, which is nearly all of
them, are untouched.
Not changed: bd close still echoes the whole reason on its success line.
A long reason-file dumps itself back at you there, but nothing follows
it on screen, so it is cosmetic rather than corrupting.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* Publish PUT and DELETE /v0/beads/config/{key}, the write half of issueops.WorkspaceConfig (ga-098zm)
Settings are read-only over v0: `WorkspaceConfig.SetSetting` and `UnsetSetting`
have no wire operation, which leaves the infra-over-http surface able to see that
a workspace is configured and unable to configure it. These are those operations.
The role, its contract and all three legs already exist; this slice wires them.
Spec first, then `make api-gen`, then the handlers.
PUT AND DELETE ON THE KEY'S OWN PATH, and the methods ARE the argument rather
than a preference. The resource has a canonical URI, the caller names it, and the
request carries the value that becomes its whole state — that is what PUT already
means, and the write is idempotent in the strict sense. `POST /v0/beads/memories`
is the operation this is deliberately NOT: that one posts to the COLLECTION
because its key may be derived from the content, so the caller cannot always name
the resource it is creating. Here it always can. The removal is
`DELETE /v0/beads/memories/{key}`'s shape unchanged — one named resource, no body,
no flags — and all three rows share one pattern, differing only in method, which
ServeMux registers together.
THE KEY IS THE PATH'S AND APPEARS NOWHERE IN THE BODY, so `SetSettingRequest`
carries exactly one member. A body spelling the anchor a second time is one
request with two anchors and a question about what to do when they disagree; the
parity test asserts the absence from both sides.
## The redaction doctrine, and what the write half owes it
A KEY WHOSE NAME MARKS IT CREDENTIAL-BEARING IS WRITABLE, resolved from the
facade's actual behavior rather than from the shape of the read. `ValidateSettingWrite`
refuses an empty key, `issue_prefix` in either spelling, and a `status.custom`
that does not parse — and nothing else; `config.IsSecretKey` appears nowhere in
the write path. The CLI's own secret guard is `CheckSecretKeyGitSafety`, which is
gated on `IsYamlOnlyKey` and protects a git-tracked **config.yaml** — a different
plane with a different hazard, a credential in git history — and returns clean for
every key this operation reaches. The role states the asymmetry itself: the reads
are a firewall, the writes are not, and a write discloses nothing. Refusing here
would be a refusal the role does not have, invented by the projection, and it
would leave a workspace's credentials visible as PRESENT and permanently
unconfigurable through this door.
WHAT THE WIRE OWES INSTEAD IS THE RESPONSE. Redaction is caller-independent and
decided on the KEY, and `Setting.value` says in one place that a `redacted: true`
entry withholds a value that may well be stored — so a write answering with both
would make one schema mean two different things depending on which operation
produced it. The write is therefore projected by `wireSetting`, the SAME function
the read is projected by, and the test states that as an equality rather than as
two assertions that could drift: the body of a PUT is byte-for-byte the body of
the GET that follows it. It costs the caller nothing, because the role promises
the stored value equals the value sent for every key this plane accepts, so the
echo carries no information the caller does not already hold.
The removal publishes `key` and nothing else. No `removed` flag — the storage seam
discards the affected-row count on all three legs, so the member would be a value
one of them had to invent — and no `value`, which on the one settings operation
that withholds nothing would publish exactly the credential the read redacts.
## Absent-vs-empty, and the 404 that is not here
REMOVING A KEY NOTHING SET SUCCEEDS. This is where the operation parts company
with the memory delete it otherwise copies: that role reports Found, and `bd recall`
already has an exit-code contract for the miss. This one cannot — an absent key
and a key stored as the empty string are one answer on this plane, the same
conflation `GET /v0/beads/config/{key}` has no 404 for — so the operation states
an intended END STATE, and the same request twice is 200 and then 200. The
document also records what the removal does NOT undo: `status.custom`'s
projection survives the row it came from, on all three implementations
(bd-yby99.33), as does the protected key's write-refused/remove-permitted
asymmetry (bd-yby99.34).
The empty string is a legal VALUE and is stored, not read as a removal: a caller
that meant "remove it" has DELETE, and conflating the two would make one request
mean whichever the handler guessed.
## The one bound that is the write's alone
`config.key` is VARCHAR(255) and the PUT INSERTS into it, so an over-long key is
an error from the column — a 500 for a request the caller could have fixed. The
GET and the DELETE COMPARE the same value and never store it, so a key no column
could hold matches nothing and already has an answer, and refusing it there would
be a refusal the role does not have. That is `releaseExpectedAssignee`'s rule
applied to the other keyed plane, and the asymmetry is asserted in both
directions.
THE ROLE'S 400 CARRIES NO `param`, and that is the depguard rule doing its job
rather than a shortcut. Two of the role's refusals are reachable and they name
different members — the protected key, and a value that does not parse — and
telling them apart takes the role's protected-key VOCABULARY, which this package
cannot hold: `httpapi-transport-boundary` denies internal/workapi from every
non-test file here, precisely so a second copy of a shared rule cannot exist to
drift. `detail` carries the role's own sentence, which names what to send instead;
every refusal this handler owns names its member.
ONE STALE SENTENCE FIXED ON THIS SURFACE. `listSettings` justified redaction with
"this API has no authentication", which stopped being true when #5516 landed the
optional bearer and which #5545 rewrote everywhere except here; settings.go's file
comment carried the same sentence. Both now say what is actually load-bearing — a
configured bearer is a single shared token that decides WHO may call and never
what a caller who is let in may read — which is the statement this whole slice
depends on. `forgetMemory`'s description carries the same staleness and is left
for that surface's own change.
CENSUS +1 EACH, twice over: two spec paths on one existing path item;
SetSettingRequest and RemovedSetting; the document's no-query-parameter list and
its two counts; two route rows on the pattern the read already registers; two
capability tokens in the ContextResponse prose (the only hand edit — Capabilities()
is derived); OpSetSetting and OpUnsetSetting; two operationCodes rows
(getSetting's vocabulary, no code minted). NOTHING new in the role plumbing:
Config.Settings, sourceRoles, roleSourceNames and s.workspaceConfig() already
carry this role, and the hook decorator's WorkspaceConfig accessor deliberately
wraps nothing — the workspace hook vocabulary hands a script an ISSUE, and a
settings write has none to name, so there is no RoleFiresHooks case to add.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Bound the settings value at the edge, and pin PUT's idempotence and the no-leak in bytes
Review found this branch shipping the exact hazard its own key bound was written
to prevent, plus two properties driven live and pinned by nothing.
## `config.value` had no bound, and it is a TEXT column
`settingWriteKey` refuses an over-long KEY with a 400 naming the member, and the
comment on it says why: an over-long key would be "a 500 for a request the caller
could have fixed". The VALUE beside it had no such check and lands in a `TEXT`
column. Measured before the fix: a 100 KiB `PUT` is a generic 500 out of the
column — the one code that tells the caller nothing about how to fix it — on the
same operation, in the same PR.
Bounded at the edge, keyed on a storage constant rather than a literal, refusing
with `param: "value"` before the role is asked.
BYTES, NOT CHARACTERS, which is why this is `types.CheckTextLen` beside
`CheckFieldLen` rather than the same helper with a bigger number: MySQL and Dolt
bound a TEXT column by ENCODED length, so 40000 two-byte characters overflow it
while 65000 ASCII ones do not. A rune-counting bound would have accepted the
former and handed the 500 back. Both directions are pinned — exactly
`MaxTextBytes` is accepted and reaches the role, one byte more is refused, and
the multi-byte case is its own test — and all three mutations (bound removed,
runes instead of bytes, one byte too strict) fail it.
NOT WIDENED, deliberately, and this is the opposite call from the ephemeral
comment column in the commit before it. A comment is a DOCUMENT — a stack trace,
a diff, a transcript — and the two comment planes disagreeing about one was a
bug. A setting is a VALUE: nothing this plane holds is a megabyte of
configuration, so the narrow bound is the honest description of what a settings
row is for rather than a limitation to widen later. The spec now states the
number and the contrast instead of claiming the 1 MiB body cap is the only limit.
## Two properties that were driven live and pinned by nothing
PUT'S IDEMPOTENCE. The method's whole argument is that the same request twice
leaves the same row, and the E2E exercised it while no test asserted it. Now
pinned on both halves: the second response is byte-for-byte the first, and BOTH
calls reach the role — the second half matters because the role performs its
write and its projection unconditionally (a no-op detection would make repairing
a drifted table depend on the row having changed, which is the state that needs
repairing), so this surface must not short-circuit either. Verified with a
compiling short-circuit mutation, which the "want 2" assertion catches.
THE NO-LEAK GREP NOW READS RAW RESPONSE BYTES rather than the decoded map. The
integration test already greps marshaled JSON; the unit test was checking members
it had thought to name, which an extension member, a duplicated key or an echo
inside a `detail` string would all walk past. Demonstrated: a mutation that adds
a `stored_preview` member carrying the credential passes every member assertion
in that test and is caught only by the byte grep — which is also what a client, a
proxy log and an access log actually receive.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Publish POST /v0/beads/issues/{id}/comments, the wire half of issueops.Commenter (ga-rslox)
The commenter is one of the facade roles the ext-api-store audit lists with no
wire operation, and comment READS already ride `getIssue?include_comments=true`.
This is the write. The role, its contract and all three legs already exist; this
slice wires them.
Spec first, then `make api-gen`, then the handler.
IT IS A SUB-RESOURCE COLLECTION OF THE ISSUE, and the argument is
listRelatedIssues' applied to a write: the row this creates is the SAME pinned
`Comment` schema `GET /v0/beads/issues/{id}?include_comments=true` already carries
under `comments`, so the operation that appends one belongs on the resource whose
members it publishes. A PLAIN collection POST rather than a custom method, for
`POST /v0/beads/issues`' reason — creating one member of the collection a path
names is what POST already means — and the collision worth checking rather than
assuming is the POST wildcard: `/v0/beads/issues/{idop}` matches ONE segment after
`/issues/` and this path has two, so the dispatcher never sees a request for it.
Checked by driving the documented path, not by reading the pattern.
THE COLLECTION PUBLISHES NO GET, and that is a statement rather than a gap. No
role answers a comment PAGE: issueops.Commenter says reading the thread is a
second question with a cursor of its own, so a GET here would be this surface
inventing the role that declined to exist. A GET lands on the catch-all and gets
the 404 every method mismatch here gets; 405 is not in the v0 vocabulary.
`author`, NOT `actor`, AND IT IS STILL CALLER-ASSERTED. The two are not the same
member wearing a different name: an `actor` is the principal a mutation is
attributed to and is no part of what the mutation wrote, while this value IS part
of the row and is echoed back by every read of the thread — so it is spelled the
way the `Comment` element that carries it back spells it. It is NOT the
authenticated principal even where a bearer is required, on the claim's terms: the
token a deployment configures admits a client to the whole surface and names
nobody. A reader of the thread is reading a claim the writer made about itself.
THE TWO MEMBERS ARE VALIDATED TO DIFFERENT DEPTHS, and the difference is the
column. `author` lands in a VARCHAR(255) every renderer of the thread prints, so
it gets `actor`'s rules whole — trim, non-empty, 256 bytes, 255 characters,
no control runes — through validateNameMember, which is validateActor's body
parameterized by the member's spelling rather than a second copy of the bounds.
`text` lands in a TEXT column stored VERBATIM, so it is checked for SHAPE only:
no trim, no length bound, no character rule, because a comment is routinely a
stack trace or a diff and the newlines are the comment. Its one content rule —
blank after trimming — stays in the ROLE, rememberMemory's posture, so `bd comment`
and this endpoint refuse the same input with the same sentence.
A WISP IS A LEGAL TARGET, resolved from the facade body rather than assumed and
pinned against real Dolt: the anchor resolves across both planes, the comment
lands on `wisp_comments` and reads back from the ephemeral thread. Only the
DURABLE trace is absent — a comment on an ephemeral row records NO history entry,
because the wisp tables are dolt-ignored precisely so ephemeral work never ships.
NO CONFLICT CODE AND NO GUARD, and both absences are the contract. A thread is
append-only and this write touches no field of the issue, so there is no row state
for an `expected_version` to be stale about and no concurrent comment to collide
with. Not idempotent either — a retry appends a second row, because two identical
comments are a legitimate thread — and the proxied test asserts that against the
table rather than the handler.
ONE ARM IN THE FAILURE PATH, and the deleted one is evidence rather than taste.
There is no explicit ErrNotFound case: ClassifyError already carries that row, and
adding one back leaves the whole package green — measured, the way #5540 measured
the same redundancy. The 400 names `text` unconditionally because exactly one of
the role's three refusals is reachable: the edge refuses an empty author under
strictly stronger rules, and an empty id cannot arrive at all.
RoleFiresHooks DID NOT KNOW ABOUT THE COMMENTER, and publishing this operation is
what made that matter. hook_commenter.go has fired the update hook for every
comment it lands since it was written, and the switch that stops `bd serve` from
being handed a hook-firing role had no case for it — harmless only while no front
door took the role off a store. An unpeeled commenter runs the workspace's script
once per comment, which is exactly the write an agent makes in a loop. The case is
added and pinned from both ends.
CENSUS +1 EACH: spec path; AddCommentRequest schema; the document's no-query-
parameter list and its two counts; route row; capability prose (the only hand
edit — Capabilities() is derived); OpAddComment; operationCodes row
(getDependencyTree's vocabulary, no code minted); httpapi.Config.Commenter with
sourceRoles, roleSourceNames, the Server field, Listen and s.commenter();
timedProvider.Commenter and its CommenterSource assertion; checkedCommenter; and
the bd serve binding. Plus Commenter on serveRoleSource and both cmd/bd stubs,
which is #5539's return: a named build error in the file that has to grow a method.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Close the RoleFiresHooks blind spot as a CLASS, and finish 0049 on the ephemeral comment plane
Review found the first version of this branch overclaimed twice. Both claims are
now either true or gone, and both are held by a test rather than by prose.
## The hook guard was blind FOUR ways, not one
The commit said the commenter was "the one hook-firing role RoleFiresHooks did
not know about". It was one of four. `*hookReadyClaimer`, `*hookBatchCloser` and
`*hookBatchCreator` were outside the switch too, and all three are served over
PUBLISHED operations — `issues:claimNext`, `issues:batchClose`,
`issues:batchCreate` — through roles `httpapi.Listen` sweeps by way of that exact
switch. A store-derived value for any of the three was therefore ADMITTED and
served, running the workspace's scripts for the life of the process: once per
bead a polling drainer wins, once per landed item plus one for a chained claim,
and once per item of a batch — so a hundred-item create was a hundred
subprocesses inside one HTTP call.
Fixed: three cases, plus the same both-ends pins the commenter got. Store side,
the accessor really hands back a hook-firing value and `serveIssueRoles` peels to
exactly the layer beneath it (the peel-depth half matters — a peel two layers
deep also answers false and silently drops the telemetry span, so the assertions
check identity, not just the predicate). Server side, `Listen` really refuses each
one.
AND THE PROSE IS NOW TRUE BECAUSE A SCAN MAKES IT TRUE.
`internal/storage/hook_decorator.go` has carried the sentence "every case that
exists today is in the switch" while it was false four ways, because every one of
the four was found by hand by whoever happened to publish an operation over that
role. That is a discovery process, not a guarantee, and it left the others
standing each time. `TestRoleFiresHooksKnowsEveryHookFiringRole` now parses this
package's `hook_*.go` for every decorator that holds an `issueOperationHooks` and
requires a case that RETURNS TRUE for it. Source scan rather than reflection, for
the reason backend/conformance's role census gives: these types are unexported
and are never built except through their accessor.
It counts the RETURN, not the case label, which closes the second failure mode
this switch has actually had: a Go type switch does not fall through, so
`case *hookMetadataCAS:` with an empty body answers FALSE, and a rebase shipped
exactly that with the compiler, vet, lint and CI all green. Mutation-verified in
both directions — deleting a case and emptying a case each fail the scan by name.
## `wisp_comments.text` was still TEXT, so the document's bound was false
The spec said `text`'s only cap is the 1 MiB every body shares. That was true on
one plane. Migration 0049 widened `comments.text` to LONGTEXT and did not touch
`wisp_comments.text`, which has been TEXT — 65535 bytes — since 0021 created the
table. Measured live before the fix: a 102,000-byte comment is 200 against a
durable issue and 500 against a wisp. This operation resolves its anchor across
BOTH planes deliberately, so nothing above the storage seam could tell a caller
which side of the bound it was on until the write failed.
Widened rather than caveated: the two planes should not disagree about what a
comment may contain, and a caveat would have to be re-stated by every client. The
handler grows no length check — there was never one to add; the fix was the
column.
MIGRATION 0065 + ignored/0024, and the twin is required rather than offered:
`wisp_comments` is clone-local and dolt-ignored, so a fresh clone materializes it
from the ignored series while the main cursor arrives at-latest and 0065 never
runs there. That is check D of scripts/check-migration-hygiene.sh, and the same
fresh-clone door ignored/0021 — the wisps half of this identical 0049 gap —
already records. Both guarded on 0049's `COLUMN_TYPE = 'text'` probe, so they are
no-ops on an already-widened workspace and idempotent on replay; the `.down` is
0049's intentional no-op, because shrinking back would truncate.
Verified from both ends: red-first against real Dolt (the wisp 500 above, green
after), and `TestEmbeddedIgnoredSeriesConvergesWithFreshInitShape` — the
engine-level backstop behind check D — fails naming `wisp_comments.text` when the
twin is withheld.
### MIGRATION LANE NOTE, for the deployment checklist
THIS MOVES THE MIGRATION CEILING FROM 0064 TO 0065, and the ignored series from
0023 to 0024. Anything pinned to "latest is 0064" — a deployment checklist, a
pre-flight assertion, a fixture bundle — transfers to 0065 when this lands.
Migration files are frozen once merged (hygiene check C), so a follow-up cannot
edit these two; a fix would be a further migration. NOTHING IS DEPLOYED BY THIS
PR: it ships the files, and the schema moves on whatever schedule the deployment
checklist runs.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Retire the last three wisp-switch call sites, and open the label guard on the whole package (ga-2ltro.12)
ga-26w10 deleted a four-way switch over (add|remove) x (wisp|durable) from
`bd label` and lint the door shut behind it. THE SWITCH SURVIVED AT THREE MORE
SITES, and the rule that was supposed to stop the next one could not see two of
them. This retires all three and makes the rule package-wide.
`bd tag`'s proxied route (cmd/bd/mutate_proxied_server.go) reached
uw.LabelUseCase() through proxiedMutateIssue, whose callback signature hands out
a unit of work AND an isWisp boolean — an invitation to pick a plane, which the
tag callback accepted. It now builds one IssuePatch and hands it to
issueops.Lifecycle.Update. IssuePlaneOnly stays false, so the role resolves the
plane inside its own transaction; TestProxiedServerTag/tag_wisp_routes_to_wisp_labels,
which asserts at the SQL table that a wisp's label lands in wisp_labels and the
durable table stays empty, passes through the role with no branch in the
command. It went red on the pre-fix tree under the boolean flipped backwards,
which is the mutation this exists to kill and which is no longer expressible.
THE MOLECULE PORT'S LABEL WRITE IS GONE RATHER THAN RE-ROUTED, and that is the
stronger fix. molWriter had an AddLabel verb with exactly one caller —
bondProtoProtoInto, labelling a compound it had just created — and two
implementations that each resolved the plane AGAIN by a DIFFERENT predicate:
storeMolWriter deferred to the storage layer's isActiveWisp, uowMolWriter
consulted a cache filled from IssueUseCase().GetWisp. Two predicates for one
fact is how a row and its labels come apart. The label now travels in
compound.Labels, so the create that decides the row's table places the label
too, and AddLabel is deleted from the interface and both implementations. The
disagreement is unrepresentable, not merely unlikely.
Worth stating plainly for the reviewer: uowMolWriter.AddLabel's WISP branch was
unreachable. Its only caller labels a durable epic it just created, so the cache
answers false every time. That is why this site had no end-to-end mutation to
run and why the new test is a unit test with a recording writer: it pins that
the create carries the label, which is the property that makes the branch
unnecessary rather than merely unused.
`bd set-state` had the switch FOUR times — the label read, the event create, the
old-label remove and the new-label add — and a second implementation of the whole
command in cmd/bd/state_proxied_server.go that no longer exists. All three verbs
now have ONE body each, on both routes, ending at issueops.Reader.Get and
issueops.Lifecycle:
- the label READ is Reader.Get's already-hydrated, already-sorted Labels, so
there is no label-shaped read here at all — the same move ga-26w10 made for
`bd label list`;
- the dimension SWAP is one IssuePatch carrying Add and Remove together;
- the EVENT is one Lifecycle.Create with ParentID, which mints the same
hierarchical child id and writes the parent edge atomically.
FOUR DELTAS, none of them absorbed.
THE DIRECT ROUTE'S DELTA IS THE EVENT'S PLANE, AND ONLY THAT. An earlier draft
of this message claimed the direct route "read no state and wrote its label into
the wrong table" for a wisp. That was reasoned, not measured, and it is FALSE:
store.GetLabels, AddLabel and RemoveLabel all reach issueops.*InTx with an EMPTY
table name, which routes by IsActiveWispInTx, and utils.ResolvePartialID
resolves through the wisp-inclusive search. Measured at the parent commit,
`bd set-state <wisp> patrol=muted` on the direct route resolves, swaps the
label, and `bd state <wisp> patrol` reads back "muted".
What the parent DID get wrong is the EVENT. It created the state-change bead
with store.CreateIssue and no wisp flag, so an ephemeral subject got a DURABLE
event child, and the parent edge was a second unguarded write across the two
planes. Measured on both sides of this commit, same wisp, same command:
parent event ms-wisp-865.1, no `ephemeral` field -> durable
this event ms-wisp-859.1, `"ephemeral": true` -> the subject's own plane
so a wisp's state history now dies with the wisp instead of outliving it in the
durable table, and its parent edge is written inside the guarded create rather
than beside it.
That correction is the finding, not the footnote: this commit's own brief is
MEASURED, NOT REASONED ABOUT, and the sentence that broke the rule was in the
commit message. The rule covers the artifact too.
A FAILED REMOVAL NO LONGER PASSES SILENTLY — with one half still open. Both
retired routes warned and carried on when the remove failed, leaving the issue
holding two values for one dimension, which findStateLabel then resolves by
whichever the label read returns first. A store-level failure now fails the
command, because the remove and the add are one guarded update.
WHAT THAT DOES NOT CLOSE, stated because the first draft of this line
overclaimed it as "the dimension has one value or nothing was written": the
CONCURRENT swap. Two racing `bd set-state <id> dim=...` calls both read the same
old label, each patch removes a label the other already removed — a no-op, not a
conflict — and both adds land, so the dimension ends with TWO values. A patch is
atomic for ONE writer; it is not a fence. ExpectedVersion cannot supply one
either, because label writes deliberately do not remint RowVersion. The race is
pre-existing, is not made worse here, and is filed as ga-dle5g.
The proxied route LOSES ONE TRANSACTION. Its event and its label swap used to
commit together; they are now two role calls. The direct route was never atomic
at all (four unguarded writes), so this is a net gain there and a stated cost
here, and it is the same trade ga-26w10 took for the same reason. The event's
plane is the subject's own retention mode copied onto the child rather than
chosen, and it is CHECKED: a guarded create refuses a parent edge it cannot
write, so an event that disagreed with its subject's plane fails loudly instead
of landing in the wrong table.
DOLT HISTORY ATTRIBUTION MOVES, which is cosmetic and is said anyway because an
unstated delta is how the two corrections above came to be needed. The role
composes its own version-commit message, so `bd tag` and `bd set-state` write
"bd: update <id>" where they used to write "bd: tag <id>" and
"bd: set-state <id>". `bd dolt log` still names the issue; it no longer names
the verb. Nothing greps for those strings in this tree.
THE FORBIDIGO RULE IS NOW PACKAGE-WIDE ACROSS cmd/bd. It was narrowed by a
path-except to cmd/bd/label.go on the argument that holding an unmigrated
command to a rule written for a migration it had not had would be a lint waived
on sight. What that missed is that the waiver was INVISIBLE — a file outside the
exemption got no marker, no reason and no diff — so the three commands still
hand-rolling the switch looked exactly like the files with nothing to declare.
Two of them were additionally exempted by `path:`-only holes written for the
FILTER rule, which silently open every forbidigo rule for their files:
mol_port.go by the mol_ hole and export_source.go by the bulk-movement one.
EVERY HOLE IN THAT FAMILY IS `text:`-SCOPED NOW, not just those two. Scoping
only the holes that covered a violation TODAY was the same reasoning error as
the paragraphs above — it sized the guard by where the calls are rather than by
where the next one may be WRITTEN — and a review probe proved it with two dodges
that both passed: a neutrally-named helper dropped into the ado/gitlab/jira/
linear hole, and that helper handing the RAW use case back to a NEW file, which
then needs no import and never spells the accessor. Both are caught now, the
second one twice (the return type and the call), and both were re-confirmed to
PASS with the hole unscoped, so the fix is the scope and not a coincidence. The
`_test\.go` exemption stays unscoped on purpose: `run: tests: false` means
forbidigo never analyzes a test file, so scoping it would assert nothing.
MEASURED, NOT REASONED ABOUT. Before: 27 LabelUseCase call sites in 8 non-test
files. After: 15 in 6, every one carrying //nolint:forbidigo and the reason that
site is not a role's question, and they add up: five in-transaction port reads
(mol_port.go), two alternate-view reads (show_proxied_server.go), two bulk
relation loads (export_source.go), two label-vocabulary reads and two
label-propagate WRITES (label_proxied_server.go), one in-transaction command
read (close_proxied_server.go) and one dry-run preview read
(create_proxied_server.go). 5+2+2+2+2+1+1 = 15. The propagate pair are the
acknowledged carve-out and the only survivors that write; each site names its
follow-up, and propagate's is issueops.BatchApplier.ApplyBatch, blocked on a
cmd/bd accessor.
Both halves verified by mutation, one bypass each. A scratch
uw.LabelUseCase().AddLabel() planted in cmd/bd/state.go — reached through
proxiedOpenReadUOW, so the file imports neither internal/storage/uow nor
internal/storage/domain and depguard is blind to it — is caught by forbidigo. A
scratch uow import in the same file is caught by depguard, which cmd/bd/state.go
now joins: it is the second entry on that list because its three verbs really
have migrated, so the rule pins something that happened.
The depguard prose said the forbidigo rule was "scoped to this same file" and
the exclusions block said its label narrowing cost "a `text:` on ONE of the
per-path holes". Both are now what they are: package-wide, and three.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Bound the union legs, and stop letting SQL page a sort it cannot order (ga-2ltro.7)
The two residues the #5476 review deferred, and they turned out to be one rule
observed from both ends: A WINDOW IS ONLY EVER PUSHED UNDER AN ORDER THE QUERY
CAN EXPRESS.
F4 — THE LEGS CARRY THE WINDOW NOW. buildUnionSubquery emitted no bound on
either side of the UNION ALL; only the outer query had one, so both planes were
read in full to deliver a page. Measured on a seeded two-plane store, a
four-row page with twenty matching rows per plane: each leg returned 20 rows,
40 scanned to deliver 4. Each leg now carries the outer clause VERBATIM plus the
deepest row index the outer query can reach, and returns 5 — the bound plus its
probe row — for 10 scanned instead of 40.
EACH LEG IS PARENTHESIZED NOW, and that is load-bearing rather than cosmetic: a
leg carrying its own ORDER BY and LIMIT inside a bare `leg UNION ALL leg` is a
SYNTAX ERROR, the engine reading the trailing clause as the union's own. The
first cut of this change shipped without the parentheses and `bd search` failed
outright — caught by CI, not by the leg probe below, because that probe executes
each subquery STANDALONE where the same string is perfectly legal. A test that
measures the part is not evidence about the whole, so there is now a case that
runs the composed query on both twins across six shapes (ordered, offset, text
term, default order, unbounded, Go-side), and it goes red on the un-parenthesized
form with the exact engine error.
Reusing the outer ORDER BY string rather than rebuilding it is what makes the
bound safe: unionOrderBySQL names `id` and the `sort_*` aliases, both of which
every leg already projects, so one string is valid in both positions and a leg
cannot come to rest in a different order than the one the outer query is about
to cut against. The pushdown is sound because the order is TOTAL — every clause
sqlbuild renders ends in `id ASC` — so a row in the union's top-N is in its own
leg's top-N, there being nothing else it could be behind. legLimit is the bound
PLUS any offset the engine carries, because those are rows the outer query reads
and discards; an offset this package keeps for itself is already inside the
bound.
F5 — AND THE OTHER HALF IS WHY THE LEGS GET NOTHING UNDER `--sort id`. That key
is the one sqlbuild renders no ORDER BY for, so the query ran
`SELECT id, src FROM (leg UNION ALL leg) merged LIMIT n` — a LIMIT with no
ordering anywhere in the statement. A LIMIT without an ORDER BY does not return
the first n rows, it returns n rows.
MEASURED, and it is worse than "arbitrary". On a store with 12 durable and 12
ephemeral beads whose ids interleave, `--sort id --limit 5` answered
[000 002 004 006 008]: five durable rows, and not one wisp. The Go-side sort
then put them in perfect order, which is why this reads as a correct page — the
ORDER was right and the MEMBERSHIP silently excluded an entire plane.
Two changes close it, and both are needed:
- searchWindowFor pushes NO page bound for a Go-side sort, which is the same
answer internal/workapi.SQLLimit gives the reader role for the same reason.
The CAP is not waived with it: maxRows still sizes a bound, so an unordered
scan too large to hold answers ErrTooManyRows rather than reading the
workspace.
- idSrcPage.sortGoSide establishes the order before finishWindow trims. This
is the union seam's copy of issueops.sortMergedResults and exists for the
identical reason that one gives: a concatenation trimmed without a re-sort
keeps an arbitrary prefix. The id is already on the ref, so no row has to be
hydrated to be placed.
THE LIVE CALLER IS `bd query`, NOT `bd list`, and the review's note undersized
it. `bd list` is protected by workapi.SQLLimit and the wire's list endpoint pins
"created" — but workapi.BuildQueryPlan pushes SortBy and Limit straight onto the
filter for any filter-expressible query with no such guard, DefaultQueryLimit
means a limit is ALWAYS set, and "id" is in both the CLI's and the HTTP
endpoint's accepted sort keys. So `bd query '<expr>' --sort id` and
GET /v0/beads/issues/query?sort=id reached this on the DEFAULT path, on a wire
the review recorded as safe. BuildQueryPlan's own comment justifies the pushdown
by promising "the page is the first N in the requested order on every backend";
that was true of every key except the one IsGoSideSort names. Both twins are
covered — the counts twin is the one those callers reach.
TWO THINGS THIS DOES NOT FIX, named rather than left for the next reader.
The per-table seam (internal/storage/issueops) bounds each leg with
EffectiveSearchLimit under the same absent ORDER BY, so it picks an arbitrary
subset per leg before sortMergedResults runs; and sqlbuild.Less ignores sortDesc
for "id", so a reversed id page there keeps the byte-FIRST rows. sortGoSide
honors sortDesc rather than mirroring that.
Costs, stated. A caller combining `--sort id` with a small limit and no cap now
reads every matching row where it used to read limit+1. It read the wrong ones,
and the reader role has always paid this price on the same query.
Also folded in, both comment-only and both named by the review: count.go cited
`bd doctor --check=cross-table`, a selector that does not exist (the flag takes
artifacts, conventions, pollution and validate; the cross-table check runs in
the default sweep), and scanIDSrcPage claimed the shadowed durable row is
dropped "wherever it sits" when the drop only ever reached the scanned window —
a distinction this change sharpens, since the legs are now bounded.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* feat(list,ready,httpapi): reach the Brief projection from both front doors
Application half of #5546, stacked on the storage half. `--brief` on `bd list`
and `bd ready`, `brief` on `GET /v0/beads/issues` and `GET /v0/beads/ready`.
Defaults to false everywhere, so no payload changes for a caller that does not
ask; #4122 objects to default payload changes and #5078 records what the last
one cost.
ONE REGISTRATION PER COMMAND REACHES BOTH OF ITS ROUTES, because the two
gatherers are shared. `bd list` hands `in.ListRequest` to issueops.Reader.List
verbatim on the direct and the proxied route. `bd ready` uses the Reader role on
NEITHER: both routes pass the filter that gatherReadyInput built through
workapi.BuildReadyFilter, so `types.WorkFilter.Lite` is what has to carry it
there, and the CLI-hop tests assert the filter rather than the request for that
reason. The HTTP handlers build both requests independently of the CLI, so they
are wired separately.
REFUSED WHEREVER IT CANNOT BE HONORED, rather than accepted and dropped, which
is the silent no-op the storage half was written to close. `Lite` reaches a
driver through exactly two queries: the bare SearchIssuesInTx (#3906) and the
counts mega-query (the storage half). `GetReadyWork` and the by-ID hydration
behind the tree walk read neither, so:
- `bd ready --brief` requires --json, and is refused with --claim, --gated,
--mol and --explain. `bd ready` runs the counts query for --json alone; the
text routes call the bare GetReadyWork and the three specialized modes
answer with shapes of their own. The direct route dispatches those modes
BEFORE gathering, so each check appears in cmd/bd/ready.go as well as in
the gatherer, exactly as the --claim conflicts beside them already do.
- `bd list --brief` works in text mode too, since all of its page routes reach
Reader.List, and is refused with --watch, with --format, and with --parent
in the tree view. --tree defaults to true, so a bare --parent in text mode
is that same walk without the flag being typed.
--claim is refused for a stronger reason than the rest: no route can serve it.
ClaimNext refetches its winning row whole and returns ErrValidation for a
projected request. Catching it in the gatherer keeps the message about the two
flags the user typed, and leaves readyRoleRequest free to carry Brief for the
COUNT, which needs it.
--format is refused rather than annotated because a caller's template can print
any of the six dropped fields and there is nothing to hang a marker on.
`bd list --long` is the one built-in text rendering that prints one of them, and
it is allowed because it CAN say so: it now prints
"Description: (omitted by --brief)". That keys off types.Issue.IsLitePartial
rather than off the flag, so a row that arrived projected reads the same
whichever door set it.
THE JSON PAYLOAD CARRIES NO MARKER, and the flag help and both OpenAPI
descriptions say so plainly. types.Issue.IsLitePartial is `json:"-"` and
documented as internal-only by #3906, so an omitted field is indistinguishable
from an empty one on the wire; only the caller that sent the flag knows. #5549
deferred exactly this marker for brief_deps as its own change, and this follows
that, rather than changing a shared type's wire form on the way past.
`brief` is decoded in handleListReadyWork and NOT in readyFilters, the
vocabulary the ready listing shares with :count and :claimNext, because it
projects fields rather than selecting rows and neither of those returns rows to
project. That made TestClaimNextAdmitsExactlyTheListingsFilters fail, correctly:
its single hardcoded `limit` exception is now a `pageKnobs` table of the
listing's two page knobs, each still asserted ABSENT from claimNext, since a
documented parameter that is always a 400 is a trap. Both branches of that
assertion were verified by sabotage.
RED BEFORE GREEN on all nine new assertions, each verified and reverted: the two
request hops, the seven refusals, the long-format marker, and both branches of
the parity table.
Gates: go build ./..., go vet ./..., gofmt, cmd/bd, internal/httpapi,
internal/workapi, backend/conformance, internal/storage/issueops, issueops,
make api-check, ./scripts/generate-cli-docs.sh --check.
Refs: #5546, #3906
* fix(ready,changelog): close the review findings on #5586
THE THREE DIRECT-ROUTE REFUSALS WERE UNTESTED, and the review's mutation
proved it: deleting the --gated check left `go test ./cmd/bd/` entirely green
while `bd ready --gated --brief` silently ignored the flag on the direct route.
Nothing in the package drives readyCmd's RunE, so the gatherer's tested copies
were only ever guarding the proxied route. The PR body's "seven refusals, red
before green" covered five.
Taking the second of the two suggested fixes, since it removes the duplication
rather than testing it. The per-mode copies in ready.go are deleted. Their body
moves to briefModeConflict, which gatherReadyInput now calls, and RunE calls
once through briefModeConflictFromFlags, hoisted ABOVE the mode dispatch and
above the proxied branch so it is the single place a --brief conflict is
decided for this command on either route.
TestReadyCmdRefusesBriefBeforeItDispatches drives RunE directly, which is
reachable because that check now precedes every store access. Verified by
reproducing the review's own mutation: deleting the hoisted call fails the
--gated, --mol and --explain cases.
THE CHANGELOG ENTRY CONTRADICTED ITSELF, claiming --brief "marks each row
is_lite_partial" and then, in the same paragraph, that the response carries no
marker. The first half was written before the wire form was checked;
types.Issue.IsLitePartial is `json:"-"` and never serialized, so an agent
following that sentence would have grepped its JSON for the field and concluded
the feature was broken. The no-marker fact is now its own paragraph, and the
only marker the entry claims is the text one `bd list --long --brief` prints.
The entry cites #5554 and #5586 alongside #5546, matching the sibling
brief-deps entry.
Gates: go build ./..., go vet ./..., gofmt, cmd/bd, internal/httpapi,
internal/workapi, backend/conformance, internal/storage/issueops, issueops,
make api-check, ./scripts/generate-cli-docs.sh --check.
---------
Co-authored-by: sjarmak <t@t.co>
A bare Close() on a dial-only probe connection (waitForReady, the dolt-store
fail-fast dialer, the socket-fallback probe, the circuit breaker probe, and
several doctor/CLI reachability checks) sends a TCP RST instead of a clean
FIN. dolt sql-server interprets that RST as an aborted MySQL handshake;
enough of them in a short window can crash the server process (see #4132,
hamchowderr's Windows repro in issuecomment-5014617950 on #4132).
Add internal/doltserver.DrainAndCloseProbe/ProbeSQLServer, a shared helper
that reads (and discards) the handshake greeting before closing, and sweep
every MySQL-speaking dial+close probe in the tree onto it. waitForReady also
gets an F7 fix along the way: a dial that succeeds but never greets (TCP
listener accepting, MySQL engine not yet writing) is no longer treated as
ready — it keeps polling until a greeting arrives or the deadline passes.
Non-MySQL probes (remotesapi gRPC/HTTP, SSH, HTTP(S)) are left as bare
dial+close with a comment explaining why: there is no handshake to drain.
This lands the drain half of #4133 (Zireael). The config half (background
Dolt workers via --config YAML) is not ported here — it is superseded by
main's #4986 YAML-config path, which already addresses that PR's F1 lint
findings. The orphaned-server angle from #4133's report remains tracked by
the existing #4282.
Agent-Signature: claude-fable-5-high on behalf of maphew
Co-authored-by: Zireael <3856578+Zireael@users.noreply.github.com>
* feat(journalops): the mutation journal becomes the third facade namespace
The durable mutation journal's read side is now a role. `journalops` is a
leaf package beside `issueops` and `memoryops` holding Row, Page,
TruncatedError/TruncatedCode and `Journal`, whose doc comment is the
specification: since-exclusive, seq-ascending, limit 0 uncapped with the
wire's cap named as the handler's, a head that comes with its rows and never
decreases, a caught-up checkpoint, and a typed truncation naming a resumable
window.
NOTHING CHANGES BEHAVIOR. The four names in `internal/storage` become
ALIASES of the leaf — `type EventsJournalCursor = journalops.Journal` and its
three siblings — so every implementation, every errors.As site and every
caller compiles unchanged. The alias direction is what avoids the import
cycle: the leaf imports context and fmt and cannot name internal/storage, so
the canon goes down and the alias goes up. Outside storage.go and the
conformance tier, the only non-test edits in this change are COMMENTS.
The role brings the apparatus a role owes:
- backend/conformance/journal_contract.go, six cases over a fixture carrying
the role, the activation switch, a prune, and a mutation kit that is
exhaustive against the engine's closed op vocabulary.
- Wirings on all three legs (dolt, embeddeddolt, uow), so #5499's
entrypoint-scoped lock passes with every leg running every case.
- journalops added to the conformance census's facadePackages. That is the
#5459 demand side, and the role that needed it: `Journal` is handed out by
NO accessor — a front door type-asserts for it — so only a source parse can
see it. issueops.Importer is the precedent.
EventsJournalAccessor and EventsJournalConfigurer stay in internal/storage.
Retention and activation are operator surface, and a server documented to
publish the journal and never retain it must not hold a delete.
Net deletion on the bespoke side: TestEventsJournalPageReportsTheHead is
subsumed by the contract and is gone. TestEventsJournalRestartAndRetentionBoundary
stays, because it observes ReadEventsInTx — the accessor's second read body,
deliberately not on the role — and a mutation of one is invisible to the other.
Mutation-measured, per case, on the embedded leg: an inclusive checkpoint, a
head derived from the page, an untyped truncation, a head taken from MAX(seq)
of surviving rows, and a dropped engine-only op each redden exactly the arm
named for them, and a fixture whose activation hook is a no-op reddens all
six. Reading the head BEFORE the rows leaves all six green — that promise is
declared unpinnable in the contract header rather than faked.
Refs ga-fvya1, ga-2yaqp.4.
* docs(journalops): fix three comment-precision findings from review
All comments, plus one test-only compile-time pin block.
1. journal_facade_test.go told a misassembled causal story: it used the
CURSOR de-aliasing as its example and then attributed the breakage to
errors.As. Those are two different failures. Measured, both:
de-aliasing the interface builds the WHOLE TREE clean and breaks nothing
behavioral — what it costs is the claim that one role has one name — while
the error's dangerous shape is not the bare defined type (which loses
Error() and fails to build) but the COPY-PASTE TWIN, which compiles in
silence and stops crossing errors.As for everything holding the leaf's
spelling. Rewritten to say that straight.
2. The seq commit-order unpinnable declaration cited "the dolt package's own
journal tests" for the server-mode half. Those are single-threaded. The
actual pin is internal/storage/domain/db/journal_seq_test.go —
TestEventsJournal_CommitOrderedGaplessSeq drives two OVERLAPPING
transactions on independent connections, and
TestEventsJournal_ConcurrentWritersGaplessNoDup a racing batch. Cited
correctly, and the single-threaded ones named as NOT the pin.
3. EveryMutationKindLandsARow's runs-last ordering is load-bearing but held
by convention: a reorder compiles, passes, and silently gives up the only
coverage that a journal keeps recording after a full prune. It was stated
in the dispatch table and the three leg wirings; it is now stated at the
case itself, where somebody editing a leg file is actually looking.
And the compile-time half of the alias pin, which fires before any test runs:
a pointer conversion per name. The pointer form is not decoration — for the
three structs a plain assignment would do, but for the INTERFACE it would be
blind, since interface-to-interface assignment goes by method set and a
de-aliased cursor still accepts a journalops.Journal. Watched fail: the
de-aliased interface, which nothing else in the tree catches.
---------
Co-authored-by: Review Sim <ci@beads.test>
* feat(show): --brief-deps flag reaching DetailOptions.BriefDeps
Application half of #5546, stacked on #5547. Both show routes gather flags
separately, so the flag is read in cmd/bd/show.go and in
gatherShowProxiedInput; a flag added to one reaches neither by implication.
Defaults to false, so the JSON payload is unchanged for callers that do not
ask. #4122 objects to default payload changes and #5078 records what the last
one cost.
Measured against a 16,051-issue store: bd show <id> --json is 216,605 bytes and
the same call with --brief-deps is 23,287, an 89.3% reduction, with the
identity fields intact and zero bytes of dependency text.
* feat(httpapi,conformance): reach BriefDeps from the HTTP door and pin it
Review follow-ups from #5547.
The conformance case is the blocking one: backend/conformance pins
IncludeDependents/IncludeComments so an out-of-tree Reader cannot ignore them,
and BriefDeps landed on the same public contract with no case. Registered at
all four call sites. Verified non-vacuous by disabling the projection and
watching TestReaderContract go red against a real backend.
The HTTP handler builds GetRequest independently of the CLI, so wiring cmd/bd
alone left the field reachable from one front door of two. Adds the brief_deps
query parameter to the v0 spec and regenerates apigen types; make api-check is
green.
Also: the cmd/bd flag test reset the value but left pflag's Changed true, which
outlives the value and contaminates later tests in the package.
* fix(conformance,show): close the review findings on #5549
The conformance case asserted Design and AcceptanceCriteria were empty without
ever seeding them, so a Reader that stripped description and notes but leaked
the other two passed. That is the same fixture-blindness the parent PR was
written against. Seeds all four heavy fields, and asserts Title, which the
projection deliberately keeps and the OpenAPI text promises.
Both CLI routes built GetRequest inline inside functions that need a
UnitOfWork, so the hop was unreachable from a test and deleting either
assignment left the suite green. Extracted showGetRequest and
showProxiedInput.getRequest and pinned both, matching what the HTTP door
already had.
The case now gets its own Test at each storage call site rather than riding
inside the OptionalRowLists test, so a BriefDeps failure reports under its own
name instead of misdirecting triage. The embeddeddolt site no longer builds a
second fixture.
Adds the CHANGELOG entry for the #5547 + #5549 pair, at the point the feature
becomes reachable.
---------
Co-authored-by: sjarmak <t@t.co>
truncate() used byte slicing (s[:maxLen-3]+"..."), which can emit invalid
UTF-8 when a multi-byte rune (e.g. em dash) straddles the cut. bd prime --mcp
then breaks SessionStart hosts that decode stdout strictly.
Keep the byte budget, walk back to a valid UTF-8 boundary, and route
truncateMemory / todoTruncate / truncateDescription through the same helper.
Co-authored-by: Marlon Costa <marlonsc@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
Priority used the filled circle also mapped to status-blocked, so agents
misread ready work as blocked (GH#4996). Render P-labels only; document
the convention for agents; keep ● for blocked status alone.
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
* Stop cook coercing non-whitelisted formula step types to task
stepTypeToIssueType had a hardcoded five-type switch whose default
branch silently turned every other step type — custom types like
"duty", but also built-ins like decision, spike, and story — into
task. Pass the type through with Normalize() instead, defaulting to
task only when the step type is empty.
No validation is added here: pour already registers non-built-in
types via ensureSubgraphCustomTypes and the storage layer validates
against types.custom, the same division of labor as bd create --type.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YLWg73gpPfwinj1jn3UhmU
* Fix custom-type registration gaps and honor declared parent step types
Review follow-ups to the cook/pour type passthrough (GH#5443):
- bd cook --persist now registers custom step types via
ensureSubgraphCustomTypes, matching the pour path
- doltTransaction.SetConfig syncs custom_types/custom_statuses tables so
in-transaction registration is visible to validation
- Wisp creation builds its validation BatchContext on regularTx (new
issueops.CreateIssuesInTxWithContext), so a custom type registered in
the same transaction validates on the dolt server backend
- Parent steps with a declared type keep it; only an undeclared type
defaults to epic
- Step types are trimmed before normalizing; types.custom is serialized
with json.Marshal; doctor's multirepo checks parse it JSON-first
- Registration gates on IsBuiltIn() so built-in types like event are not
churned into types.custom
- Regression test runs against a local dolt sql-server when the Docker
test container is unavailable
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YLWg73gpPfwinj1jn3UhmU
* Consolidate duplicated custom-type plumbing behind shared issueops helpers
Cleanup pass over the GH#5443 branch:
- Export issueops.ParseTypesConfigValue and point the doctor, domain/db,
template.go's comma-split hack, and config_helpers.go's own inline
copies at it instead of five parallel JSON-or-CSV parsers.
- Extract issueops.SyncConfigTables to own the config-key -> normalized
table mapping; all four SetConfig implementations now share it.
- Build one BatchContext per doltTransaction create call: hoisted above
the wisp/regular branch in CreateIssue, shared across both legs in
CreateIssues (drops 4 redundant config reads on mixed batches).
- CreateIssuesInTxWithContext sets SkipChildCounterReconcile on a
shallow copy so the caller's context is reusable.
- Retype ensureSubgraphCustomTypes as ensureCustomTypesForIssues taking
[]*types.Issue, removing cook's throwaway TemplateSubgraph wrapper.
- Rebuild setupLocalServerStore on the setupWispCascadeStore recipe:
t.Cleanup teardown and CreateIfMissing instead of hand-rolled
CREATE DATABASE / initSchemaOnDB / shelled dolt init.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YLWg73gpPfwinj1jn3UhmU
* Stop auto-registering formula custom types; flatten unregistered to task/epic
Pour and cook --persist no longer write step types into types.custom.
A step type that is neither built-in nor already registered is flattened
with a warning — to epic when the step has children (matching the
undeclared-parent default), task otherwise. Operators opt in with
bd config set types.custom before pouring; a typo'd step type can no
longer become a permanently registered custom type.
ensureCustomTypesForIssues (the read-merge-write into types.custom)
becomes flattenUnregisteredIssueTypes, reading types.custom through the
transaction plus config.yaml-declared types to match insert validation.
The now-unused molConfigWriter interface is gone.
Also lands the code-review fixes on the same plumbing:
- storeMolWriter.GetConfig routes through the bound transaction, fixing
out-of-tx config reads (lost-update window; MaxOpenConns=1 hang).
- doltTransaction.SetConfig invalidates DoltStore's config caches via
the shared invalidateConfigCaches, so long-lived processes stop
serving stale custom type/status sets.
- doctor's unknown-type check uses IsBuiltIn instead of a stale 6-type
hardcoded list that would have flagged spike/story/gate as unknown.
- schema backfill uses issueops.ParseTypesConfigValue (no import cycle;
the old copy kept untrimmed JSON elements).
- Dead EnsureCustomTypeInTx (misleading GH#3213 doc, wrote table-only
rows the sync invariant wipes) and dead GetCustomTypesTx deleted.
Step.Type docs updated and schema_gen.go regenerated via go generate.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YLWg73gpPfwinj1jn3UhmU
* Fold the last SetConfig path into SyncConfigTables; cleanups
Follow-up cleanup on the custom-types work.
EmbeddedDoltStore.SetConfig still carried the hand-rolled `switch key`
that the other four SetConfig paths replaced with SyncConfigTables, so
the helper's stated invariant — every SetConfig path keeps the
projection in step — had a hole. Route it through the helper, then
unexport syncCustomTypesTable/syncCustomStatusesTable: with no callers
left outside SyncConfigTables, the single-entry-point rule is enforced
by the compiler rather than by a comment.
Smaller cleanups alongside it:
- Drop linearConfigReader; it was the same single-method interface as
configReader, in the same package.
- flattenUnregisteredIssueTypes built three collections where one does
the job. Seed `unknown` directly and delete registered types, losing
the string/IssueType round-trip.
- Use WarnError instead of open-coding its Fprintf.
- processStepToIssue trimmed step.Type twice, once inside
stepTypeToIssueType and again for the epic default; hoist to one
declaredType so the two can't drift.
- Remove the `typesStr == ""` guard in readTypesFromDB, left behind
when its loop became ParseTypesConfigValue (which returns nil for
empty).
- Rename the BatchContext copy in CreateIssuesInTxWithContext from
`local` to `batch` instead of reassigning the parameter, so bc
provably stays the caller's pointer.
- Lead storeMolWriter.GetConfig's doc with the reason that still
applies (second pool connection deadlocks at MaxOpenConns=1); nothing
registers types in-transaction during pour any more.
No behavior change. gofmt, go vet, and the affected tests pass;
golangci-lint was not available locally.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YLWg73gpPfwinj1jn3UhmU
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(cli): one text-source layer for comment, note, and human respond
`bd comment`, `bd note` and `bd comments add` each read their body text a
little differently, and all three applied a SILENT precedence when a caller
gave two sources: positional text plus --stdin or --file resolved to the flag
and dropped the positional half with no message. In every case we could find,
the dropped half was the text the caller meant.
One textSources layer now owns the reading for all of them. Naming two sources
is an ERROR ("cannot combine positional text ... with --stdin") rather than a
precedence question; --file content is passed through verbatim, matching every
other file-input flag (--body-file, --design-file, --reason-file), while stdin
keeps trimming the trailing newline a shell appends; and an explicitly-set-but-
empty text flag counts as a source via cobra's Changed, so `--response ""` gets
"cannot be empty" rather than "no text provided".
`bd human respond` joins them: its response can come from positional args,
--response, --file or --stdin, so --response is no longer a required flag.
`bd human dismiss` takes its reason positionally as well as via --reason, and
both accept trailing free text (`<id> [text...]`) the way `bd comment` does —
a second argument is text, never a second id. The "Response: " prefix and the
shared Dismissed close reason are now formatted ONCE, before the proxied
dispatch, so the two backends cannot shape them differently; the same move
lets the proxied comment entry points take resolved text instead of re-reading
the flags themselves.
`human stats` classifies dismissals by that shared Dismissed prefix instead of
a case-insensitive substring search for "dismiss", so the writer and the
classifier cannot drift. Beads closed earlier with a lowercase or mid-string
"dismiss" move from the Dismissed count to Responded; CHANGELOG carries the
note.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzyFzAJkmN3MGhXSo9AMwQ
* fix(human): bring `human list`/`stats` to bd list parity via IncludeAllTypes
`bd human list` built its own two-field filter: a label match plus whatever
--status the caller typed, unvalidated. So it showed closed beads by default
where `bd list` hides them, answered a typo'd status with a silent empty list
instead of an error, and — because it never went through the shared builder —
could not be told what a default listing is SUPPOSED to hide.
It goes through workapi.BuildListFilter now, which gets it the done/frozen
status exclusions, the pinned default, status validation against built-in and
custom names, comma-separated sets, and "all". `human stats` counts the same
universe (--status=all) through the same path, and the proxied side calls
openAndPrepare rather than hand-building a second filter, so the command
cannot mean one thing in direct mode and another behind the proxy.
What it must NOT inherit is the type suppression: a `human` label is an
explicit request for a person's attention, and this command is the only place
a person sees it, so gates, wisps, infra beads and templates all show. That is
the new issueops.ListRequest.IncludeAllTypes — the union of IncludeTemplates,
IncludeGates, IncludeInfra AND IncludeEphemeral. Both the type exclusions and
the PLANE decision now live in one applyTypeSuppressions that the flag skips
whole, so it decides the ephemeral plane too rather than lifting three type
knobs and leaving `bd human list` blind to human-labeled wisps. A suppression
added there in future is lifted here without touching this command.
Two pinned fixes fall out of parsing the status selector ONCE instead of
comparing the raw string in three places:
* --status=all no longer forces Pinned=false. "all" promises every status;
the string comparison never matched it, so the one selector that hides
nothing kept hiding pinned beads. The golden case status_all_keyword is
re-recorded (Pinned false -> null) and TestPinnedDefaultBySelector owns
the rule now.
* --status=pinned,closed no longer excludes the pinned beads it asks for —
the same comparison missed every multi-status set.
--ready is deliberately unaffected: it forces status open and otherwise
ignores the selector, so an "all" the query never applies must not have a
pinned side effect either.
BEHAVIOR CHANGE, called out in CHANGELOG: scripts using --status=all as a way
to list everything EXCEPT pinned beads will see pinned beads appear. Add
--no-pinned to keep the old result.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzyFzAJkmN3MGhXSo9AMwQ
* fix(human): let proxied respond/dismiss answer wisps, and stop the phantom label warning
Two gaps in the proxied twins of `bd human respond`/`dismiss`, both of which
`bd human list` showing every bead type now makes reachable:
WISPS. The pair resolved through proxiedRequireIssue and then wrote the
comment and the close against the DURABLE tables. A human-labeled wisp is a
bead a person can see in `bd human list` — so it has to be one they can also
answer. Resolution goes through workapi.GetIssueOrWisp and the write side
branches: AddCommentToWisp/CloseWisp for the ephemeral plane, unchanged calls
for the durable one, still inside the single RunTx the proxied write
convention asks for.
THE ADVISORY WARNING FIRED ON A FAILED LOAD. The missing-'human'-label warning
read labels with the error discarded, so a label load that FAILED was
indistinguishable from a bead with no human label, and the user was told the
label was missing when nothing had been checked. The result now carries
labelsKnown, and a failed load simply warns nothing.
NOT salvaged: the post-commit close-hook firing this branch originally carried.
It was written when each proxied call site hand-wired its own hooks; main has
since moved firing onto the unit-of-work plumbing (uow.NewNotifyingProvider,
bd-opisf), which buffers during the transaction and drains after Commit. The
proxied human close already fires its hooks — a hand-wired call here would
fire each one twice. The reason is recorded on closeHumanProxied so the next
reader does not re-add it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzyFzAJkmN3MGhXSo9AMwQ
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
`bd show` printed "DEPENDS ON" on an issue that another supersedes, and
"BLOCKS" on its replacement instead of the obvious "SUPERSEDED BY" and
"SUPERSEDES." "BLOCKS" was doubly wrong since supersedes takes no part
in ready-work calculation.
Only blocks, parent-child, related and discovered-from had verbiage of
their own; duplicates, replies-to, tracks, attests and every other type
fell through to a `default: blocks` fallback, while conditional-blocks
and waits-for do block but lost the distinction.
One table now names each type from both ends of its edge and all three
renderers share it.
Type names have no consistent left-to-right reading, so each entry takes
its direction from the command that writes the edge: `bd supersede old
--with new` stores (old, new), making the source the replaced issue.
Same bug elsewhere, also fixed: `bd show --refs` headed groups with the
bare type name, so a canonical issue announced itself as the copy; `bd
dep add` and `rm` said "depends on" whatever the type; `bd dep list`'s
batch header said "X depends on:"; `bd list --deps` had supersedes and
conditional-blocks backwards; and the dependencies doc described
supersedes in reverse.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Relations is one of the facade methods the ext-api-store audit lists with no
wire operation, and it is the one gc's infra-over-http read surface cannot do
without: `bd dep list`'s dependents view has no other direction-aware wire path,
because EdgeReader is outgoing-only. This is that operation. The role, its
contract and all three legs already exist; this slice wires them.
Spec first, then `make api-gen`, then the handler.
IT IS A SUB-RESOURCE OF THE ISSUE, and the argument is ELEMENT IDENTITY rather
than a claim about what the dependency collection answers with — getDependencyTree
answers hydrated TreeNodes, so "everything under /dependencies is about edges"
would be false and is not said. What decides it is narrower and checkable: the
rows here are the SAME pinned struct `GET /v0/beads/issues/{id}` already carries
under `dependencies` and `dependents`, so this operation is that pair,
standalone, direction-parameterized and type-filterable, and it belongs on the
resource whose members it publishes: `/v0/beads/issues/{id}/related`. The route table's first sub-resource: the
segment is a LITERAL after a single-segment wildcard, so pattern and specPath
agree and the claim row's exception does not apply. It collides with nothing —
`/v0/beads/issues/{id}` is a different whole path, which is what ServeMux
matches on, and the custom-method dispatcher is POST-only and one segment
shorter.
The consequence is stated in the document rather than left to be discovered:
the length of `items` is a NEIGHBOR count and not an EDGE count, because a
target that is an `external:` reference or another repository's id has no far
end here and is silently not a neighbor. The same edge IS a row on
`GET /v0/beads/dependencies`. That single observation is what separates the two
operations, and the proxied test asserts both halves of it against real Dolt.
THE ANCHOR-BOUND maxItems GATE DOES NOT APPLY. The facade signature is
single-anchor — one `RelatedRequest.ID`, not a slice — so there is no question
to bound at 100 the way the three dependency-collection reads bound theirs, and
`TestSpecDefaultsMatchSharedConstants`' three-op loop is deliberately untouched.
The other side of single-anchor is the 404: those reads report a miss per anchor
because failing would throw away the ids that were found, and here there is one
anchor and nothing to preserve. `getDependencyTree`'s operationCodes row,
unchanged, is this one's.
TWO-PLANE, AND BOTH HALVES ARE REAL. The neighbours are collected from
`dependencies` AND `wisp_dependencies` and hydrated from `issues` AND `wisps`,
so a durable anchor's `in` answer includes the wisps that depend on it and a
wisp id is a legal ANCHOR. Resolved from the bodies, not assumed, and pinned
against real Dolt: a durable anchor with one durable and one wisp dependent
answers two, and the wisp element carries `ephemeral` — which is what catches an
implementation that spanned the edge tables and hydrated one issue table.
VALIDATION STAYS IN THE ROLE, on `dependencies:count`'s terms rather than
`issues:count`'s. Relations has two bodies and every accessor calls
ValidateRelatedRequest, so its refusals are reachable over the wire: the handler
forwards `direction` raw and classifies on the sentinel, naming the parameter by
re-asking the validator's own questions in its own order. Only two of the
validator's three refusals are reachable — the path bound turns an unusable id
into the 404 a real miss gets, which is why there is no `id` arm in the picker
and why the tests say so.
Census: +1 spec path, +1 schema (`RelatedIssues`, unpinned for `EdgeCounts`'
reason — the element under it is the pinned one), +1 route row, +1 capability
(`issues.related`, hand-edited only in the document's vocabulary — `Capabilities()`
is derived and untouched), +1 `Op*` const, +1 `operationCodes` row, +1 required
`Config` field with its `sourceRoles`/`roleSourceNames`/accessor lines, +1 `bd
serve` binding. No code was minted: every problem code on the row is inherited.
THE "STEP WITH NO NUMBER" IS NOW A BUILD ERROR, and this is the first role to
measure that rather than assert it. #5539 landed the serveRoleSource subset while
this was in review, so `IssueRelations` joins that interface and both `cmd/bd`
stubs are COMPELLED to declare it — omitting either is
*serveRolesStore does not implement serveRoleSource (missing method IssueRelations)
in the file that has to grow the method, checked both ways. Counter and
GraphCounter had to be FOUND, the second only by a full-package CI shard; this
one could not be missed. Both stub comments are rewritten to say so: the
promoted-method-on-a-nil-embed narrative is history now, not instruction, and on
the identity stub the surviving load-bearing fact is PLACEMENT — the accessor
sits at depth 1, shallower than serveStubRest's nil store, so it shadows the
promotion and the assertion can see it. Swept for a third stub site reaching this
path: serve_registered_backend_test.go reuses serveIdentityDoltStore and a real
embeddeddolt.Open, so there is none. A drive-by one-liner beside all that:
timedProvider gained the `uow.GraphCounterSource` compile-time assertion #5536's
accessor landed without.
One arm was DELETED after measurement. failRelatedErr shipped with an explicit
`storage.ErrNotFound` case, mutating it out left every case in the package green
— ClassifyError already carries that row, so the 404 travels through the one
shared mapping — and a green arm named for half the contract is worse than no
arm. The ErrValidation arm is the opposite: deleting it turns every refusal on
this operation into a generic 500, and both measurements are recorded at the
site.
Evidence, six mutations. The picker's arms collapsed reddens the four direction
cases and nothing else; the ErrValidation arm deleted reddens all five refusal
cases; `items` as a nil slice reddens the empty-array case; the path bound
dropped reddens the impossible-anchor case; the dependents read narrowed to
`dependencies` and the hydration narrowed to `issues` each redden the two-plane
case against real Dolt at 1-of-2. A seventh, a json tag on types.Issue.RowVersion,
reddens the no-revision case — and TestWireTagBijection too, which the test now
says out loud.
Rebased onto #5539 (06b0dffb2). Fable review: APPROVE, zero blocking findings
— the reviewer re-ran every mutation, probed the router live (an issue literally
named "related" does not shadow the detail read), and confirmed the
environmental-failure set name-identical to pristine main. Its one INFO, the
overclaimed placement rationale, is the paragraph rewritten above.
Gates: `make api-check` a no-op, `go build ./...`, `go vet ./...`, `gofmt -l`
clean, `internal/httpapi` + `internal/telemetry` + `internal/storage` +
`internal/storage/uow` (the nine-minute parity run) green, and
`BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/ -run
TestProxiedServerServeRelatedIssues` green against real Dolt in five cases. The
pre-commit hook's `go run golangci-lint@v2.10.1` downgrades the toolchain to
go1.25 and refuses this go1.26.5 module outright (ga-2ltro.13), so the
CI-pinned binary was run by hand — `golangci-lint run --new-from-rev=origin/main`,
0 issues — and this commits with --no-verify citing that bead.
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* refactor(serve): make the next role a compile error in the serve stubs
serveIssueRoles took a whole storage.DoltStorage, so the test stubs that
stand in for a store satisfied it the only affordable way: embed the
interface and leave it nil. Every accessor a stub had not declared then
arrived as a promoted method on a nil interface — a segfault inside role
extraction, not a compile error.
It has landed twice in one PR cycle, both on GraphCounter. First in
serve_source_test.go, then in serve_store_identity_test.go, where no local
-run pattern names the test and only a full cmd/bd shard found it.
So the function now asks for serveRoleSource: the accessor subset it
actually reaches, which a whole store still satisfies. Both stubs declare
that subset and assert it, and the store they must still BE — the
decorator chain takes one, and backends.Backend.Open returns one — comes
from an embed one level deeper that their own accessors shadow. Adding a
role to the loop is now:
cannot use (*serveRolesStore)(nil) ... does not implement
serveRoleSource (missing method GraphCounter)
ADDING_AN_ISSUEOPS_ROLE.md's "step with no number" listed these two stubs
among the surfaces to grep for by hand; it now says this pair is taken
care of and the rest still are not.
Swept the embed pattern across cmd/bd for a third instance reaching this
path: none.
Bead: ga-c3g45
* fix(httpapi): check the batch closer, the one role with a positional result
internal/httpapi has checked wrappers for Reader, BatchCreator, Lifecycle,
Claimer and Releaser, but the batch closer went out unwrapped — on the
reasoning that CloseBatchResult is a value and its issue pointer is
forwarded rather than dereferenced. True, and it is why there is no panic
here to prevent. What it left unguarded is the thing this role owns that
none of the others do: an array the client reads POSITIONALLY.
Two shapes reached the wire as answers rather than faults, and they fold
at different scopes:
- An outcome count that does not match the request cannot be walked
against the caller's items at all. Projected anyway it reports one
item's answer under another item's id for the rest of the array,
silently, inside a 200. Whole-batch 500, never a partial projection —
checkedBatchCreator's refusal exactly.
- An outcome carrying neither a row nor a refusal has no honest wire
shape: `code`'s absence promises `issue`, so it projects as a success
with no row, which is the shape closeOutcome's `default` branch
already refuses to produce. Folded into THAT item, because this batch
is not all-or-nothing — the survivors have committed, and failing the
request would hide durable closes.
The fold corrects a copy: the outcomes slice is the role's, and one that
answers from a prepared result would otherwise carry this server's
correction into everything it hands back afterwards.
No wire shape changes and no spec changes; make api-check is a no-op, and
the error classification order in failBatchClose is untouched.
Bead: ga-39tl5
---------
Co-authored-by: Julian Knutsen <ci@beads.test>
The role landed facade-only (#5485) with neither front door, and its own doc
said why: the numbers it answers are already printed through internal/workapi's
detail seam, and the wire operation "lands in the graph-counts wire slice".
This is that slice. What it buys is the question the stored-edge read cannot
ask — how many edges, in a direction the caller names, without materializing a
row.
Spec first, then `make api-gen`, then the handler.
IT IS NOT THE LISTING COUNTED, and the operationId says so. `listDependencies`
is OUTGOING ONLY and takes no direction; this one REQUIRES a direction and
answers about either end, so the two agree on a number at `direction=out` and
nowhere else. `countDependencies` would have promised they always agree, so it
is `countDependencyEdges` — and the path is `/v0/beads/dependencies:count`,
the collection-level custom method `ready:count` and `issues:count` already
spell, on the collection whose listing it sits beside. Both segments are
literal, so pattern and specPath agree; it collides with nothing, because
/cycles, /blocking and /tree all carry a separating slash and ServeMux matches
whole segments.
THE ANSWER IS PER ANCHOR, which is the shape difference from the listing beside
it. An edge row carries its own `issue_id`, so that operation flattens; a number
does not, so folding these would produce a total nobody asked for and lose the
per-issue answer every caller wants. `anchors` is an ARRAY in first-mention
order — the role's doc says a map would be the one result shape a wire
operation cannot carry without inventing a key vocabulary, and that the
request's order is part of the answer. `count` and `missing` are both emitted
on every entry: 0 is the COMMON answer here and `missing` is the only thing
that tells a typo from an issue that genuinely has none.
THE IDS CAP IS THE ONE THE LEAF ASSIGNED TO THIS SLICE. EdgeCountRequest.IDs
says there is no size cap on the role, that the bound belongs to the WIRE, and
that "the graph-counts wire slice sets it". It is 100 — the same number, from
the same `maxDependencyAnchors`, as the stored-edge read on the same
collection, because the two bound the same thing and a client holding both
should not have to learn two numbers. And it is now PINNED: nothing kept the
document's maxItems and the Go constant together on ANY of the operations that
read it, so TestSpecDefaultsMatchSharedConstants grew a case covering all
THREE — including listBlockingAnnotations, which enforces the same constant and
declares the same maxItems and predates this slice entirely. Pinning only the
two operations this slice touched would have gated the copies that happened to
be in front of me and left the oldest one free to drift.
VALIDATION STAYS IN THE ROLE, which is the opposite of `issues:count` and for a
reason the checklist spells out. That operation refuses its one enum at the edge
because NO role refusal is reachable; here the role has ONE body on all three
legs with ValidateEdgeCountRequest inside it, so four refusals are reachable —
a missing or unrecognized direction, a status beside direction=out, an empty id,
an unusable type. The handler classifies on the sentinel and names the
parameter by re-asking the validator's own questions IN THE VALIDATOR'S OWN
ORDER, which is part of that function's contract. Two cases carry two offenders
each and assert the FIRST is named; swapping the picker's arms reddens them.
The role's own semantics — sum-not-distinct, both dependency planes, the status
asymmetry, the missing-anchor rule — are CITED, never restated. A second telling
is a second thing to keep true.
Config gains a required GraphCounter field on the checklist's terms, `bd serve`
binds it beside the issue counter, and TWO stub stores gain the accessor — the checklist's "step with no number", found exactly as it
predicts: the read role's hook decorator RECURSES, the recursion lands on a
stub that embeds a nil DoltStorage, and the panic arrived the moment `bd serve`
began binding the role. storage.RoleFiresHooks needs nothing, because that
table takes only decorators that WRAP.
THE SECOND STUB IS THE ONE WORTH RECORDING, because it says what the checklist's
warning actually costs. serve_source_test.go was found by running the tests a
role slice thinks to run; serve_store_identity_test.go's serveIdentityStore has
the same nil embed and was found only by the FULL-SUITE macOS shard, because no
test name in that file matches a pattern anyone would guess
(TestServeAnswersFromTheStoreTheRootCommandOpened). #5508's own message recorded
this same gap — "I ran the proxied shards by name and never the whole cmd/bd
package" — and I repeated it. The rule that actually holds is the checklist's:
GREP FOR THE EMBED, NOT FOR THE INTERFACE. Both stubs are now swept, and a
tree-wide sweep for a type declaring Counter() without GraphCounter() finds no
third.
The structural fix is deliberately NOT in this slice: as long as these stubs
embed the whole storage.DoltStorage interface, every future read role is a
promoted method on a nil interface — a segfault rather than a compile error.
Replacing the embed with an explicit role-accessor subset would turn the next
one into a build failure, and that is its own change.
ONE NICE PROOF OF #5508's WORK: the capability list needed ZERO hand edits in
Go. routes.go's diff is a table row and nothing else — `Capabilities()` is
untouched — and TestSpecCapabilityVocabularyMatchesTheRouteTable passes, which
means the derived list picked `dependencies.count` up on its own. The only hand
edit was the document's own prose vocabulary, which is precisely what that gate
exists to demand.
Evidence. Three mutations, each red in the right place: the picker's arms
reordered reddens the two-offender cases and nothing else; `omitempty` on
`count`/`missing` reddens the per-anchor case (which decodes through pointers
for exactly that reason); the anchor cap as `>=` reddens the at-the-cap
assertion that the two refusal cases could not see. A fourth, drifting the
spec's maxItems to 50, reddens the new shared-constant pin.
Real Dolt through a real `bd serve`, five cases: out and in over an ASYMMETRIC
fixture (2 and 3, so neither direction can pass by coincidence) with the
outbound count reconciled against the rows `GET /v0/beads/dependencies`
returns; the TWO-PLANE SUM, where a durable anchor depended on by one durable
issue and one wisp counts 2 across `dependencies` and `wisp_dependencies` — a
count reading one table answers 1 and looks fine; a missing anchor reported
beside two found ones, both of the other two carrying 0 so only the flag
separates them; the status filter narrowing inbound edges by the dependent's
stored status, an unrecognized status counting 0 rather than failing, and the
400 naming `status` beside direction=out; and a repeated anchor answered once.
Gates: `make api-check`, `go build ./...`, `go vet ./...`, `gofmt -l` clean,
`golangci-lint run --new-from-rev=origin/main` on the touched packages (0
issues), `internal/httpapi`, `internal/telemetry`, `internal/storage` and
`internal/storage/uow` (the nine-minute parity run the checklist names), and
`BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/ -run
TestProxiedServerServeEdgeCounts` green against real Dolt. The pre-commit hook's
`go run golangci-lint@v2.10.1` fails on this host with a toolchain mismatch
unrelated to this change, so the hook's contents were run by hand before
committing with --no-verify.
Stacked on feat/httpapi-read-revision (#5535); rebase after that merges.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Every `expected_version` on this surface is composed from a token some response
carried, and until now every response that carried one was a WRITE. A client
that wanted to read a row, decide from what it said, and write it back under a
guard had to precede its first guarded write with a write it did not want to
make — or guard on nothing, which is the lost update the whole family exists to
refuse. Five places in the document said "no READ on this surface publishes a
revision yet" and named the member a read would have to agree with. This is that
member.
Spec first, then `make api-gen`, then the projection.
GET /v0/beads/issues/{id} PUBLISHES IT; GET /v0/beads/issues DOES NOT, and the
reason is not payload. Measured against a 20,482-row production export the
member is 28 bytes on a 1449-byte median row — under 2%, and the list rows are
already fat enough that a token would disappear into them. The reason is that
`types.IssueWithCounts` is ALSO THE INTERCHANGE ROW: `exportIssueRecord` embeds
it in both `bd export` and the auto-export that flushes a git-tracked
`issues.jsonl`, and the token is re-minted by every write, so publishing it on
that element would put a per-write-random value into a file whose whole value is
that it diffs when something meant something. That is precisely the loss
`types.Issue.RowVersion`'s `json:"-"` is there to prevent, and a wire member
cannot opt out of it — the list element and the export element are one pinned Go
struct. `types.IssueDetails` has neither problem: nothing interchanges it, and
`workapi.BuildIssueDetails` is its ONE production construction site against
IssueWithCounts's SIX, which is the second half of the argument. (Six
field-populating non-test literals: export.go, export_auto.go, search.go,
claim_next.go, ready_work_counts.go and uow/ready_claimer.go. The `[]*T{claimed}`
spellings in ready.go and ready_proxied_server.go are slice literals wrapping a
role-built element, not independent places to forget a field, and they are not
counted.) A token field on a struct built in six places is silently 0 wherever a
site forgets it, and 0 is a LEGAL token (the migration-0054 backfill), so
nothing — no test, no client — can tell a forgotten one from a legacy row.
So the projection moved onto the canonical type behind ONE DOOR. types.Revision
is set by types.NewIssueDetails and nowhere else, because a struct literal with
an unset token publishes a wrong answer that looks exactly like a right one.
THE DOOR IS WRITTEN INTO THE DOCUMENT, not just into this description. A later
revision that wants the token on the list rows needs a list element that is NOT
the interchange element, and the listing's own prose now says so — together with
the rule a client needs meanwhile: model the absent member as ABSENT, never as
0, because 0 is a real token and a client that defaulted would compose guards
matching exactly the rows it is most dangerous to be wrong about.
THIS DELETES A PARITY DIVERGENCE RATHER THAN ADDING ONE. `bd show --json` has
published this token for as long as guarded writes have existed, through a
CLI-only wrapper, and `readsParityAllowlist` waived the difference with the note
"if the token is ever needed over HTTP, extend that surface and delete this
entry". The wrapper is gone, both front doors read the member off the one detail
seam, and the allowlist is now EMPTY — kept declared, because an empty allowlist
is a stronger statement than no allowlist.
The wire council's outstanding fix rides along, because it is the same member
family: `ApplyItemResult.revision` and both apply-item `expected_version`
members gained the DECODE-AS-64-BIT clause every other revision-bearing member
already carried. The batch spelling is where it bites hardest — a token
corrupted by an IEEE-754-double parser refuses the WHOLE plan rather than one
write.
Evidence. Four mutations, each watched to go red in the right place and only
there: the constructor stopping projecting reddens all three legs; the seam
regressing to a struct literal reddens the workapi pin ALONE and leaves the
httpapi case green, which is why both exist; `omitempty` reddens exactly the
legacy-zero arms; and adding the field to `types.IssueWithCounts` reddens the
new list case while leaving `TestRowVersionNeverSerialized` GREEN — the separate
unset field carries none of the forbidden spellings — and reddens
`TestWireTagBijection` only while the document has not caught up. That measured
pair is written into the new case's own comment, because it is why the case is
not redundant with either gate.
Real Dolt through a real `bd serve`: read the token, guard a patch with it, watch
it land; watch a write move it; watch the read and the write agree on the new
one; watch the stale guard 409 with `param: expected_version`; re-read and watch
the retry land. The same loop on `close`, and the ephemeral fallback — where the
token is a different column on a different table and the failure mode is a zero
rather than an absence.
Gates: `make api-check`, `go build ./...`, `go vet ./...`, `gofmt -l` clean,
`golangci-lint run --new-from-rev=origin/main` on the touched packages (0
issues), the internal/types, internal/workapi, internal/httpapi and
internal/storage package runs, the byte-pinned `cmd/bd/protocol` corpus, and
`BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/ -run
'TestProxiedServerServeReadRevision|TestProxiedServerServeReadParity'` green
against real Dolt. The pre-commit hook's `go run golangci-lint@v2.10.1` fails on
this host with a toolchain mismatch unrelated to this change, so the hook's
contents were run by hand before committing with --no-verify.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Publish GET /v0/beads/issues:count, with the role's whole filter surface
issueops.Counter is the role the ADDING_AN_ISSUEOPS_ROLE checklist was derived
from, and it was the last read role on the store with no HTTP half. `bd count`
reached it; nothing over the wire did. A client that wanted a number had to
page a listing and count the rows, which answers a DIFFERENT question: a
listing hides closed, pinned, template and gate rows and a count hides none of
them, so the two disagree by every one of those exclusions.
Spec first, then `make api-gen`, then the handler.
ONE OPERATION FOR BOTH OF THE ROLE'S METHODS. `group_by` selects the bucketed
shape, because the two ask the same predicate of the same set and the grouped
response is the scalar response PLUS `groups` — one schema with an optional
member, not two contracts under one id. That is the opposite of `events:watch`,
which is a sibling operation because it differs in media type, lifetime, limits
and capacity; here nothing differs but one member.
The full CountRequest surface is published — 23 filters plus the dimension —
because a wire narrower than the role would make an HTTP-backed store answer
questions the native one can and it cannot. The two parameters that could
mislead are documented rather than smoothed over: `status` is ONE status here
where the listing takes a comma-separated set, and `include_infra` changes four
things at once (merges the wisps tier, drops templates, drops gates, routes an
infra type to the ephemeral tier).
One finding worth the ledger: NO ROLE REFUSAL IS REACHABLE from this operation.
issueops.Counter has exactly one ErrValidation — ValidateCountGroup's unknown
dimension, since BuildCountFilter cannot fail — and the handler refuses that
dimension at the edge, so every `invalid_argument` here is the transport's. The
spec, the operationCodes row and a test all say so, and
TestCountGroupEnumMatchesTheRolesVocabulary is what keeps it true: a dimension
this server accepted and the role refused would arrive as an unclassified 500.
The wisp-plane question is answered against real Dolt rather than asserted: a
default count is DURABLE ONLY and `include_infra` merges the ephemeral tier in,
both agreeing with `bd count`'s own numbers through the same role.
Config gains a required Counter field on the checklist's own terms — a Config
missing it would bind, advertise issues.count and nil-dereference on the first
request — and `bd serve` binds it beside the ready counter.
Gates: `make api-check`, `go build ./...`, `go vet ./...`, `gofmt -l` clean,
`golangci-lint run` on the touched packages, `--new-from-rev=origin/main`, and
the windows/no-cgo cross-lint the PR workflow runs (0 issues each), plus
`BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/ -run
TestProxiedServerServeCount` green against real Dolt. The pre-commit hook's
`go run golangci-lint@v2.10.1` fails on this host with a toolchain mismatch
unrelated to this change, so the hook's contents were run by hand before
committing with --no-verify.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Derive both capability expectations from the route table
The count slice went red on a proxied shard for a list nothing about counting
had changed: cmd/bd's servedCapabilities is a second hand-written copy of the
capability vocabulary, and the thirteen checks a stacked PR runs do not include
the proxied shards. The literal was updated in internal/httpapi and missed out
here — which is the failure mode the list's own comment describes ("the
server-mode copy sat at four entries through every expansion since"), happening
again for the same reason.
Both literals are now derived from routeTable, which already carries capability
and implemented and already feeds the spec-vocabulary check.
The argument the old comment made against deriving — "comparing the server
against its own derivation would pass for any surface at all" — is true and is
answered somewhere better. TestSpecCapabilityVocabularyMatchesTheRouteTable
compares the derived set against the `capabilities` prose in openapi.v0.yaml in
BOTH directions, and that paragraph is written by hand for the operation being
added. So content still has an independent oracle, adding an operation still
costs a deliberate edit, and the edit is now in the document a client reads
rather than in two test files nobody does.
internal/httpapi re-derives from the table rather than calling Capabilities(),
which the handler already calls: Capabilities() == Capabilities() is green for
every surface including an empty one. A non-empty guard and a sortedness
assertion on the wire keep it from passing vacuously; reversing the sort turns
it red.
Two assertions written for this were DELETED after mutation testing showed they
cannot fail — a stub-advertises-itself loop and an implemented-gate check, both
green against the mutations they were named for, because the expectation
re-applies the same filter and v0 has no 501 rows to filter. The comment says
so and names what actually holds the gate (TestSpecStatusCodesMatchHandlerTable
fails on any unimplemented row) and the probe that would upgrade it.
Also, from review:
- TestEveryCountRequestFieldIsPublished pins issueops.CountRequest's 23 filters
against the parameters that reach them. A 24th field left unpublished turned
nothing red before, and an unreachable role filter is exactly how an
HTTP-backed store becomes narrower than the native one without anyone
deciding to narrow it. Falsified against a hypothetical field.
- TestCountParametersMatchTheHandler's comment records that its derivation is by
EXECUTION: it sees the names read on the path taken, which is the whole
vocabulary only because countFilters is straight-line today.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Declare Counter on the serve stub store
CI's macOS shard caught what my local runs did not: binding the count role in
serveIssueRoles made TestServeIssueRolesComeFromBeneathTheHookDecorator panic
with a nil dereference.
This is the hazard ADDING_AN_ISSUEOPS_ROLE.md calls "the step with no number" —
every surface that EMBEDS the store gains a new accessor PROMOTED rather than
declared, so the build stays green and the first symptom is a nil dereference in
somebody else's stub. serveRolesStore embeds a nil storage.DoltStorage and
declares only the roles its own test is about; Counter was not one of them.
The count role made it reachable for a reason worth recording: Counter is a
READ, so hook_counter.go RECURSES and hands back the inner surface unwrapped —
and that recursion lands on this stub. A role whose decorator wraps would have
stopped at the wrapper.
The other surfaces the checklist names were checked and need nothing:
storage.RoleFiresHooks takes cases only for decorators that WRAP, and uow's
notifying provider has declared CounterSource since the role landed.
The gap that let it through was mine: I ran the proxied shards by name and never
the whole cmd/bd package. Running it now shows an identical failure set on this
branch and on a clean origin/main worktree — 25 tests, all collateral from the
package exceeding go test's default 10m timeout on this host.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
bd serve's help says "No authentication and no TLS", and the first half of that
is what stops it being deployed anywhere but a developer's loopback. Two flags
answer it, and both default to the behavior that exists today: a `bd serve` with
no arguments is byte-for-byte the server it has always been.
AUTHENTICATION
--auth-token-file names a file of accepted tokens, one per line, all
accepted. There is deliberately no --auth-token: a credential passed as an
argument is readable by every local user out of ps.
The accepted set is NOT a startup snapshot. It is re-read while the server
runs, gated to at most one stat(2) per second for the whole process, and that
is what makes rotation hitless — write {new,old}, roll the clients, drop old —
and what makes a leaked token revocable inside a second without a restart.
The freshness check runs on the ACCEPTING path too, not only on a mismatch:
a token the operator just deleted still matches the cached set, so a
mismatch-triggered reload would give rotation and never give revocation.
A failed or empty re-read keeps the last-good set and logs the error, so a
writer that truncates before writing cannot lock every client out; the stat
cache is left untouched, so the next attempt re-reads and recovers.
The check sits in route(), on a per-operation authExempt column beside
bypassSemaphore, and runs BEFORE the semaphore — a refusal costs one SHA-256
and can never occupy the database slots authenticated clients are waiting for.
/healthz is the one exemption, because a probe carries no credential;
/v0/beads/context is not, because it reports the repo root, beads directory
and database name. Tokens are compared as SHA-256 digests in constant time,
so the process holds no raw credential and the 401 — fixed detail, via the
staticDetail map — can never echo the one that was presented.
The wire says so: a bearerToken securityScheme, a 401 on every guarded
operation, and a spec-parity test that fails if the route table's exemption
column and the document's security blocks ever disagree. That test is what
makes a NEW operation inherit the 401 in the same commit that routes it.
HOST ALLOWLIST
--allowed-host (repeatable) adds Host values the DNS-rebinding check answers
to. Matching stays exact; there is no wildcard or suffix syntax. Admitting a
name the operator enumerated does not weaken the defense: a rebound page
still cannot make a browser send that Host to 127.0.0.1, and the automation
clients that do send it are not browsers. Without this, a server reached by
any name other than a loopback spelling or the bind address 400s on every
request, which is the first thing a non-loopback deployment trips over.
WHY LOOPBACK BEHAVIOR IS UNCHANGED
Every new field defaults to the value that reproduces the old code path: no
Auth, no extra hosts. A zero-valued Config is the previous server, and the
whole pre-existing test suite proves it — none of those tests passes a token
or a host, and all of them still pass unmodified.
The one deliberate behavior change is at the other end: --allow-non-loopback
now REQUIRES --auth-token-file, escapable only by naming --insecure-no-auth.
Beyond loopback the old default was that reaching the address granted every
read and every claim. The three places that advertised "no authentication" —
the help text, the bind refusal and the flag usage — are reworded, since
leaving any of them would ship a false security statement.
Still no TLS, deliberately and unchanged. A non-loopback bind now warns that
the token and the issue data travel in plaintext and belong inside a trusted
boundary; supplying confidentiality is the deployment's job.
Agent-Signature: claude-opus-5
Co-authored-by: CI Bot <ci@beads.test>
* Publish the row-version guard on close, reopen and delete
`expected_version` already existed on all three roles — `CloseRequest`,
`ReopenRequest` and, since the deleter slice, `DeleteRequest` — and none of
the three published it. `internal/httpapi/close.go` even carried the reason
in a comment ("a precondition would need a frozen conflict code for
ErrVersionMismatch and a `row_version` on the issue body for clients to
echo"). Both of those landed with `updateIssue`'s guarded members:
`precondition_failed` is frozen, `PreconditionFailed()` exists, and
`UpdateIssueResponse.revision` is the token clients echo. This retires the
comment by making it false.
Spec first, then `make api-gen`, then the handlers.
- `closeIssue` and `reopenIssue` take `expected_version` and answer with
`revision`. The guard is checked BEFORE the idempotent re-close and before
the non-done no-op, which is the role's own order; `force` bypasses close
POLICY and never the precondition.
- `deleteIssues` takes `expected_version` under the role's SINGLE-ID rule: a
guard beside more than one DISTINCT id is a 400 naming the member, refused
at the edge so the client gets a member name the role's own ErrValidation
route cannot give it. Duplicates collapse after trimming, matching
workapi.NormalizeDeleteIDs; a blank id is refused first so the arity rule
cannot steal a broken list's answer.
- Every precondition arm is matched TYPED and FIRST. ClassifyError has no row
for ErrVersionMismatch and neither leg wraps it in ErrValidation, so below
those arms all three would answer a generic 500. Verified by mutation.
- `applyInt64Member` becomes `applyVersionGuardMember` and names the member
itself: five call sites, one spelling, and no unparam exclusion.
Two tests changed rather than being added to: reopen's "publishes no conflict
code" is now "publishes no POLICY conflict code", written as an exact set, and
`TestDeleteRequestMembersMatchTheHandler` is new — that handler's member list
was hand-rolled with nothing tying it to the document.
Gates: `make api-check`, `go build ./...`, `go vet ./...`, `gofmt -l` clean,
`golangci-lint run` on the touched packages and `--new-from-rev=origin/main`
(0 issues), and `BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/
-run 'TestProxiedServerServeClose|TestProxiedServerServeDelete'` green against
real Dolt. The pre-commit hook's `go run golangci-lint@v2.10.1` fails on this
host with a toolchain mismatch unrelated to this change, so the hook's contents
were run by hand before committing with --no-verify.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Record the compare-and-set rule where the next handler author will look
Five handlers now match ErrVersionMismatch typed before reaching failErr, and
each said why in its own words. That is five coincidences, not a rule: handler
author #6 reads ClassifyError, finds no row for the sentinel, and concludes the
shared mapping covers it.
State it at ClassifyError instead. That function CANNOT build a
precondition_failed — the refusal echoes the value the REQUEST guarded on and
ClassifyError is handed an error alone — so any operation publishing
expected_version, expected_status or expected_assignee must match the sentinel
typed in its own failure path. Forgetting is not a worse 4xx: neither storage
leg wraps these in ErrValidation, so the miss falls through the default arm and
every guard failure on that operation is a generic 500.
The three handlers this stack added now cite that rule rather than restating it.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* lint: the last US spelling in problem.go
main was red on its own Lint job (misspell, locale US) from two words the
release slice added. `neighbour` has since been fixed upstream; `archaeology`
at problem.go:85 is the one left, and the PR workflow lints the whole tree with
only-new-issues: false, so every open PR inherits the failure until it goes.
Not this stack's breakage, and landed here only because this stack is what it
was blocking. Prose only; no behavior.
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Publish POST /v0/beads/issues:claimNext: take ready work atomically (ga-g3gg8)
A client of this surface that wants the next piece of work composes
`GET /v0/beads/ready` with `POST /v0/beads/issues/{id}:claim`. That
composition is a RACE, and it is the reason this operation exists rather than
a round trip saved: between the listing that offered a row and the claim that
asked for it, another agent claims it — so the second agent earns a 409 for a
row it was correctly offered, and a fleet polling one queue spends its
requests losing races instead of doing work.
`claimNextIssue` publishes issueops.ReadyClaimer, where selection, the
compare-and-set that wins the row, and the hydration of the row that was won
are ONE transaction. The row cannot move between being chosen and being
reported.
THE FILTER IS THE LISTING'S, and not a copy of it. The parameters are decoded
by readyFilters — the same function `listReadyWork` and `countReadyWork` share
— because a claim that answered a different question than `bd ready` shows
would hand an agent work the listing never offered it, and two predicates that
are allowed to differ eventually do. The actor is the only body member: it is
provenance that lands in a column, and this surface has always carried that in
a body, while re-spelling the filter as a body object would create exactly the
second expression the shared decoder exists to prevent.
TestClaimNextAdmitsExactlyTheListingsFilters holds the DOCUMENT to the same
identity, since only the handler is protected by sharing the function.
`limit` is refused BY VALUE rather than left to the unknown-parameter rule,
and the distinction is two different client recoveries. `unknown_parameter`
means "this server does not know that name — version skew, degrade or fall
back", which would be false: it is a name this server knows perfectly well on
the sibling listing. It will not ACT on it, which is `invalid_value`, and the
reason is the role's: a claim delivers the one row it wins however large the
pool it scanned, and the scan must stay unbounded or a window that happens to
be full of rows a racing agent already took reports nothing to claim.
`sort` IS published, unlike on `ready:count`, because order decides WHICH row
a claim writes to where it cannot change a cardinality — and it is sent
explicitly for handleReady's reason, which bites harder here: an empty policy
adopts storage's hybrid fallback, and here that changes the row that gets
written rather than the order rows are printed in.
NOTHING ELIGIBLE IS A 200 WITH `claimed` ABSENT. An empty ready front is the
steady state of a drained queue, not a failure, and a polling agent that had
to classify an error to discover it would be pattern-matching prose. There is
no boolean beside the member and no scan count: a second member carrying the
same fact is a second member that can disagree with the first. This is the one
place the operation differs from `issues/{id}:claim`, which 404s an id that
names nothing — that one was asked about a ROW, and this one was asked a
question whose honest answer can be "none".
It documents no 409 and no 404 at all, and both absences are contract. There
is no id to have missed, and a row a racing agent took is simply not in the
set this claim scanned.
The real-Dolt leg asserts the guarantee a fake cannot express: nine concurrent
claimants against six ready rows win six distinct rows and never the same one
twice. The assertion is on duplicates rather than on timing, so it is
deterministic however the goroutines interleave.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Publish patch.add_labels and patch.remove_labels on updateIssue (ga-g3gg8)
The bead asked for "incremental label add/remove on the wire", noting that
labels are replace-only and that issueops.LabelPatch has Add and Remove. The
trace found the situation is narrower than that and more familiar: the role's
whole algebra IS already wire-expressible — as `labels.{replace,add,remove}`
on `issues:batchApply`'s update item, which has published `ApplyLabelPatch`
since it landed. What has no incremental spelling is `PATCH /v0/beads/issues/{id}`,
whose `patch.labels` is a bare array.
That is #5484's finding again, on the one member it did not close: two
operations for patching one issue, disagreeing about what patching one issue
means. This closes the gap from the same side, and this member is the last of
them.
`patch.labels` KEEPS ITS SHAPE, and that is a constraint rather than a
preference. Nesting it into an object the way `ApplyPatchBody` does would
RE-TYPE a published member, which is the one kind of change this document has
no additive route for — `## Profiles` names re-typing explicitly as not a
tightening, and the only remedies written down are a new optional member or
cutting /v1. So the increments arrive as two flat siblings, which is the shape
`notes` and `append_notes` already use for the same replace/increment pair on
this exact schema.
THEY ARE NOT MUTUALLY EXCLUSIVE WITH `labels`, and that is the difference from
that pair. The role defines an ORDER over all three — replace, then add, then
remove, so removal wins — so a request carrying all three has a defined result
and must reach the role whole. Notes have no such algebra, so there the two
members are a contradiction and are refused. The handler assembles one
LabelPatch in one loop for exactly this reason: a member decoded into its own
patch value would overwrite the others' fields and the last one decoded would
silently win.
The retired premise is worth stating, because it was written down and it was
half right. `patch.labels` said incremental edits were deferred because
"replacement is the only shape whose result the client already knows without a
read-back". That holds for a writer that knows it is alone and fails for every
other one: two agents each adding a tag to one row, each composing a
replacement from a read taken before the other wrote, silently drop each
other's label. `bd label add` and every agent that tags work concurrently are
that caller. The real-Dolt leg is written as exactly that scenario.
The length bound applies to all three members including `remove_labels`, where
a value the column could not hold could never have been stored: it is a rule
about what a label may BE, and the role refuses it there too and writes
nothing, so the edge refuses it where the 400 can name the member and the
index.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Publish POST /v0/beads/issues:batchClose: close many, keep the survivors (ga-g3gg8)
`bd close a b c` is one transaction and one history entry. Over this surface it
has been N calls to `POST /v0/beads/issues/{id}:close`, which is N transactions
and N history entries, with no way for a caller to say it wanted them together.
The request is the transaction boundary, which is the whole reason
issueops.BatchCloser is a role rather than a loop.
IT IS THE ONE OPERATION HERE WHOSE 200 CARRIES REFUSALS, and that shape is the
ROLE's rather than an arrangement of it. An id the batch turns down is skipped
and the survivors commit, because an agent that finishes four of five steps and
mistypes the fifth should keep the four — so a per-item refusal is a RESULT of
the batch, not an error of it. `batchCreateIssues` is the deliberate opposite
and has said so in its own document since it landed: half a created plan cannot
be re-sent without duplicating the half that landed.
The division that falls out is the contract a client codes against, and it is
stated on both sides: a NON-2xx means the batch NEVER RAN, and a per-item
`code` means that item did not land while others may have.
`code` ON AN OUTCOME IS `Problem.code`'s VOCABULARY, restricted to `not_found`
and `not_closable`. A second vocabulary was the alternative and it was refused:
an item refusal and a request refusal are the same question asked at two
scopes, so a client made to learn two spellings would be classifying the SCOPE
rather than the condition. `open_children` keeps both of its readings, and both
are the single close's: present-and-a-count on a success (the number a forced
close bypassed, reported even for an idempotent re-close), and PRESENCE as the
discriminator between the two `not_closable` refusals on a failure, exactly as
on a problem document.
The projection fails CLOSED. An item error no arm recognizes becomes a refusal
carrying the generic code, never a success — because a success with no row is a
shape a client cannot tell from a real close, and a `default` that fell through
would produce exactly that.
NO COMPOSED CLAIM, and the omission is reasoned rather than partial. The role
can claim the next ready issue in the same transaction once the closes land;
publishing that member would need a second, BODY-shaped spelling of the ready
filter vocabulary that `GET /v0/beads/ready` and the `issues:claimNext` landing
beside this one both express as query parameters — and two spellings of one
predicate eventually disagree, which is the reason ReadyClaimer.Filter is the
listing's own request type. A client that wants both sends two requests and
loses the single transaction, which is a real loss and is named in the document
rather than papered over. It is additive later.
The per-item id is bounded HERE, which the single close gets from the
custom-method dispatcher and this operation has no dispatcher to get it from. It
is a 400 rather than a per-item `not_found`, because it is a statement about the
REQUEST and because reporting it as a miss would let a caller map this server's
notion of a well-formed id.
The real-Dolt leg asserts the claim the whole shape rests on: a batch whose
middle item names nothing still commits the two either side of it, each with its
OWN reason — read back through the CLI rather than off the response the batch
composed. A fake cannot state that, because it holds no rows to roll back.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Scope the label members' no-op wording to the labels (ga-g3gg8)
`add_labels` and `remove_labels` each said a no-op edit "reports
`changed: false`". That is the RESPONSE's member and it describes the whole
patch, so it is only true of a request whose sole content was the no-op edit —
a request that also moved a title changed the row and reports true.
They now say what is true of the member: the edit changes no labels. The
response's reading is stated once beside it, as a fact about the patch.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Fix two misspell findings inherited from the release merge (ga-lzcuv)
`main` is red on Lint as of 294af94be2, and both findings are prose from that
squash rather than from anything in this branch:
internal/httpapi/problem.go:85 `archaeology` -> misspell wants `archeology`
internal/httpapi/problem.go:591 `neighbour` -> misspell wants `neighbor`
`.golangci.yml` sets `misspell.locale: US`, so both are real under this
repository's configuration. They are fixed here because this branch merges next
and would otherwise carry a red Lint of its own making no changes to earn.
`neighbour` takes the US spelling. `archaeology` is REWORDED to `excavation`
rather than respelled: `archeology` is the spelling the linter wants and the
one most readers would read as a typo, and the sentence loses nothing by not
having the word in it. Rewording is the only one of the two options that leaves
the comment saying what it meant without looking wrong.
Neither is reachable from the local pre-commit hook, which fails at
golangci-lint config load in this environment before it analyses a file.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
bd label list-all fetched every issue via SearchIssues, which already
hydrates Issue.Labels in bulk, then discarded that hydration and called
store.GetLabels once per issue. In embedded Dolt mode each of those calls
enters withConn, opens a short-lived OpenSQL connector, starts a
transaction, runs a wisp-routing probe plus the label SELECT, and closes —
2N extra round trips for data already in memory. On a live 455-issue
embedded database that turned a ~10s scan into a 33.75s command, and one
run was killed at 104.31s with "context canceled while getting labels for
mr-qji", the error string from exactly this loop.
Count from issue.Labels instead. Output is unchanged: same unique labels,
same counts, same sort order, same JSON shape. The helper takes a
labelListAllSearcher interface exposing only SearchIssues, so the per-issue
lookup cannot come back without widening that interface; a gate test
asserts the method set.
Benchmarked against a real embedded Dolt store: 200 issues, 5,960ms/op
before vs 64.3ms/op after (92.6x); 20 issues, 478.7ms vs 27.3ms (17.5x).
This is the same defect pattern that #1586 removed from the RPC handleList
path; the proxied-server path was already bulk.
Fixes#5325
Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of mwotton
* Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv)
The claim has had a wire since v0 and its inverse has had none. `bd unclaim`
is a subprocess for every client of this surface, and a release-if-current has
no route at all — so the one verb that frees stranded work is the one verb an
automation client cannot reach.
`releaseIssue` publishes issueops.Releaser whole: `actor`, the
`expected_assignee` compare-and-set, and `force`. The response carries the
issue, `changed`, and `revision` — the last for `updateIssue`'s reason, and
one of its own: a release REMINTS the row's token by design, so a caller that
guarded its next write on a version read before the release would miss, and
this member is the only place the new one exists.
THE REFUSAL CODES ARE THREE, AND ONLY ONE IS NEW.
`already_claimed` is the ownership fence — an unforced, unguarded release by
an actor that is not the holder. That is `updateIssue`'s assignee-fence
situation exactly, down to having two bypasses, so it takes that operation's
code rather than a fourth spelling of "a live foreign owner refused your
write". Like there, no `assignee` member: the fence refuses without naming the
holder, so absence means re-read the row.
`precondition_failed` is the guard, inherited from the same operation and
carrying the same members for the same reason — `expected_assignee` is the
REQUEST's value, and there is no `actual_assignee` beside it, because the
refusal rolled its transaction back and ErrAssigneeMismatch is a bare sentinel
that formats the holder it saw into prose. There is no ClaimConflictError
equivalent to read, and this surface does not scrape its own messages.
`not_releasable` is minted, covering ErrNotReleasable and ErrNotClaimed.
`not_claimable` is the nearest existing code and covers a superset of the same
statuses today, but the coincidence is not a contract — the release transition
is pinned to {open, in_progress} by releasableStatus and the claim's
eligibility is a separate predicate — and for the unheld half the reuse would
be an outright lie: an open, unassigned row is the most claimable row a
workspace has. The two conditions share ONE code with no discriminating
member, which is the narrow choice rather than the convenient one: neither
sentinel carries a typed observation, and splitting later is an ADDITION the
document already tells clients to tolerate, while merging two published codes
is the removal that breaks the wire.
IT IS NOT IDEMPOTENT, and the wire says so rather than inventing an answer the
role refused to give. An unheld row is 409, never a 200 carrying
`changed: false` — that value is one no role produces (ReleaseResult.Changed
is true on every non-error answer), and it would report one answer for "I
released this twice", "a reaper beat me to it" and "nothing ever claimed it",
because the post-state is anonymous and nothing is left on the row to tell
them apart. A client for which "already released" is the ordinary path maps
the code to success in one line it writes knowingly.
`expected_assignee` disagrees with `updateIssue`'s same-named member in
exactly one place, and the schema says so: the empty string is a 400 here
rather than a guard meaning "expected unassigned". It also documents what the
comparison ACTUALLY does — separator-insensitive over runs of `.`/`_`/`-`,
per actorMatches, and nothing else forgiven — rather than repeating the role
doc's "byte for byte", which the implementation stopped being at ga-5ksp5.
failRelease matches all four sentinels TYPED and BEFORE its ErrValidation and
ErrNotFound arms. None of them is wrapped in ErrValidation on any leg, so
below a generic arm every one would have been a 500 on every leg.
The real-Dolt leg asserts the property a fake cannot: after every refusal it
reads the row back through the CLI, so "nothing was written" — and above all
the CLAIM SURVIVING a wrong-holder refusal — is a fact about the stored row.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Fix the release document's three review findings (ga-lzcuv)
The mint stands; what the review caught is that the document was written as
though `not_releasable` meant one thing, and it means two.
THE SAFETY ONE. "A caller for which 'already released' is the ordinary path
treats that code as success" was true of the sentinel it was written against
and is FALSE of the code it shipped as. `not_releasable` also covers the
status refusal, and a row parked in a status this workspace configured is
refused WHILE STILL ASSIGNED — so a reaper following that sentence books a
claim as dropped while it stands, held by an agent that is already gone, with
nothing left to free it. That is the stranding this operation resolves ids
across both planes to prevent, reintroduced through the refusal vocabulary
instead of through the id.
It now says the opposite, in the operation description and again on the 409:
on `not_releasable`, READ THE ROW. The row carries the one fact that separates
the two — an assignee, or none. One extra request on an uncommon path is the
honest price of one code rather than two, and the handler's `detail` says so
too, since that is the string an operator actually reads.
THE ACCURACY ONE. CodeNotReleasable claimed "neither refusal is typed", which
is wrong and misleads the person who eventually splits it: ErrNotClaimed and
ErrNotReleasable are two distinct typed sentinels and failRelease holds both
in one case arm, so a split is a mapping change in that arm — no archaeology
and no prose-scraping. What is genuinely unavailable typed is the OBSERVATION
each refusal made, the status seen and the emptiness of the assignee, which is
why the code carries no extension member. That is a narrower claim than the
one the comment made, and it is the true one. The merge is recorded as what it
is: a deliberate start-narrow choice, kept because adding a code later is the
reversible direction.
THE WIDENING. The 200 now states it: the transition is defined over `open` AND
`in_progress`, so a row already open that STILL HOLDS AN ASSIGNEE is released
here — the state a partial write or an out-of-band status edit leaves behind,
and one a release-if-current guarding on `in_progress` did nothing for and
reported no error about. A client porting such a guard has to know that before
it ports one.
Beside it, the code-to-outcome mapping a release-if-current client wants, so
that mapping is written against a documented fact: `not_releasable`,
`precondition_failed`, `already_claimed` and `404` all mean "no release
happened, and that is not an error" — `(false, nil)` to a client spelling it
as a pair. With the reading that pair does NOT license, stated beside it,
because it is the same reading the safety finding is about: it means no
release happened, never that the claim is gone.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
BatchCreateOptions.OrphanHandling had four modes and one behavior. Every
production call site passed OrphanAllow (or left the field at its zero
value, which took the same branch), so CheckOrphan returned (false, nil)
on every path it could reach — after paying a SELECT COUNT(*)
parent-existence probe on every hierarchical-ID create to feed a switch
whose only reachable arm ignored the answer.
OrphanStrict and OrphanSkip were reachable from exactly one conformance
case, testAuditCreateOrphanHandling, which existed to execute them.
OrphanResurrect was never a branch at all: it shared the default arm with
OrphanAllow, and the "auto-resurrects missing parents from database
history" behavior its doc comment described left with the JSONL sync
layer. internal/beads' TestImportWithDeletedParent still asserted that
removed behavior; it goes too.
This removes the type, the four constants, the field, CheckOrphan and its
call site, the backend package's alias and re-exports (a breaking change
to a published package, signed off by the owner), the dead
ImportOptions.OrphanHandling, and the import.orphan_handling row in the
yaml-only-key test — replaced with import.unlisted-key, which keeps the
"import.* is exact-match, not a prefix namespace" assertion the row was
actually providing.
The behavior that remains is what OrphanAllow always did: a hierarchical
create whose parent is missing is accepted, and the child's auxiliary
counter row is skipped because it would have no owner
(TestReconcileChildCountersSkipsMissingParent pins that). The wasted
query is gone from the create path.
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(bd): canonicalize actor==assignee comparisons in unclaim.go and AuthorizeAssigneeTransferWithPools
Follow-up to ga-wzl83, which canonicalized the two pure-Go validators in
internal/validation/issue.go but explicitly left out two higher-risk sites.
UnclaimIssueInTx / UnclaimIssueIfAssigneeInTx compared actor/expectedAssignee
to the stored assignee verbatim, both in a Go-side precheck AND in the SQL
UPDATE's WHERE clause -- so canonicalizing only the Go side would not have
fixed `bd unclaim` end-to-end. Replaced the `assignee = ?` SQL predicate with
a `row_lock = ?` CAS against the RowVersion read moments earlier: every
ownership/status/started_at mutation always rewrites row_lock (the documented
freshRowLock invariant in lease.go), so this detects the exact same race the
old predicate did -- and more (status/started_at races too) -- without
embedding a spelling-sensitive string comparison in SQL.
AuthorizeAssigneeTransferWithPools (the single fence both the DBTX and
unit-of-work backends evaluate, per its own doc comment) compared
before.Assignee to request.Actor and to request.Patch.Assignee.Value
verbatim, so a caller naming the current holder under a different layer's
identity spelling was wrongly fenced as a stranger.
Both fixes reuse the canonicalActor/actorMatches shape from ga-wzl83, kept as
a small package-local duplicate in issueops (internal/storage/issueops
importing internal/validation would invert the layering).
Verified: new cross-spelling cases in aggregate_authorize_transfer_test.go
and new end-to-end cases in unclaim_embedded_test.go /
unclaim_conditional_embedded_test.go (against a real embedded Dolt backend)
all fail with the exact bug-report symptom against the pre-fix code and pass
after the fix, with no regressions in the existing suites.
ga-5ksp5
* fix(bd): close the sibling-CAS disagreement gate review flagged on #5439
Review verdict on #5439 was "MERGE AFTER ONE FIX": after this branch's
unclaim.go/aggregate.go fix, bd unclaim --if-assignee succeeds under a
respelled identity while bd update --expected-assignee on the same bead
still fails ErrAssigneeMismatch — the same verbatim actor==assignee defect
(ga-wzl83), left in two more places.
- internal/storage/issueops/update_cas.go:46 (CheckExpectedFieldsInTx) now
compares under actorMatches (package-local, unexported — same package as
identity.go, no new import needed).
- internal/storage/domain/issue.go:643 (ApplyUpdate, the unit-of-work twin)
now compares under validation.ActorMatches. domain cannot import
internal/storage/issueops (issueops already imports domain in several
files — the reverse would cycle), but domain -> internal/validation is
safe (validation depends only on internal/types), so this reuses the
already-shipped validation copy instead of adding a third duplicate.
Two non-blocking asks from the same review, addressed:
- Exported internal/validation's canonicalActor/actorMatches to
CanonicalActor/ActorMatches so domain/issue.go could reuse them (the
reviewer's own point: "an issueops -> validation import creates no
cycle... layering inversion is a style call, not a compile fact" applies
equally to domain -> validation). Also fixed a garbled mid-sentence doc
comment on ActorMatches while touching the file (separate nit from the
same review, on #5438).
- Added a cross-package parity test
(internal/storage/issueops/identity_parity_test.go) that runs the
existing CanonicalActor/ActorMatches case tables through both this
package's local duplicate and validation's exported version, so the two
copies can't silently drift. Mutation-tested: dropped the hyphen
separator from issueops's copy, confirmed the two hyphen-related cases
correctly fail, reverted.
New conformance test (backend/conformance, wired into all three backend
legs) proves the fix end-to-end: an ExpectedAssignee guard now accepts a
different spelling of the current holder and still refuses a genuinely
different identity. Added as a SEPARATE function rather than extending the
existing RunIssueOperationsUpdateConditionalGuardsGateOrdinaryEdits — that
test's later "order-dependent composition" arm depends on the row's
assignee staying exactly "holder" through to the end, which a mid-test
respelling would have broken.
Verification: internal/validation, internal/storage/issueops,
internal/storage/domain(+db,fs,git) all green. New conformance test passes
on embeddeddolt and uow (dolt backend skips locally, no Docker — matches
the existing documented limitation, CI covers it). Broader regression
subset (Update/Claim/Unclaim, 28 embeddeddolt + 22 uow cases) green, no
regressions. go build/vet/gofmt clean.
Filed ga-4ymii for the reviewer's second (also non-blocking) ask: the
remaining verbatim sites at issueops/claim.go (SQL CAS + idempotent
re-claim), its domain/db and domain/issue.go uow twins, and
issueops/lease.go's heartbeat holder check — out of scope for this PR per
the reviewer's own framing ("please file the follow-up").
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(bd): dispatch the respelled-assignee contract case onto the role seam
TestRoleContractCasesCoverEveryContractCase (main, post-dating this branch's
fork point) caught a real gap: the ga-5ksp5 contract case added to this
branch's earlier commit (RunIssueOperationsUpdateConditionalGuardAccepts-
RespelledAssignee) had no roleContractCases dispatch row, so an external
backend running RunRoleContracts would never see it.
The reason isn't a missed row so much as the whole RunIssueOperationsUpdate*
family this case was written beside having been renamed and moved to
RunLifecycleUpdate* in backend/conformance/lifecycle_update_contract.go by
main's "de-stage the hard Lifecycle contracts onto the role seam" refactor,
which landed on main after this branch forked. Ported the case to match:
same logic, adapted to the new fixture's idioms (fixture.Lifecycle.Update
instead of fixture.Operations.Update, lifecycleUpdateRow(...).Priority
instead of a raw SQL assertion, storage.ErrAssigneeMismatch instead of
publicops.ErrAssigneeMismatch, seedLifecycleUpdateIssue instead of
seedClosePolicyIssue) — not a mechanical copy. Also wired it into the three
per-backend TestLifecycleUpdateContract dispatch lists (dolt, embeddeddolt,
uow) beside its ConditionalGuardsGateOrdinaryEdits sibling, so it actually
runs against real backends rather than only satisfying the completeness
guard.
Verified: TestRoleContractCasesCoverEveryContractCase passes; the ported
case passes against embeddeddolt (0.35s) and uow (0.17s) for real, not just
compiles (dolt backend test skips in this sandbox — no Docker); full
backend/conformance suite and repo build clean.
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* Retire bd label's proxied use-case bypass, and lint the door shut (ga-26w10)
cmd/bd/label_proxied_server.go reached uw.LabelUseCase() and uw.IssueUseCase()
— the domain layer BELOW the roles — and hand-rolled, on that side only, a
four-way switch over (add|remove) x (wisp|durable) to pick which of four
use-case methods to call. That switch is the whole bug class the roles exist to
delete: it is a front door deciding which physical plane a row lives on, in a
boolean it can get backwards, with a second implementation of the same command
sitting in the other file.
BOTH ROUTES NOW END AT issueops.Lifecycle AND issueops.Reader.
`bd label add` and `bd label remove` build ONE IssuePatch — Labels.Add or
Labels.Remove carrying every label of the request — and hand it to
Lifecycle.Update once per issue. `bd label list` asks Reader.Get and reads
IssueDetails.Labels, which is already hydrated and already sorted, so there is
no label-shaped read here at all.
THE WISP SWITCH IS GONE, NOT MOVED. UpdateRequest.IssuePlaneOnly stays false,
so the role resolves the plane inside its own transaction. The four
proxied-integration cases that assert at the SQL-table level — a wisp's label
lands in wisp_labels and the durable table stays empty — pass through the role
with no branch in the command.
ONE BODY PER VERB. The three RunEs were each an `if usesProxiedServer() {
return run...ProxiedServer(...) }` in the MIDDLE of a body, with a separately
maintained twin behind it. They are now one line each into runLabelAdd,
runLabelRemove and runLabelList, and the route fork survives in exactly two
places: the accessor (openIssueLifecycle / openIssueReader, the count/purge
shape) and resolveLabelTarget. Resolution stays a front-door job because
GetRequest.ID and UpdateRequest.IssueID are exact by contract — an affordance
that can resolve to a DIFFERENT issue than the caller named has no place on a
contract two front doors share.
THE LINT DENIES internal/storage/uow, NOT JUST internal/storage/domain, and
that is the load-bearing half. depguard matches IMPORTS, and the retired route
called uw.LabelUseCase().AddLabel(...) WITHOUT importing domain at all — a
method call on an inferred type needs no import — so a domain-only rule could
not have seen the bypass it was written for. Reaching a use case needs a unit
of work, opening one needs uow.RunTx, and that is an import. Verified by
mutation: re-introducing the retired call in cmd/bd/label.go fails the rule.
TWO DELIBERATE DELTAS, both stated rather than absorbed.
A multi-issue edit is now 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. The old shape rolled the
good ones back with the bad one. Neither is obviously right — the new one
attributes each edit to its own issue and lands what it could, the old one was
atomic — and the atomic shape is expressible on the facade today as
issueops.BatchApplier with one update item per issue, which is the follow-up
this notes rather than smuggles.
The proxied route's resolution failure lost its "label added: " prefix, which
named a write the command never attempted: resolution now happens before the
role is even asked for. The direct route's message is the one both routes keep,
per the CLI's documented behavior.
SCOPE. `bd label list-all` and `bd label propagate` stay where they are: no
role answers "every distinct label in this workspace", and propagate is a
search plus a fan-out that needs the same batch question the atomicity note
above names. Both still name types.IssueFilter, so `label` stays on
.golangci.yml's forbidigo exception list and the count above it is unchanged —
this slice closes the DOMAIN door, not the filter one, and says so at the rule.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Honor --dolt-auto-commit batch on the role route
CI caught the one thing this migration loses by construction, and it is worth
naming rather than folding into the parent commit: transactHonoringAutoCommit
implemented batch mode by BLANKING the commit message it handed
RunInTransaction, and a role cannot be told that way — it creates its Dolt
version commit inside the storage layer. The deferral has to be said on the
CONTEXT, which is what issueOpsContext exists for and what every other
role-routed write already does (cmd/bd/update.go, cmd/bd/close.go).
Pinned by TestEmbeddedDirectCommitPathsBatchAutoCommitDoesNotAdvanceHead's
label_add case, which went red on the parent commit with "label add advanced
HEAD in batch mode" and is green here.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Close the in-package route past the label guard, and finish the deltas list
THE DEPGUARD RULE OVERCLAIMED, by the same finding it was written from. cmd/bd
is ONE PACKAGE, so proxiedOpenReadUOW (cmd/bd/show_proxied_server.go) hands any
file in it a uow.UnitOfWork with no import of its own: a label.go calling
proxiedOpenReadUOW(ctx) and then uw.LabelUseCase().AddLabel() compiles and
passed the rule. Measured, not reasoned about. An import-scoped guard cannot
see a bypass routed through an in-package helper, and a guard a reader finds
and stops looking behind is worse than none.
A forbidigo `LabelUseCase` rule now closes it, scoped to cmd/bd/label.go, and
the two are a PAIR: forbidigo names the CALL, depguard names the PACKAGE, so a
third spelling — a helper handing back a use case directly — still trips the
import. Both verified by mutation, one bypass each.
Scoping it cost two config edits the config itself predicted. forbidigo now
holds two rules where its exclusions block said "exactly one ... a second would
need this widened or replaced": every per-path hole in that block was written
for the FILTER rule and names only a path, so it silently opens both. One of
those holes covers cmd/bd/label.go — which still names types.IssueFilter for
list-all and propagate — and would have exempted the very file the new rule
exists for. That entry is now scoped by `text:` to the filter message; the
others name no such file and are left alone rather than churned.
THE DELTAS LIST SAID TWO. THERE ARE FOUR, and the two additions are both
improvements, which is exactly why they were easy to leave out:
- a DUPLICATE ADD now writes nothing. ApplyLabelPatch computes the target set
and returns Changed false when it equals the existing one, where
tx.AddLabel recorded an event and a version commit unconditionally;
- the `provides:` REFUSAL now precedes id resolution on the direct route, so
a caller that typo'd an id and reached for a reserved label is told about
the label rather than sent to fix an id that was never going to be labeled.
And the N-updates delta was missing its two consequences. Under
`--dolt-auto-commit on`, the DEFAULT, it is N version commits and not only N
history entries; batch mode still makes zero. Partial application is
acceptable, and the argument is idempotence: ApplyLabelPatch no-ops on an
unchanged set, so a retry is a no-op on the ids that landed and does the rest,
and a partial batch CONVERGES. The atomic shape is
issueops.BatchApplier.ApplyBatch with one ItemUpdate per issue carrying this
same IssuePatch — named, in this branch's ancestry, and blocked only on a
cmd/bd accessor of its own.
Also: commandDidWrite.Store(true) moved below the error check it contradicted.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Refuse kv.* point reads on the settings role and stop printing them
The `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, and only the ENUMERATION was filtered: a caller naming an exact
key still got the value back from GetSetting. That is not a smaller hole
than the enumeration was. `bd remember` derives its key from the content it
stores, so the keys are guessable, and the walk-around is one request to
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.
The point read now answers a `kv.` key exactly as it answers a key nothing
ever stored: the echoed key, an empty value, a nil error. Indistinguishable
from absence on purpose — this role has no ErrNotFound to give, and an
error of any kind would confirm the guessed key to the caller. The row is
not touched, and no read reaches the store at all.
The refusal lives in internal/workapi beside FilterSettingsEnumeration,
where both WorkspaceConfig bodies already reach for the enumeration rule,
so the three legs inherit one decision. Both filters now decide with
workapi.KeyIsOnTheKVPlane, which is the single statement of where the plane
boundary runs.
`bd config show` gets the same rule (bd-klko9). Its database section reads
GetAllConfig raw rather than through the role, so it inherited neither
filter, and it prints values in FULL because it is the operator's
provenance view — every stored memory went into every terminal and pasted
bug report that ran the command. Nothing replaces the view; `bd kv list`
and `bd memories` are the surfaces that own those rows.
The writes are deliberately untouched: SetSetting and UnsetSetting still
take a verbatim `kv.` key, which keeps the escape hatch for a wedged
memory, and a write discloses nothing.
RunWorkspaceConfigPointReadRefusesTheKVPlane pins it on all three legs. It
reads the config table out of band around the refusal, because "the row is
there and the read refuses it" has to be a different fact from "there is no
row", and it asserts a settings key still reads back so a role that
answered "" to everything cannot pass. Reverting either half of the
production refusal turns it red on dolt, embeddeddolt and uow.
bd-rfwtv, bd-klko9
* test(memory): move the proxied leg onto the new settings-plane contract
The proxied memory journey asserted that `bd config get kv.memory.<key>`
returns the memory content, with a comment calling it "visible via bd
config get". That is exactly the behaviour this branch removes, so the
case was pinning the old contract from a shard that does not run locally
-- which is why it stayed green until CI reached it.
It now asserts the new one: the point read answers as an unset key does,
and the content does not appear in the output. The rest of the journey is
untouched and still proves the memory is readable through the surfaces
that own it -- `bd memories` lists it, `bd recall` returns it
byte-for-byte -- so this is the proxied leg of the same firewall the role
contract pins, not a weakened assertion.
Also records in the CHANGELOG what the change does NOT buy. `bd serve`
has no authentication and serves every memory in full through
/v0/beads/memories by design, so this is plane hygiene -- keeping user
data out of the routes that get republished into agent transcripts -- and
not a confidentiality boundary against anyone who can reach the port.
---------
Co-authored-by: Review Sim <ci@beads.test>
Four small truth-restoration changes, none of which alter behavior.
Retire TestImportWithDeletedParent (internal/beads/beads_integration_test.go).
It asserts a "[RESURRECTED] placeholder parent" behavior that left with the
JSONL sync layer: no implementation writes that marker anywhere at HEAD, so
the assertions cannot pass on any backend. Verified live against a dolt
sql-server with -tags=integration,gms_pure_go: unskipped, it dies at setup
(dolt.New: database "testdb_..." not found) before reaching an assertion.
The `encoding/json` import it was the only user of goes with it.
Delete ImportOptions.OrphanHandling (cmd/bd/import_shared.go). No literal
sets it and no path reads it — importIssuesCore hardcodes
storage.OrphanAllow on the BatchCreateOptions it builds. The struct carries
no tags and is never marshaled, and the historical `import.orphan_handling`
config key is gone. Nothing else in the orphan-handling cascade is touched
here; that removal is a published-surface decision and needs its own
sign-off.
Name ErrValidation in Claimer's leaf doc (issueops/claimer.go), in the same
words the other sixteen roles use. All three implementations already answer
it for an empty Actor or IssueID, and
RunClaimerRefusesIncompleteRequestsAndAnAbsentIDWithoutTouchingState asserts
it on all three legs; its SPEC GAP note recorded the doc's silence and is
updated to match.
State Commenter's history cost exactly (issueops/commenter.go): one durable
comment records EXACTLY ONE entry, an ephemeral one records none.
RunCommenterRecordsExactlyOneHistoryEntry was tightened from a range to an
equality at one and RunCommenterCommentOnAWispLandsOnTheWispThread pins the
ephemeral half at zero, both on all three legs, so the shipped contract was
already stricter than the published prose.
Co-authored-by: Review Sim <ci@beads.test>
`PATCH /v0/beads/issues/{id}` documented four exclusions and gave one
reason for all of them: status belongs to close/reopen/claim, assignee to
the claim's compare-and-set, metadata deserves its own design pass,
parent_id is a graph edit in patch clothing — and keeping them out was
"half the reason this operation documents no 409 at all."
That held until `issues:batchApply` landed, whose update item publishes
`status`, `assignee`, both force flags and all three `expected_*` guards,
and says of itself that it patches one issue "under PATCH's rules plus the
preconditions and force flags that operation deliberately does not
publish." Two operations for patching one issue, disagreeing about what
patching one issue means. This closes the gap from the other side.
`patch` grows `status`, `assignee`, `parent_id` and `metadata` — the last
reusing `ApplyMetadataPatch` and `applyMetadataPatch()` themselves, not a
second spelling of the replace/merge/set/unset algebra. Beside `patch` the
request grows `expected_version`, `expected_status`, `expected_assignee`,
`force_close_policy` and `force_assignee_transfer`.
The conflicts follow the members, and every one is inherited rather than
invented: close policy's `not_closable` from `status`, the assignee fence's
`already_claimed` from `assignee`, the graph's `dependency_cycle` and
`dependency_exists` from `parent_id`, and `precondition_failed` from the
guard trio. failUpdate matches all of them TYPED and BEFORE its
ErrValidation and ErrNotFound arms, which is the correctness of this
change: the reparent and precondition bodies return raw on one leg and
wrapped on another, so without that order one condition would have answered
500 on the unit-of-work leg and 400 on the store legs.
`UpdateIssueResponse` gains `revision`. `expected_version` guards an opaque
token, `types.Issue.RowVersion` is json:"-" so no read on this surface
publishes one, and a guard whose token no response carries is a guard a
caller cannot fill. A read-modify-write loop now composes its next
expectation from the value the write answered with.
A `patch.parent_id` naming the issue itself is refused at the edge — the
child is the id in the path, so the request contradicts itself with no
state read, and the two legs of the role disagree about which error they
raise for it. A new parent that names nothing stays a 400, conforming to
dependencies:add; the 404 remains the path id's alone.
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
`bd serve` could create issues only in batches, and only nine members of
one. `POST /v0/beads/issues:batchCreate`'s item has no `status`, no
`sender`, no `metadata`, no `ephemeral`, no `no_history` and no `id`, so a
caller composing a real row could not use it — the R1 lesson
`issues:batchApply` already learned when its create item published the
whole create vocabulary instead.
This is the single-issue create over `issueops.Lifecycle.Create`, on the
plain collection POST the batch deliberately left free by spelling itself
as a custom method. Its issue members are `ApplyCreateItem`'s exactly,
minus that schema's two plan-only members, plus the edge vocabulary that
operation moves into `dep_add` items: `parent_id`,
`inherit_labels_from_parent`, `dependencies` (typed edges, `reverse`
included) and `waits_for`.
Two conflict codes, both inherited rather than invented. `already_exists`
arrives with the explicit `id`, which the batch publishes none of.
`dependency_cycle` arrives with `parent_id` and `dependencies[].reverse`:
the first places the new row in a hierarchy the caller cannot see, the
second writes an edge INTO the id being minted, and between them a create
can close a cycle for the first time. There is no 404 — a target that
names nothing is a statement about the request body, not about a resource
this operation was asked to address — and no `dependency_exists`, because
the only type conflict a create can raise is between two edges of the same
request.
checkedLifecycle.Create stops passing through. It could, while no handler
on this surface reached it; handleCreateIssue writes *result.Issue onto the
wire, so a provider-supplied role answering nil with a nil error was a
panic on a live server.
`created_at`, `created_by`, `spec_id`, the await/molecule/event plumbing
and `IDPrefix` stay unpublished; the PR body carries the decision and the
evidence for each.
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Add issueops.BatchApplier: one plan, one transaction
A heterogeneous, ORDERED list of creates, updates, closes and edges applied
as one durable act. Each of BatchCreator, BatchCloser and DependencyEditor is
one verb repeated, so a caller that needs two of them needs two transactions
with a window in between; this role's unit is a PLAN.
The role, the two bodies, both decorators and the accessors on every
implementer. The wire half and the conformance contract land beside this.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Close the empty-commit-message hole a no-op batch could open
ApplyBatchCommitMessage now reads the write as well as the result. The counts
are ItemResult.Changed, which is what a CALLER observes; a request can still
write a durable row with every count at zero — a same-type edge re-add
rewrites that edge row's metadata, a re-close can settle blocked state. An
empty message for one of those is an unlabelled Dolt commit on the store legs
and a rollback of a real write on the unit-of-work leg.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Give BatchApplier the contract its two bodies justify
Thirty-nine cases over three legs and TWO independent bodies — the store legs
share issueops.ApplyBatchInTx, the unit-of-work leg cannot reach it, and the
contract header says so rather than claiming three backends agree.
The end-gate case is the one that could not have been written before: every
edge in it is legal when it is written, and only a re-validation against the
closure the whole request produced refuses the pair.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Publish batchApply on v0, and delete batchCreate's false promise
The spec first, the types from it, the handler against the types. The item
union is a TAGGED single-shape object rather than a oneOf, because the
document's x-go-type doctrine forbids composition keywords; the create item
publishes sender, metadata, status, ephemeral and no_history, none of which
batchCreateIssues has — which is why no measured caller could use that one.
The wire result stays lean: ids, changed and a revision. The hydrated
snapshot on the Go contract is what the completion hooks consume, and hooks
never fire on this surface.
OQ2: batchCreateIssues' description claimed a dependency target could name an
earlier item of the same batch. It never could — the server mints the ids and
a wire item has no name — so the paragraph is deleted rather than qualified.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Partition the two new dependency probes on the recorder's surface
The gate halves BatchApplier re-runs are repository PROBES — an ancestry walk
and a reachability walk — so recordingDepUC declares neither and the parity
test has to say so out loud rather than let embedding answer for it.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Teach the proxied topology's capability golden about batchApply
The one expectation stored as data outside the package whose gates would
otherwise have caught it — which is what its own header warns about.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Restore the CAS hook case, mint 409 already_exists, and stop over-claiming
Three fixes from review.
The rebase that brought MetadataCAS in left `case *hookMetadataCAS:` with an
EMPTY BODY: a Go type switch does not fall through, so RoleFiresHooks answered
FALSE for it and #5473's Listen refusal was silently disarmed. The compiler,
vet, lint and CI all pass on that. The case is restored and — because it had no
precondition of its own, which is why nothing caught it — serve_source_test now
pins CAS the way it pins the other four, with its peel assertion.
An occupied explicit create id becomes 409 already_exists rather than 400. The
body is well-formed and stays well-formed; what refuses it is state the client
must READ, and recovery is to look at that state. A dead 409 retires for free
where a narrowed 400 breaks clients.
Two headers claimed all three legs share the store body — every clause false,
one citing the contract header as agreeing when it says the opposite — and the
plan file gave a placement reason that is MetadataCAS's, not this role's. The
end-gate claim in ADDING_AN_ISSUEOPS_ROLE.md is narrowed to the true thing: the
two LEAF checks are shared, the orchestration around them forks.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Give the scheduling-edge set one definition, in types
Four packages walked {blocks, conditional-blocks, parent-child} under four
names — isSchedulingEdge, isSchedulingDep, isSchedulingDependency, and the
isApplySchedulingEdge this branch added as the fourth. Adding a fifth
scheduling type was four edits with nothing to catch a missed one.
It goes in internal/types rather than the issueops leaf the review named,
because internal/storage/issueops imports internal/storage/domain, so domain
cannot import back and two of the four copies would have survived there. Beside
the Dep* constants themselves, every walker reaches it: nine call sites, one
definition, one edit for a fifth type.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Add issueops.MetadataCAS: compare-and-set over one metadata key
The one coordination primitive missing at every layer. Everything the
metadata plane holds is written through Lifecycle.Update, which has no way
to say "only if", so every caller that needs a guarded write composes a
transaction, a read and an update by hand — and each one has to get the
composition right. Gas City emulates it client-side with RunInTransaction +
GetIssue + UpdateIssue for exactly that reason, and the comment it left
behind names the gap: "the upstream storage layer exposes no
conditional-UPDATE ... WHERE primitive".
The role is a state transition stated as a pair. Expected is the key's value
before, Value is its value after, and nil on either side means the key is
ABSENT there: a conditional create is (nil -> value), a conditional delete
is (value -> nil), and a caller that can take a lease can return it to the
state its own acquire tests for. Equality is canonical, so a caller cannot
lose a swap to its own formatter; numbers compare as their source literal,
because decoding through float64 equates two int64s past 2^53 and that is
the silent false match a compare-and-set exists to prevent.
A MISMATCH IS AN ANSWER, not an error: Swapped false, Current carrying the
value that refused it, nil error. That is the one place this diverges from
PROPOSAL-cas-conditional-update.md, which specifies a typed error and a loud
non-zero exit for the assignee/status guards. Its argument is a CLI one — a
swallowed refusal in a shell script is the bug class it was written for —
and a non-zero exit is the front door's enforcement, which the HTTP handler
here still owes and pays. The role's designed caller is a retry loop, for
which a lost race is the ordinary path, 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.
All three legs share one body (internal/storage/issueops), so this is one
reading plus two wrapper checks rather than three backends agreeing. The
wrapper check earned its keep: the unit-of-work leg rolled an ephemeral swap
back, because the shared body reported "no durable tables changed" and that
leg's commit message is what commits the SQL transaction as well as what
versions it. MetadataCASWrite now carries the two facts separately.
The HTTP half lands with the role per the 2026-08-05 scope decision:
POST /v0/beads/issues/{id}:casMetadata, spec first. A lost race is a 200
carrying swapped:false, so the operation has no conflict code; an omitted
`expected`/`value` member means absent and a member holding null is a value,
which is why the handler reads raw members.
No bd command yet: the primary consumer is an embedder, and a CLI front door
is additive. No .golangci.yml entry, for the reason memoryops gives — the
body is an …InTx function no front door can reach.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Review: read Current from the row, and let a client read a present null
Two shape fixes, both of which would have been expensive to change after
anyone depended on them.
A *json.RawMessage wire member cannot READ a present null: encoding/json
nils the pointer before UnmarshalJSON runs, so a generated client decoding
{"swapped":false,"current":null} gets the same value it gets for an omitted
member — and on this operation those mean opposite things. A retry loop
against a null-valued key would read "absent", swap with expected omitted,
mismatch, and livelock on a stream of 200s. x-go-type-skip-optional-pointer
makes the member a bare json.RawMessage, which is an Unmarshaler and
receives the literal; the wire is unchanged in both directions, which is
exactly why nothing else catches the regression, so the decode is now
pinned. nullable: true beside it, for the validating gateway in front of
somebody's server.
The number rule was defended in three places as protecting int64s past 2^53
from a float64 round-trip. It protects nothing: the metadata column decodes
through float64 itself — measured, 9007199254740993 stores as ...992, 1.0 as
1, -0.0 as 0, 1e300 as three hundred and one digits. The false justification
is gone from all three sites and replaced with what the probe actually
showed, plus the guidance it implies: compose an Expected from a previous
Current, and prefer a string for a coordination token.
That guidance was not true yet, because Current was the REQUEST's bytes
rather than the row's — so "what you get is what a later read sees" was
false, and a loop feeding Current back compared its own spelling against the
substrate's forever. Current is now re-read inside the deciding transaction
on every path. One extra SELECT, one statable invariant.
Three contract cases, each watched to fail: Current is the column's bytes
and a Current-driven loop converges (mutant: answer from the plan);
the history entry names the request's actor, counted per actor because
created_at is second-granularity and an ORDER BY decided this case on a coin
toss when it was first written (mutant: stamp a constant); a wisp swap
writes no durable event row, which two layers had been holding by
coincidence with nothing asserting either.
Also: the serializer-omits-null footgun in the spec (an absent `value` is a
DELETE, and Jackson/Pydantic/omitempty all omit nulls by default),
canonicalizeForContract's own float64 blind spot named in the coverage
paragraph, and the leaf now says corrupt stored metadata is an untyped error
— a 500 — because the request was well formed and the issue exists.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Close the three capability holes CI found, and one my sweep could not
All three are the same shape: a surface that loses the new role silently,
and none of them is reachable from the package tests I ran locally.
internal/storage/uow's notifying wrapper is the important one. Its
recordingIssueUC inherited CompareAndSetMetadataKey from the embedded use
case, so a swap through a notifying unit of work recorded nothing and the
hook the DoltStorage chain fires for the same write was lost. Its
notifyingProvider did not answer MetadataCAS at all, so a caller's type
assertion simply stopped matching and the wrapper dropped the capability
along with its hooks. Both are now declared, and the recorder reads the
use case's own "a row write landed" rather than inferring it from the
request — which is strictly better than what the hook decorator can do, and
snapshots anyPlane because this role resolves a wisp id itself.
cmd/bd's serveIdentityStore is the second stub store to nil-panic on the
promoted accessor, after serveRolesStore in the same commit. And
serve_proxied_integration_test.go carries a SECOND hardcoded capabilities
golden, whose own comment says two literals that must match are one literal
— it was right, and it was still missed.
My local sweep ran the metadata-cas contract on all three legs but not the
whole internal/storage/uow package, which takes nine minutes; that is where
the parity guards live. Ran it whole this time.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: name the step with no number — the surfaces that EMBED
A new accessor arrives on every embedder promoted rather than declared, so
the build stays green and the first symptom is a nil dereference in somebody
else's stub. Four such places caught this role after its own slice was
green: RoleFiresHooks, both halves of uow's notifying wrapper, and two
cmd/bd stub stores. Grep for the embed, not for the interface — and run
internal/storage/uow whole, because the parity guards live there and the
package takes nine minutes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
bd worktree create promises an isolated checkout, but it previously trusted git worktree add and continued even if the newly created tree already had modified or untracked files. That can silently sweep unrelated changes into an agent branch.
Add an immediate git status --porcelain=v1 check after worktree creation and fail before .gitignore or permission follow-ups if the created tree is dirty. The error includes the porcelain output so the caller can see exactly what made the checkout unsafe.
Validation: go test ./cmd/bd -run 'Test(EnsureCreatedWorktreeCleanRejectsDirtyWorktree|RunWorktreeCreateFailsWhenCreatedWorktreeIsDirty|AddToGitignore|GitCmdInDirSuppressesHooksViaGitConfig)$'; go test ./cmd/bd -run Worktree
Co-authored-by: Verify <verify@local>
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
`--set-metadata` takes ONE key=value per flag, and `update` is variadic over
issue ids. So `bd update ID --set-metadata a=1 b=2 c=3` binds only `a=1` to the
flag; `b=2` and `c=3` become positional issue ids. They fail to resolve, but
`a=1` is still written — a silent 1-of-N write that a caller cannot distinguish
from a full write. #4726 made the command exit nonzero on the unresolved
positionals, but the partial write still lands and the exit code alone does not
tell a script which pairs were dropped.
No issue id contains '=' (the flag-value form is the only source of one), so a
'='-bearing positional is unambiguously a mis-typed flag value. Refuse it up
front, before any write path (direct or proxied), naming the offending pair and
the correct repeated-flag form. This prevents the partial write entirely rather
than only reporting it after the fact.
Fixes#5247
Co-authored-by: Ben Younes <2910651+ousamabenyounes@users.noreply.github.com>
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
GET /v0/beads/events:watch holds a text/event-stream response open and emits
each committed mutation as it lands, so a consumer learns about a write when it
happens instead of on its next interval. It is a SIBLING of the paged read, not
a mode of it: `follow=true` would have given one operationId two media types,
two lifetimes, two limit rules and two capacity stories, and a client generated
from the document could not have described either.
THE CURSOR IS STILL THE CONTRACT, which is what makes this cheap to publish.
The server keeps no per-consumer state and remembers no subscription; a stream
is the `since` reads a poller would have performed, performed on its behalf
against the same ReadEventsJournalPage through the same read-only cursor. Every
event carries `id: <seq>`, so the checkpoint a client holds while streaming is
the number it would have held while polling, and `Last-Event-ID` — the header a
browser's EventSource resends by itself — takes exactly the value `since` takes.
That header WINS over the parameter, because the client that sends it did not
choose to: an EventSource reconnects to the URL it was built with, so honoring
`since` there would replay every record since the consumer started, on every
reconnect, forever. A nonempty unparseable one is a 400 naming the header rather
than a silent fallback, which would start a stream somewhere the client did not
ask for and never tell it; an EMPTY one means "no id yet" and defers to `since`,
because a client that always sets the header sends it empty on its first
connect and refusing that would break the request the header exists to serve.
Delivery is at-least-once against the client's own checkpoint: exactly once and
in order within a stream, duplicates only across a reconnect. No engine or
storage change — this consumes the poll read path.
EVERY REFUSAL IS DECIDED BEFORE THE FIRST BYTE — validation, the disabled 409,
the flush check, the stream cap, and then the first read, which is what turns a
pruned-past cursor into the paged read's own 410 rather than a 200 that
immediately reports its own failure. Exactly one failure can arrive after the
status is spent: a prune racing an open stream, emitted as a NAMED `truncated`
event carrying the 410's own body in the same encoding on one line (asserted
against Write's output, not merely agreeing with it), behind a raised `retry`
and followed by a close. Naming only the exception is what lets a bare
`onmessage` consumer treat an unrecognized event as "stop, this is not a
record"; one that ignores it does not lose records silently, it stalls loudly on
connect-time 410s, slowly. The other unreportable failure — a stored payload
that will not encode — ends the stream too, and names its seq in the log,
because it will end every stream that reaches that row and nothing else would
say which one it is.
THREE LIMITS HAD TO MOVE, and the middle one is the trap.
- requestDeadline (60s) does not apply to a streaming row. For every other
operation it is the backstop against a request holding resources forever;
here it would do nothing but sever the stream. Each READ carries a 15s
deadline instead — a liveness budget rather than a database one, since it
also bounds how long a stream can go without a heartbeat and how long it can
ignore a shutdown.
- http.Server.ReadTimeout (30s) had to be cleared per request, BEFORE the
connect read. There is no WriteTimeout on this server — statusWriter rolls a
deadline forward before every write, which bounds one stalled write rather
than a stream, and needs nothing here — but ReadTimeout is a deadline on the
WHOLE request, and net/http keeps a background read running while a handler
writes: the read that notices a disconnect. Its expiry cancels the request
context, so an idle stream would end itself at thirty seconds with no client
involved, and a database wedged during the connect read would be booked as
`client_closed`. Clearing it costs no disconnect detection — a client that
leaves still produces a read error — and a peer that vanishes without a FIN
is reaped by TCP keepalive, which Go's listener enables by default
(measured: 15s idle, 15s interval, 9 probes; ~150s).
- The database slot moves from the request to the read. Sixteen slots and
forty-eight stream places means one slot per open stream would let a handful
of idle consumers starve every other operation for hours with /healthz
green; a stream now takes a slot for the moment of each poll and gives it
back, and slot pressure delays a pass instead of ending a stream.
Streams are capped at 48, SIXTEEN BELOW the 64-connection limit, and the gap is
load-bearing arithmetic rather than caution: LimitListener returns a connection
slot only when the connection closes, which is after the handler returned and
after this counter came down, so a cap at maxConns could never be observed — the
connect that should earn the 503 would never be accepted, and neither would the
poll it is told to fall back to, nor a mutation, nor a fresh-connection
/healthz. The headroom makes the refusal deliverable; `events_watch_admitted`
carries the live gauge on every connect so accumulation is visible before the
cliff. Each stream jitters its own poll phase by ±10%, because consumers
reconnect together after a restart on one shared `retry` and a fixed interval
would march them into a single read burst per second forever. And a graceful
shutdown signals its streams (RegisterOnShutdown) rather than waiting them out;
the loop consults that signal and the client on EVERY pass, including the
draining ones, so a week-old backlog stays cancellable within one batch.
Tests: handler-level over live delivery (mutations land AFTER the connect),
id=seq, heartbeats, Last-Event-ID precedence including a stale header against a
live `since` and the empty-header polarity, the 400/409/410 connect legs, a
prune under an open stream, the cap and its 503, the cap's headroom against
maxConns, backlog drains cancelled by both a hangup and a shutdown, slot release
on every exit, a stream sharing a single-slot semaphore with a paged read, the
flusher refusal, the read-deadline clear and its ordering against the connect
read, jitter spread, and a clean drain with a stream open — all under -race.
Framing is pinned against a record whose payload carries literal newlines, a CR
and a `data:` line of its own. Two e2e legs through a real `bd serve`: mutate on
one connection while streaming on another under a 10s arrival bound, then
reconnect with Last-Event-ID and require the resume, plus the disabled refusal.
Mutated and each caught: the mid-stream truncated event, Last-Event-ID
precedence, the empty-header polarity, the cap decrement, the cap's headroom,
the drain-cancel fast path, the read-deadline clear and its ordering, the poll
jitter, the shutdown exit, and the deadline exemption.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
Implements bd-gq84y — the last outstanding divergence with a caller-visible
consequence. Embedded delete and sweep went from 0 history entries to 1,
matching the other two legs.
It was an accident, not a design. The role port dropped the pre-existing
embedded version commit; the commit that noticed said so outright, and it was
patched at the CLI rather than at the role. So bd dolt log differed by mode, and
since embedded Push does not auto-commit pending, an unflushed role delete did
not replicate.
The contracts absorbed it with an "at most one" range, which is unfalsifiable in
the direction that matters. The investigation recorded the proof: mutating
dolt/deleter.go to drop its commit left the dolt-leg case green. That exact
mutation is now caught, alongside four more, each attributed to the body it
broke and each UNIQUE.
Embedded delete and sweep now split dry-run from mutating, with the mutating
path going through the same post-SQL-commit StageAndCommit publication the
commenter and lifecycle verbs already use. The staged set is schema-derived, so
an existing test guards it rather than a hand-maintained list.
One path did need the compensation being retired: bd prune never called
issueOpsContext, so once the role committed, prune --dolt-auto-commit batch
advanced HEAD on embedded. Verified live, fixed, with a subtest that reddens
when the one line is reverted.
The range was also hiding a fixture defect. Exactly-one was not true on embedded
even after the fix: that kit seeds rows without versioning them, so deleting a
row that never reached history produces no diff and no entry. The case was
measuring a versioned deletion on two legs and an unversioned one on the third —
and on that third it depended on which other subtests ran first, since their
uncommitted seeds were what kept the working set dirty. A new CommitPending hook
makes settling a stated precondition. That is a category this programme had not
hit: not a test that cannot fail, but one that passes for reasons depending on
execution order.
Embedded's entry lands after the SQL commit on a second connection, so the
promise is steady-state exactly-one, not crash-atomic. That is said in the leaf
docs, in both contracts' prose, and beside the code in both stores' bodies.
GET /v0/beads/events pages the durable mutation journal from a caller-held
checkpoint, so a hosted consumer stops shelling out to `bd events tail`. The
journal and its retention contract already landed; this is the consumption
surface for them.
THE RECORDS ARE THE CLI'S RECORDS, and that is a machine fact rather than a
promise. The envelope and its projection moved out of cmd/bd into
internal/eventsjournal, beside the activation and auto-prune logic that already
had to be reachable from two binaries; the spec pins EventRecord to that struct
with x-go-type, pinning.go proves the generator emitted an alias, and the
committed golden fixture now renders through the same function the handler
serves from. A second wire struct in internal/httpapi would have passed its own
tests while quietly shipping a different `ts` shape or a `dep` that appeared
when empty, and the consumer who notices is the one reconciling an HTTP mirror
against a CLI export.
THREE ANSWERS THE DATA CANNOT TELL APART, which is most of the design:
- CAUGHT UP is a 200 with an empty list. "Nothing new yet" is an ordinary
answer about a log, and a poller whose steady state was a 404 would have to
treat this surface's miss vocabulary as its happy path.
- DISABLED is a 409 `events_journal_disabled`. A journal that is off reads as
zero rows and a head of zero — byte-identical to an enabled journal nothing
has written yet — so without this gate a consumer would poll a workspace
that will never emit a record and call itself caught up forever. Activation
is workspace state, so it is resolved by cmd/bd (eventsjournal.EnabledFor)
and handed in; this package resolves no workspace state of its own. A 409
for CodeNotClosable's reason: a statement about state the client cannot see,
which the same request stops earning once an operator changes it.
- PRUNED PAST is a 410 `events_journal_truncated` carrying `since`, `floor`
and `head`. It is the surface's only 410 and it is the right one: those
records existed, were addressable by exactly this request, and were
deliberately deleted — retrying the same `since` can never succeed, which is
what a 404 would wrongly invite. The mapping lives in ClassifyError, keyed
on the typed error with errors.As, so neither database source can forget it;
the code is storage's own constant, so the CLI's `--json` failure and this
body cannot drift to two spellings of one condition.
`head` is why the read seam grew. ReadEventsJournal answers what came next and
cannot answer "keep asking, or wait?", so ReadEventsPageInTx returns the rows
and the counter head from ONE transaction, read in that order — a head taken
first could land below the last row served, which a consumer reads as "past the
end" and stalls on. `bd events tail --follow` keeps the cheaper path: it runs
the truncation decision every second and pays for a head read only in the
ambiguous cases.
The handler holds storage.EventsJournalCursor, a read-only interface, not the
wider accessor the CLI takes. There is no prune, no acknowledge and no
truncate over HTTP: retention stays a workspace decision, and a surface
documented to publish the journal should not be one line from a delete.
EventsJournal is the first CONDITIONAL role on httpapi.Config — required
exactly when the workspace's journal is enabled. A storage backend with no
journal seam is an ordinary backend as long as nobody asked it to record
anything (eventsjournal.Apply takes the same deal at open time), and demanding
it unconditionally refused to start two registered-backend servers that had no
use for it.
`limit` runs 1..10000 defaulting to 1000, and `0` is REFUSED rather than
meaning unlimited as it does on the issue listings: a caller resuming from an
old checkpoint would otherwise ask one process to buffer the whole retained
window. `since` is required — defaulting a missing checkpoint to zero serves
the entire window to a consumer that meant to resume, which arrives as a flood
of duplicates rather than as an error.
Tests: handler-level over both refusals, the caught-up/empty/disabled trio, the
limit bounds and an int64 checkpoint; a storage-level head guard against the
real embedded store; and three end-to-end legs through a real `bd serve` —
mutate over HTTP then read the journal back gapless, prune and meet the 410 then
recover from floor-1, and a disabled workspace refusing. The truncation mapping,
the disabled gate, the window members and the limit ceiling were each mutated
and each failed a test.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
Both features are bd-opisf and they now share a tree. The hooks work wrapped the
unit-of-work provider; auto-prune asks that provider for a capability. This is
what it takes for the two to compose.
THE REAL BUG is the resolution, not the wrapper. eventsJournalMaintenanceRunner
peeled the STORE decorator chain and asserted the provider bare — so behind
NotifyingProvider, which bd builds whenever a hook runner exists and therefore
by default, the assertion matched nothing and retention became a silent no-op in
proxied-server mode. Silent is the word that matters: a workspace whose journal
is never pruned is indistinguishable from one with nothing to prune, and proxied
mode is the topology that journals fastest, because it is the one taking
concurrent writes through a long-lived server. Resolution now peels
uow.UnwrapProvider the same way it peels storage.UnwrapStore.
The wrapper ALSO forwards the two capabilities (SetEventsJournalEnabled,
RunEventsMaintenanceTx), and keeping both is deliberate rather than redundant:
the forwarder keeps the wrapper's surface honest, which the parity guards
enforce structurally, and the peel keeps resolution honest against the next
decorator that forgets one. Verified independently — with the peel removed the
forwarder alone carries the proxied end-to-end test, and with BOTH removed the
test fails exactly as CI did.
The parity guards were right to flag the two new provider methods, and their
exemptions say why each is capability plumbing rather than a missing hook: a
retention pass deletes records already committed and changes no bead, and the
journal itself is written at the issueops seam inside the mutation's own
transaction, so everything it records is already covered by the use case that
made the change. EventsJournalUseCase joins the use-case exemption list on the
same argument.
Two test-only repairs the merge exposed:
- The ignored-plane shape simulation cleared exactly one static dolt_ignore
pattern before staging its drops. Three are seeded statically now, so the
journal tables' deletions were unstageable and the ignored-source
dirty-table guard refused the pass ("pending ignored schema migrations
alter pre-existing dirty tables: bd_events_journal, bd_events_seq"). The
production ordering it simulates is correct; the harness had to widen with
it.
- Two events-journal end-to-end files were tagged `cgo` while every helper
they use lives in the `cgo && unix` proxied family, so the Windows package
build lost eight symbols. Windows coverage for a proxied-server end-to-end
test was never intended; the tag now says so.
The auto-prune trigger keeps its place — last in the post-command maintenance
net, in the body, before the store closes — and main.go now states the combined
ordering, because both features land defers in the same teardown and each needs
the other's reason: maintenance must run while the store is still open, and the
hook wait must run after it closes so a hook that shells out to bd can take the
embedded Dolt lock.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen