Commit graph

59 commits

Author SHA1 Message Date
Stephanie Jarmak
7e825441b4
feat(workapi,storage): opt-in Brief projection for the list and ready pages (#5554)
STORAGE LAYER ONLY, per CONTRIBUTING_PR_GUIDELINES.md. issueops.ListRequest
and issueops.ReadyRequest gain Brief; no CLI flag and no HTTP parameter sets
it yet, so no front door's payload changes. The wiring stacks on top.

WHAT IT DROPS is the free-form text: description, design, acceptance_criteria,
notes, payload and waiters are not selected, and the row comes back carrying
types.Issue.IsLitePartial. #5546 measured a 16,051-issue store where
`bd ready --json` returned 454,021 bytes and notes plus description were 76% of
it, on the call an agent makes to decide what to work on. Measured through
issueops.Reader on 100 rows sized from those per-row ratios: 362,301 bytes
full, 24,001 brief, a 93.4% reduction.

THE PRIMITIVE WAS HALF-BUILT AND UNREACHABLE. #3906 landed
types.IssueFilter.Lite, IssueSelectColumnsLite, HeavyDropList,
ScanIssueLiteFrom and Issue.IsLitePartial, then wired filter.Lite into exactly
one place: SearchIssuesInTx, the UNCOUNTED store-backed search. Every read that
answers with IssueWithCounts, which is every --json route of both commands,
both implementations of issueops.Reader, and both HTTP reads, runs the counts
mega-query instead and ignored the field. A request that set it would have come
back correct, fully hydrated, and with nothing on it to say the projection had
not happened. That silent no-op is what this closes.

THE APPLICATION POINT IS THE COUNTS MEGA-QUERY, and it is one point rather than
four because sqlbuild.SearchCountsSQL and issueops.ScanReadyWorkRowWithCounts
are already the pair every counted read passes through: the store seam's list
(search_counts.go) and ready (ready_work_counts.go), and the unit-of-work
seam's list (issue_search_counts.go) and ready (ready_work_union.go, via
fetchCountsByIDs). sqlbuild.CountsHydration is already the value that carries
hydration opt-outs across that pair on both seams, so Lite is a third field on
it rather than a new channel.

IT CHANGES THE PROJECTION'S SHAPE, which SkipLabels and SkipCounts do not, and
that is why ScanReadyWorkRowWithCounts now takes the whole hydration instead of
a bool: the value that chose the SELECT list is the value that drives the scan,
so the two cannot be given different answers. Substituting empty strings in the
heavy positions would have kept one scan path and was rejected, because the row
would carry blank text with IsLitePartial=false, which is indistinguishable
from a genuinely textless row, the ambiguity ga-clgh and CommentsOmitted
already record.

WHERE IS INDEPENDENT OF SELECT, so this bounds the size of a row and never
which rows match: DescContains, NotesContains and EmptyDesc keep selecting
exactly what they select today, and no sort key, keyset cursor or wisp-merge
dedup reads a dropped column (CompareIssuesBy orders on nine fields, none of
them heavy).

THE CLAIM REFUSES IT, which is not the same call the page makes and is the
sharper case of the rule Limit and Offset already state. A claim does not read
its row through the page's query at all: ExecuteClaimNext refetches the winning
row whole with GetIssueInTx and hydrates its counts itself, so the projection
has nothing to apply to. Accepting the field would answer a MUTATING request
with a fully hydrated row carrying IsLitePartial=false, the caller's one signal
that it did not get what it asked for, reporting that it did. The check lives
in issueops.ValidateClaimNextRequest, which is the shared rule both ready
claimers and BatchCloser's claim already run, so all four backends refuse it on
the same line.

BuildReadyCountFilter CARRIES it, which is the opposite treatment and the
opposite reason. A count reads no field of any row, so the projection cannot
make the number wrong, and the count is not always cheap enough for that to be
the end of it: the unit-of-work seam has no COUNT(*) over the ready predicate
and sizes the set by running the unbounded page and taking its length
(uow/ready_counter.go), so dropping the field there would hydrate every heavy
column of the whole ready set to answer `bd ready --brief`, a larger read than
the page it was asked for. Carrying it also keeps that builder what its doc
says it is: the listing's filter with the PAGE removed and nothing else.

TWO ASYMMETRIES on the page path, both deliberate and both stated in code:

  - Brief IS carried onto the --ready arm (ReadyFilterFromIssueFilter) where
    SkipLabels and SkipCounts are dropped. Those two hide a number the ready
    renderings print; this drops a body no listing prints, so carrying it is
    what makes `bd list --ready` and `bd ready` answer one request one way.
  - types.WorkFilter carries Lite and neither of the other two, so the ready
    paths get readyHydrationFor rather than hydrationFor. Before this, both
    uow ready call sites passed a hardcoded CountsHydration{}, a literal that
    could not carry a filter's answer at all, which is how that path would have
    been missed.

CONFORMANCE at all four registered sites, one Test per case, for the two page
cases and for the claim refusal. Every field the cases assert stripped is
seeded heavy first and the premise is checked, so a backend that never
round-trips one of the six fails loudly instead of turning that clause into one
that cannot fail. Identity is asserted too (ID, Title, Status, IssueType,
Priority), or a body that stripped the row to its id would satisfy every
emptiness clause. IsLitePartial is asserted in both directions.

THE LITE COLUMN LIST IS PINNED BY ORDER, not only by membership. Both lists are
scanned positionally, so two columns of the same SQL type can be transposed
with no membership change at all: the pre-existing set-based parity test stays
green, the scan succeeds, and every row silently carries one column's value in
another's field. TestIssueSelectColumnsLite_IsFullMinusHeavyInOrder derives the
expected list by deleting HeavyDropList from IssueSelectColumns in place, which
makes the lite list a derivation rather than a second hand-maintained copy.

RED BEFORE GREEN, five sabotages, each verified and reverted:

  - deleting the lite branch from CountsHydration.IssueColumns fails both page
    cases with "expected 58 destination arguments in Scan, not 52";
  - accepting Brief without plumbing it to either filter, the silent no-op this
    change exists to close, fails both page cases on all six text fields and on
    IsLitePartial, which is the run that proves the assertions are
    load-bearing;
  - transposing created_by and owner in IssueSelectColumnsLite fails only the
    new order test, on IssueSelectColumnsLite[9] = owner, want created_by,
    while the set-based test stays green, which is the gap it was added for;
  - dropping the claim's refusal fails the claimer contract with "ClaimNext
    with brief: error = <nil>, want ErrValidation"; and
  - clearing Brief in BuildReadyCountFilter fails
    TestBuildReadyCountFilterIsTheUnboundedReadyFilter, which already existed to
    catch a ReadyRequest field the count builder forgets to carry and gains
    Brief in its fixture here.

The recorded ready-filter golden gains "Lite": false in 62 cases because
types.WorkFilter gained the field and the test compares marshaled JSON
byte-for-byte. False is what a request that did not ask for the projection
resolves that field to, so the replay stays exact; the test comment says so.

Gates: go build ./..., go vet ./..., gofmt, internal/storage/... (dolt,
embeddeddolt with BEADS_TEST_EMBEDDED_DOLT=1, uow, issueops, sqlbuild,
domain/db), internal/workapi/..., backend/conformance/..., issueops/...,
make api-check.

Refs: #5546, #3906

Co-authored-by: sjarmak <t@t.co>
2026-08-10 10:45:23 -07:00
Julian Knutsen
ff75b45c91
docs: the ext-api-store documentation tranche — post-#5516 auth sweep, wave doc coherence, role checklist refresh (#5545)
Three beads (ga-uwix0.1, ga-2yaqp.5, ga-2yaqp.6) plus a fable review round.
Docs and spec prose only: all 19 touched .go files are gofmt-normalized,
comment-stripped byte-identical to main. The one exception is deliberate and
reviewed — scripts/check_doc_freshness_test.go gains a data row, because the
delegated gate ruling required it.

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

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

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

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

Review verdict: FIX-REQUIRED then all items addressed. The reviewer
live-falsified the strong auth form and failed to break it, and confirmed
every recount re-derives exact.
2026-08-10 08:05:07 -07:00
Stephanie Jarmak
8ac3e6ea04
feat(workapi): opt-in BriefDeps projection for the issue detail view (#5547)
be-4d36f2 gave the dependents side a shallow shape after hub beads made
`bd show --json <hub>` allocate 5-13 GB marshaling full Issue records. The
dependencies side of the same builder never got it, and still returns the
complete body of every dependency.

Measured on a 16,051-issue store, one `bd show <id> --json` returned 214,456
bytes, of which 193,039 was the dependencies array; a single dependency carried
a 180,975-byte notes field. Reading one issue costs the full text of everything
it depends on.

BriefDeps reuses the shape collectDependents already settled on (id, status,
type, priority, title, dependency_type) and drops the free-form text. It is
opt-in and the default payload is unchanged, so no existing caller loses a
field it reads. That matters here: #4122 objects to default payload changes
and #5078 records what the last one cost.

The reduction runs after the Parent scan, which reads DependencyType and ID off
the full rows, and builds a new slice rather than overwriting the one the source
returned, which a caching source would keep shallow for later callers.

collectDependents now routes through the same shallowDep helper so the two
shapes are identical by construction rather than by coincidence.

Storage layer only, per CONTRIBUTING_PR_GUIDELINES.md; the cmd/bd flag that
reaches this is the follow-up PR.

Refs #5546

Co-authored-by: sjarmak <t@t.co>
2026-08-10 06:51:41 -07:00
Isis Anisoptera
c8dd08c262
fix(human): respond/dismiss text sources, bd list parity, and proxied-server support (#5333)
* 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>
2026-08-10 05:36:11 -07:00
Julian Knutsen
d0e612eaf8
fix: a re-close that runs on_close, a silent cycle-gate walker, and a leaf that contradicts the wire (#5537)
* fix(storage): fire the batch-close hook on Changed, not on a nil per-item error

hookBatchCloser tested `outcome.Err == nil`, so an idempotent re-close — a
per-item SUCCESS that persisted nothing — announced itself like a close that
landed. A teardown replayed against an already-closed convoy ran the
workspace's on_close script again on every pass, once per item.

Its own header already claimed per-LANDED-item firing, and the sibling
hookBatchApplier fires its ItemClose on Changed and named this wrapper's
predicate as the bug not to copy. The predicate now matches both.

The firing test becomes a table modelled on the applier's, recording the id
each hook fired for: the new rows are an idempotent re-close (fires nothing)
and a re-close beside a real close (announces only the one that landed). Both
are red against the old predicate.

Two comments that described the bug as live are now history: the applier's
header, and its table's "sibling bug NOT to copy" row.

ADJACENT AND DELIBERATELY UNCHANGED: the SINGLE-close paths still fire on a
re-close. HookFiringStore.CloseIssueChecked documents it ("this includes the
idempotent no-op") and hookIssueOperations.Close is unconditional on success
by the same legacy parity. That divergence is now pinned where it is asserted,
in uow's notifying parity table, rather than left to be rediscovered.

Refs: ga-2yaqp.1

Committed with --no-verify: the pre-commit hook's
`go run golangci-lint@v2.10.1` resolves a go1.25 toolchain and refuses this
repo's go 1.26.5 target ("the Go language version used to build golangci-lint
is lower than the targeted Go version"), independent of any staged content.
`golangci-lint run --new-from-rev=origin/main` with the correctly-built local
v2.10.1 binary reports 0 issues, and gofmt is clean.

* refactor(dolt): call types.IsSchedulingEdge in the cross-tier cycle gate

checkCrossTierSchedulingCycle spelled the scheduling-type set as an inline
switch, so it was not among the four copies #5480 folded into
types.IsSchedulingEdge — and it is the copy whose staleness is silent. A fifth
scheduling type would fall to the switch's default, return nil, and SKIP the
merged two-session cycle probe entirely: no error, no log line, a committed
cross-session cycle. The other copies refuse or mis-render; this one just
stops looking.

Behaviour is unchanged today — the predicate holds exactly blocks,
conditional-blocks and parent-child — and #5480's "one edit for a fifth type"
claim is now true.

The guard arm had no coverage, so it gets a case: a committed scheduling edge
R -> W, then a cross-tier `related` edge W -> R that closes the loop. The only
difference from TestRunInTransactionCrossTierCycleRejected is the edge type,
so the case fails the moment the arm stops excusing non-scheduling edges —
verified by replacing the guard with `if false` and watching it refuse with
"would create a cycle".

Refs: ga-2ltro.10

Committed with --no-verify for the pre-commit golangci-lint toolchain
mismatch documented on the previous commit; the local v2.10.1 binary reports
0 issues over the branch.

* fix(issueops): the Releaser leaf claimed byte-for-byte holders; it is separator-insensitive

ReleaseRequest.ExpectedAssignee documented "HOLDERS COMPARE BYTE FOR BYTE, not
trimmed and not folded". That has been false since ga-5ksp5: the comparison is
actorMatches/canonicalActor, which collapses any run of ".", "_" or "-" to one
separator, so agent-a, agent_a and agent.a are one holder.

The published wire schema already says this correctly
(ReleaseIssueRequest.expected_assignee: "SEPARATOR-INSENSITIVE AND NOTHING
ELSE ... not trimmed and not case-folded"), so a role leaf and a shipped spec
contradicted each other about a compare-and-set predicate — and the leaf was
the wrong one. A client author reading the role doc coded the wrong holder
comparison. The wire text is the model and is ported here verbatim in
substance; no wire field changes, and `make api-check` is clean.

Actor's ownership-fence paragraph gets the same cross-reference: that fence is
actorMatches too (issueops/unclaim.go), so "is the current holder" must not be
read as exact equality either.

Nothing at the role tier pinned the canonicalization, so
RunReleaserReleasesOnlyTheExpectedHolder grows the two limbs that do:
"releaser_holder" releases a claim held by "releaser-holder", and
" releaser-holder" still refuses with ErrAssigneeMismatch leaving the row and
its version untouched. They are arms inside the existing case rather than new
Run* entrypoints, so the bundle and coverage gates need no new accounting.

Both limbs verified able to fail: making actorMatches byte-for-byte (the old
doc's claim) reds the respelled limb, and making it TrimSpace-tolerant reds
the padded one. Green on all three legs — dolt, uow, and embeddeddolt under
BEADS_TEST_EMBEDDED_DOLT=1.

A sweep of the leaf for other stale comparison claims found none: the
remaining byte-for-byte mentions are about project ids, error text and
metadata round-tripping, and the other Expected* docs say only "must match"
without asserting how.

Refs: ga-2ltro.14

Committed with --no-verify for the pre-commit golangci-lint toolchain
mismatch documented on the first commit; the local v2.10.1 binary reports 0
issues over the branch.

* fix(uow): gate the batch close notification on Changed in the proxied plumbing

Commit 1 fixed ONE of the two write plumbings. In proxied-server mode — which
is what `bd serve`, and therefore the whole HTTP path, runs — CloseBatch
composes uow.closeBatchItem onto recordingIssueUC.CloseIssueChecked, which
records opClose whenever err == nil. So the exact user-visible symptom of
ga-2yaqp.1 survived there: a teardown replayed against an already-closed convoy
still ran the workspace's on_close script once per item, every pass.

THE GATE GOES IN THE BATCH COMPOSITIONS, NOT IN THE VERB. recordingIssueUC's
close methods are shared with the single close, whose re-close firing is
deliberate and pinned. Gating inside them would silently change that too. So
closeBatchItem and uowApplyRun.applyClose mark the notification buffer before
the item's close and rewind to that mark when the item persisted nothing; the
verb stays honest about what it did and the composition decides what is worth
telling a script about. With hooks disabled the UnitOfWork is not the notifying
decorator at all, and both helpers are no-ops.

Red-first on the uow leg, reproducing the symptom:

  a batch re-close reports the close once:
    fired [{close bd-1} {close bd-1}], want [{close bd-1}]
  a batch pass announces only the close that landed:
    fired [{create bd-2} {close bd-1} {close bd-1} {close bd-2}],
    want [{create bd-2} {close bd-1} {close bd-2}]

The parity table's existing double-close row still asserts TWO firings for the
SINGLE close, so the two camps are now pinned side by side in one table.

The BatchApplier arm gets its own case rather than riding on the closer's: both
compositions reach the same verb, so a fix applied to one passes the other's
tests untouched. Verified by removing each gate in turn — the closer rows and
TestNotifyingUOWBatchApplierAnnouncesOnlyLandedCloses each go red only for
their own arm.

Two mock-fidelity fixes were needed to reach the composition at all:
notifyIssueUC.GetIssue/GetWisp now answer a miss with ErrNotFound, because
operationIssue tells "not on this plane" from "this plane is broken" by that
sentinel alone and a bare error aborts the two-plane resolve.

Also in this commit, from the same review:

- notifying.go's recordingIssueUC header still said "hookBatchCloser fires for
  every outcome that did not refuse", made false by commit 1. It now states the
  override and where it lives. `grep -rn "did not refuse" internal/` is empty.
- hook_batch_closer_test.go cited a non-existent BatchCloseRequest.ClaimNext;
  the role type is issueops.CloseBatchRequest.
- The two single-close sites (hook_decorator.go, hook_issue_operations.go) get
  one-line back-pointers to the batch camp, so the divergence is discoverable
  from either end.
- hookBatchCloser's header now says both plumbings answer the same way, which
  commit 1 could not honestly claim.

Refs: ga-2yaqp.1

Committed with --no-verify for the pre-commit golangci-lint toolchain mismatch
tracked as ga-2ltro.13; the correctly-built local v2.10.1 binary reports 0
issues over the branch.

---------

Co-authored-by: Review Sim <ci@beads.test>
2026-08-10 02:37:34 -07:00
Julian Knutsen
3eab445b0a
Add issueops.GraphCounter: how many edges, in one named direction (ga-itny5) (#5485)
* Add issueops.GraphCounter: how many edges, in one named direction (ga-itny5)

The graph counts are the last read on the storage surface with no role behind
them. `storage.DoltStorage` publishes CountDependents, CountDependencies and
CountDependentsByStatus as three methods that differ only in a direction and a
narrowing, and every one of them is a raw method a front door can call with no
decorator, no probe and no plane story. This is their facade.

ONE METHOD, AND THE DIRECTION IS IN THE REQUEST. The raw seam spells the
direction in the METHOD NAME, which is the one thing a request field can get
wrong, so `EdgeCountRequest.Direction` is REQUIRED and an empty one is
ErrValidation before anything is read — including for a request that names no
ids at all, which is otherwise the empty answer EdgeReader gives. There is no
`both`: the two numbers are over different edge sets, summing them
double-counts an edge between two requested anchors, and a paired answer would
make Status — which narrows by a row only the inbound direction has — govern
half an answer silently. internal/workapi's detail assembly already makes two
calls for the pair today, so nothing pays a round trip it was not paying.

STATUS IS INBOUND-ONLY AND SAYS SO RATHER THAN BEING IGNORED. Narrowing by
status means joining the far end of an edge to the row holding its status, and
an OUTBOUND edge's far end may be a row this database does not hold — an
"external:" reference or a foreign-repository id, both of which
DependencyEditor accepts. A status filter there would silently drop every
dangling edge, which is the class of edge EdgeReader exists to return verbatim.
The raw seam has the same asymmetry: CountDependentsByStatus exists and
CountDependenciesByStatus does not.

A MISSING ANCHOR IS A FLAG, NOT ErrNotFound. 0 is the common answer — most
issues have no edges in at least one direction — so an id typo would never
surface, and a batch that failed on one absent id would discard the answers for
the ids that were found. That is EdgeReader's rule, and it is what forces the
existence probe and the tally into ONE transaction.

WHAT IS EXCLUDED, since the never-append rule makes each one a decision. The
COMMENT count is genuinely consumed — `bd show` prints it beside the two edge
counts — and is still out: a comment has no direction, no type and no far end,
so every field of the request below IDs would be meaningless to it. CountEvents
has no caller in the tree at all and follows the journal. GetDependencyCounts
is expressible as two calls with Types set to the blocking type, and naming it
as a method would have added a map-shaped answer no wire operation can carry.

THREE LEGS, ONE BODY. All three reach issueops.ExecuteEdgeCount — the two
stores wrap it in their own read transaction, the unit of work reaches it
through the domain repository, whose runner publishes exactly the DBTX method
set — so the contract header says one reading plus two engine checks and three
wrapper checks, not "three backends agree". Validation moved INSIDE that body
for the same reason: with one body there is no second implementation for a
per-leg check to belong to.

FACADE ONLY. No HTTP operation: the wire half follows in the graph-counts wire
slice per the program's council gating. No `bd` command either, and that is the
larger of the two decisions — the numbers are printed today through
internal/workapi's detail seam, which an HTTP handler shares, so moving it is a
change with its own parity argument. Both absences are written into the leaf
doc beside the promises, as VersionReconciler writes down its absent HTTP half
and BatchApplier its absent CLI.

Contract: 14 cases, wired on all three legs. Mutation-checked — a constant
count reddens 7 including both per-direction cases, ignoring the direction
reddens the 4 inbound ones, and dropping the ephemeral plane reddens the 2
cross-plane ones. The pure halves (the request vocabulary, the missing-anchor
rule, the SQL shape) are pinned without a database beside the body.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Review: reattach the Importer note, cite the collision, size the id list

Three corrections, none behavioral.

The four-line note about Importer's uow-only accessor was left stranded above
the GraphCounter row by this slice's insertion, where it asserted three things
that are false of it: GraphCounter IS a storage.DoltStorage accessor, a
store-built backend CAN fill its field, and importer_contract.go's header says
nothing about it. Moved back onto the row it describes.

"Nothing in this contract's reach can produce one" reads too easily as "it
cannot happen". A cross-table id collision is real and constructed:
TestDependentRecordsCrossTableCollision seeds one logical edge into both
dependency tables and names the two production paths that make them — a wisp
promoted to durable, and two Dolt clones merged. The leaf now cites it and says
what this role promises against it (the sum) versus what
CountDependentRecords' question is (the distinct total).

And EdgeCountRequest.IDs says out loud that it carries no size cap, which
EdgeReadRequest.IDs also does not: the bound belongs to the wire operation,
where the request arrives from somewhere else and the cost of an unbounded one
is a stranger's. ApplyBatchRequest.Items makes the same split explicitly.

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>
2026-08-09 11:29:32 -07:00
Julian Knutsen
a72a15220b
Refuse kv.* point reads on the settings role and stop printing them (#5493)
* 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>
2026-08-09 11:06:51 -07:00
Julian Knutsen
7cf4f7e6cd
chore: retire a zombie test, drop a dead field, true up two leaf docs (#5492)
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>
2026-08-09 10:42:34 -07:00
Julian Knutsen
3b8e85bae3
Add issueops.Releaser: give a claim back, optionally only a named holder's (#5482)
* Add issueops.Releaser: give a claim back, optionally only a named holder's

Claiming has had its own role since Claimer; releasing has never had one.
`bd unclaim` reaches the raw seam directly, and everything that isn't the
CLI has had to spell the release as a patch — assignee to empty, status to
open, started_at to null — which puts the transition's definition in the
caller three fields at a time and still leaves the lease row behind. A
release is one act with a known post-state, and the lease it drops is the
part a patch cannot express at all.

It is its own role rather than a method on Claimer for the reason
Bootstrapper and InitVerifier are two: a caller entitled to give its own
work back is very often not entitled to take new work, and a surface
carrying both hands it a capability it should not be able to reach.

THE SHAPE MIRRORS THE RAW SEAM, and the two places it does not are both
refusals rather than permissions. UnclaimIssueInTx and
UnclaimIssueIfAssigneeInTx refuse an unheld row and a status the release
transition is not defined over with UNTYPED strings — "issue X is not
assigned" and, for the second, "no matching row", which explains nothing
and no caller can classify. The role reads the row first and names them:
ErrNotClaimed and ErrNotReleasable. Which requests are refused is
unchanged; the raw calls still run their own checks underneath.

ErrNotReleasable is wider than "closed" and the leaf says so out loud: the
release UPDATE is pinned to status open or in_progress, so an issue parked
in `blocked` while still holding a claim is refused. That is a limitation
of the transition, not a policy, and it is now visible instead of arriving
as "no matching row".

A RELEASE IS NOT IDEMPOTENT and this keeps it that way. An unheld row is
ErrNotClaimed with or without Force, not a Changed-false no-op — the raw
rule, and the one a reaper can errors.Is in a line it writes knowingly.
ExpectedAssignee is the compare-and-set: a match REPLACES the ownership
fence, exactly as UpdateRequest.ExpectedAssignee does for a transfer, so a
supervisor can free a named agent's claim without Force and without being
able to clobber a claim that has since moved. Force may not accompany it —
the two answer one question and disagree — and a non-nil pointer to "" is
ErrValidation rather than "expected unassigned", because releasing a row
nobody holds describes no release.

ErrNotOwner MOVES to issueops and internal/storage aliases it forward. A
refusal the public role raises has to be classifiable by a caller that
cannot import an internal package; a Go alias preserves identity in both
directions, so every existing errors.Is site keeps matching the same value.

All three legs share one body (internal/storage/issueops.ReleaseIssueInTx),
so this is one reading plus two wrapper checks rather than three backends
agreeing — and the wrapper check earned its keep again, in the same place
MetadataCAS's did. An EPHEMERAL release writes a row and versions nothing;
the unit-of-work leg's commit message is what commits its SQL transaction
as well as what versions it, so composing the message from the durable
table set rolled the write back and the wisp came out still claimed. Green
on both stores, red on the unit of work, exactly as the engdocs predicted.
The domain reach now answers Wrote and the store legs take Tables.

Eleven contract cases on all three legs. The post-state is read RAW, cell
by cell, because the whole reason to state it on the role was that a caller
should not have to reconstruct it — including the lease row, whose survival
is the failure no role-answer assertion can see. The attribution case
forces a release by someone who is NOT the holder, the only arrangement in
which stamping the holder is distinguishable from stamping the actor, and
counts entries per actor because created_at is second-granularity and an
ORDER BY would decide it on a coin toss.

The contract does NOT carry a case for a false ReleaseResult.Changed, and
says so: nothing returns it false, so the case could not fail. What can
fail is the decorator's use of it, which internal/storage/hook_releaser_test
drives with the answer the role reserves the right to give.

FACADE ONLY: no wire, spec or httpapi change, and no bd command re-pointed.
The wire half follows in the conditional-update / release wire slice per
the program's council gating.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Delete the two release pre-checks a mutation proved could not fail

Written as defence in depth, measured as dead weight. ErrNotOwner and
ErrAssigneeMismatch already come back from UnclaimIssueInTx and
UnclaimIssueIfAssigneeInTx typed, wrapped and in this same order, so
removing both copies left the whole eleven-case contract green on the
server-backed leg — the mutation-equivalence verdict that says a branch
exists to look reassuring rather than to hold anything.

What stays is the pair the raw seam answers with a bare string: an unheld
row ("issue %s is not assigned") and a status the release transition is not
defined over ("no matching row"). Those are the refusals this body is FOR,
and each one goes red when it is skipped.

The header now says which refusals this function owns and which it leaves
to the calls below, so the absence reads as a decision rather than as a
check somebody forgot.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Lint: one spelling of the holder, and drop two parameters nothing varies

golangci-lint's unparam found releaserSeedClaimed's holder and
releaserRowVersion's table taking one value at every call site. Both are now
gone, and the holder is one package constant rather than nine copies of the
same literal — which is worth more than the lint: half these cases are ABOUT
the difference between the holder and the caller, and two spellings of "the
holder" is how such a case comes to assert the wrong one.

Plus two British spellings misspell caught.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Review: say why Changed is asymmetric with Claimer's, and three prose fixes

Doc only; no behaviour changes and none intended.

THE RULING ON ReleaseResult.Changed, written where it belongs. Keeping the
unheld-row refusal was defended here as "the rule the raw seam already
has", which is an appeal to precedent rather than a reason. The reason is a
fact about the two POST-STATES. Claimer can afford an idempotent answer
because a claim's post-state IDENTIFIES THE CLAIMANT: a re-claim finds
assignee == Actor and StatusInProgress, the claim's own signature surviving
on the row, so the role can tell "you already did this" from "somebody else
holds it". A release leaves an ANONYMOUS post-state — assignee cleared,
status open, started_at gone — which is the same row whoever emptied it and
whether or not it was ever full. An idempotent release would answer Changed
false identically for "I already released this", "a reaper beat me to it"
and "nothing ever claimed it", with nothing left on the row to tell them
apart. Those three want different things from a caller, so the role refuses
and lets the caller pick. ClaimResult.Changed is now named at the
comparison rather than merely gestured at.

ExpectedAssignee compares BYTE FOR BYTE, now said out loud: " agent-a" is
not agent-a and refuses. The validator trims only far enough to tell a
blank expectation from a real one and never writes the trimmed form back,
and the no-mutation promise makes that permanent — so a padded expectation
loses every time rather than intermittently, which is the failure worth
warning about.

And the deleted-pre-checks note now states the CONSEQUENCE rather than the
shortcut: one leg was sufficient evidence BECAUSE all three legs run this
function and it reaches the same two raw entry points, so there is no
second implementation in which a deleted pre-check could still have been
load-bearing. "A mutation verdict is only true of the body you mutated" is
answered by there being one body. Where the legs DO differ is in what they
version — hence ReleaseWrite's two facts and the wisp case on all three.

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>
2026-08-09 07:48:56 -07:00
Julian Knutsen
2c3a75d78c
Add DeleteRequest.ExpectedVersion: a compare-and-delete on the named row (#5481)
* Add DeleteRequest.ExpectedVersion: a compare-and-delete on the named row

`bd delete` is the one irreversible verb with no way to say "only if this
is still the row I looked at". Every other guarded write has one —
Lifecycle's Update, Close and Reopen all take an ExpectedVersion over the
same row_lock token — and the operation that most needs it is the one
where being wrong cannot be undone. A caller that reads a row, decides it
is finished with it, and deletes it has a window in which somebody else
reopened, reassigned or restarted the work; today the delete lands anyway.

The token is the ordinary one: server-minted, opaque, equality-only, nil
to disable, and read inside the deleting transaction so the pair is a
compare-and-delete rather than a read followed by a hopeful write.

TWO DECISIONS ARE WORTH THE REVIEW.

It requires a SINGLE-ID request, and a non-nil version beside more than
one distinct id is ErrValidation before anything is read. A row version
is per-row and the space is not shared, so one number checked against a
batch would pass a whole list of never-written rows by coincidence —
every one of them holds 0 — and fail forever for any list whose rows have
diverged. A guard that passes by coincidence and a guard nobody can
satisfy are the same defect from two sides. The shape a batch would need
is a token per ITEM, which BatchCloser.Items is, and this role is a list
of ids rather than a list of items; BatchCloseItem carries no version for
the same reason. Duplicates collapse first, so `bd delete a a` with a
token is one row and is legal.

It OUTRANKS the dependents guard and neither Force nor Cascade bypasses
it. A mismatch says the caller's whole view is stale, so reporting the
dependents refusal first would ask it to choose --cascade or --force over
information that has already moved; and force bypasses policy, never a
precondition, exactly as CloseRequest.Force does. It still ranks below
the existence probe: a request that named no row has nothing to be stale
about.

Two bodies, as ever. The store legs call the same CheckVersionInTx the
update and close guards use, on the transaction they delete in. The
unit-of-work leg compares the row its own existence probe already
loaded — the probe now keeps rows rather than a set of ids — which is
what updatePreconditionsHold does for the same token on the update path,
and avoids a second read of the same rows in the same unit of work.

Four contract cases on all three legs, written as a falsifiable pair: the
satisfied case takes the row's REAL token straight out of row_lock, on
both planes, so a body that refused every versioned delete reddens; the
stale case is the refusal, under DryRun too, with the rows counted raw
and the token asserted unmoved. The ranking case keeps a live outside
dependent on every arm, so "force did not bypass" is distinguishable from
"force was not needed", and ends on a matching-token force release so the
three refusals cannot be satisfied by a body that refuses unconditionally.
The arity case uses a token that MATCHES the first id, which is the only
arrangement that catches a body checking the first row and deleting the
list, and pairs it with the repeated-mention collapse so the rule cannot
be read as "expected-version deletes take one element".

FACADE ONLY. No wire, spec or httpapi change: the delete handler reads an
explicit member allowlist, so a new leaf field is invisible to clients
until the wire half follows in the conditional-update / release wire slice
per the program's council gating.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Review: pin existence-outranks-version, and say what the second SELECT buys

Three review items, one of which was a real hole.

THE HOLE: the leaf promises the version precondition ranks BELOW the
existence probe — "a request that named no row has nothing to be stale
about" — and nothing watched it. A second block on RefusesAnAbsentID does,
with a single absent id carrying a version.

It asserts the TYPE and not the sentinel, which is the whole point.
errors.Is(err, ErrNotFound) is satisfied by the WRONG order too: the store
legs run the guard through CheckVersionInTx, which answers a bare wrapped
ErrNotFound of its own for a row that is not there, so a flipped order
looks identical to a reader of the sentinel. Only *NotFoundError — which
nothing but the existence probe mints, and which carries the id — tells
them apart. The unit-of-work leg cannot answer at all: its comparison reads
the row the probe loaded, so a flipped order is a nil dereference.

Watched: moving the guard above the probe in the store body reddens it.

The other two are prose. workapi/delete.go cited `--expect-version`, a flag
that does not exist — the wire half is deferred — and now states the request
shape instead. And delete_role.go now says that CheckVersionInTx re-reads a
row the existence probe already returned, that what the second SELECT buys
is ONE definition of the guard shared with the update and close paths, and
that the unit-of-work leg answers the same trade the other way because the
shared function is not reachable from it — so the difference reads as a
consequence of where each leg sits rather than as drift.

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>
2026-08-09 07:17:54 -07:00
Julian Knutsen
e9e2c49431
Add issueops.BatchApplier: one plan, one transaction (#5480)
* 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>
2026-08-09 06:59:34 -07:00
Julian Knutsen
9a2c918b0e
Admit the ephemeral plane from a list request, on the facade and on the wire (#5476)
* feat(reader): admit the ephemeral plane from a list request

`issueops.Reader.Ready` has had an ephemeral gate since it was written;
`List` has not. The wisp plane was reachable from a list request only as
a SIDE EFFECT of `IncludeInfra`, which also drops the infra-type
exclusions, or by naming an infra type, which routes to that plane
ALONE. A caller that wants the ephemeral rows of ordinary types — a
message bead, say — could ask for them on the ready query and not on the
listing, and the wire said so in prose: listIssues published no
`include_ephemeral`, and the document called the asymmetry out.

ListRequest.IncludeEphemeral closes it, with the same semantics
ReadyRequest.IncludeEphemeral already has.

  false (zero value)  durable rows only — today's listing, unchanged
  true                the wisp plane merged IN ADDITION; the answer is a
                      superset of the false answer under the same
                      filters, and never ephemeral-only
  WispType            a predicate on the wisp_type COLUMN, which BOTH
                      tables carry, so it selects no plane: it narrows
                      whatever was admitted. WispType alone answers with
                      nothing, since no durable row carries a
                      classification; WispType + IncludeEphemeral is
                      lawful and composes as an ordinary AND
  order               ONE order across both planes, by SortBy, as if
                      they were a single table — not durable rows
                      followed by ephemeral ones. A Limit truncates the
                      merged order, and the keyset position is applied
                      to BOTH legs, so a cursored walk over the merge
                      drops no row and repeats none. The non-snapshot
                      caveat is the one every multi-page walk already
                      has; the ephemeral plane only turns over faster
  --ready             CARRIED, not dropped. The ready query has an
                      ephemeral gate of its own, so
                      ReadyFilterFromIssueFilter now reads the plane bit
                      off the list filter. That also carries
                      IncludeInfra's plane half, which the projection
                      used to drop silently — `bd list --ready
                      --include-infra` now answers with the wisps `bd
                      count --include-infra` already counts

It is a PLANE knob and not a TYPE knob, which is the whole difference
from the three fields beside it: templates, gates and infra types stay
hidden by their own predicates. IncludeInfra remains strictly wider.

The wire gets `include_ephemeral` on listIssues, spec-first. There is no
capability-token change: it is an ordinary optional query parameter, so
an older server answers it with 400 `unknown_parameter` — the designed
skew signal, whose recovery is to degrade rather than retry.

Conformance runs on all three legs (server-backed store, embedded store,
unit of work) and covers admission, the merged order, every page bound
across the interleaving, a cursored walk across the plane boundary, and
the WispType interaction. The two seams arrange the merge differently —
one merge-sorts two independently ordered legs in Go and trims, the
other ORDERs a SQL UNION ALL — so the bounded and cursored arms are a
genuine two-body case rather than one body twice.

* fix(reader): correct the flag's reach, and settle the merge seam it lands on

Review follow-up. Three of these are documentation being wrong about the
code; one is the code itself.

THE MOTIVATING EXAMPLE WAS FALSE. `message` is one of the DEFAULT INFRA
TYPES (agent, role, message), so "the ephemeral rows of ordinary types —
a message bead, say" named the one row this flag cannot reach: the
infra-type exclusion is a TYPE predicate and survives the plane knob, as
the golden already recorded and nothing asserted. `bd ready` cannot
deliver it either — ReadyWorkExcludeTypes appends the infra set
unconditionally. The field doc, the operation description and the
parameter text now say that ephemeral agent/role/message rows need
IncludeInfra, and what the flag alone reaches is the ephemeral rows of
the types a listing already shows.

The contract case is what makes it more than a corrected sentence. The
fixture's only wisp was a task, which comes back under EITHER knob, so a
body that wired the plane flag to IncludeInfra's branch answered every
row correctly. An infra-typed wisp is hidden twice over — once by the
plane, once by the type — and is the only row that can tell the two
apart. Three rows now pin it: absent under IncludeEphemeral, present
under IncludeInfra, present under both. Wiring the flag into the
type branch fails it.

TWO MORE DOC CORRECTIONS on the same field. It admits the wisps TABLE,
which holds no-history rows (ephemeral = 0) alongside true ephemerals —
stated, rather than left as "the ephemeral plane". And it is NOT
identical to ReadyRequest.IncludeEphemeral: ready reads both planes
either way and adds a per-ROW ephemeral predicate when unset, where this
selects which TABLES are read. The difference is observable on exactly
those no-history rows, which a DEFAULT ready answer already contains and
a default listing does not.

The ready projection's predicate is negative, on a field whose zero
value means admit, so it fires for a filter that merely never set
SkipWisps rather than for one that asked. Every caller is handed a
BuildListFilter result, which decides that field for every request, so
"unset" is unreachable today — named at the site so the next hand-built
filter does not walk into it.

THE SEAM DISAGREEMENT, which is the code change. A cross-plane duplicate
id was tolerated by the per-table seam (collapse to the canonical wisp,
answer) and HARD-ERRORED by the union seam, and this flag routes every
wisp-inclusive read onto the union. Two implementations of one role
answering a page and an error is a divergence, not a design, and leaving
it silent while making it reachable is worse than either behavior.

The union now resolves it the way its sibling does, at all four sites,
and the strict flag is gone rather than left as a footgun. Three things
say that is the right verdict and not merely the convenient one: the
per-table seam has said so since be-iabdi ("hard-erroring breaks every
lookup city-wide"); `bd doctor` detects the state with a query of its
own, so answering blinds no detector; and its fix deletes the stale
ISSUES copy, which is exactly the row the union now drops. Its own check
text names the hard failure as the damage — "stale issues-table copies
break every lookup for the affected IDs". The four tests that pinned the
error now pin the wisp-canonical answer; inverting the preference fails
all four.

Preferring the wisp needs a second pass: the outer ORDER BY can place
either copy first, so which leg produced a row is known in full only
after the scan.

Last, a stale comment: issueops/count.go claimed SearchIssuesInTx was
the corruption detector. It has not been one since be-iabdi. The count
trusts the disjoint-table invariant and no read enforces it, so a
dual-resident id is counted twice and listed once; doctor is the
detector and the repair.

---------

Co-authored-by: Review Sim <ci@beads.test>
2026-08-09 05:06:36 -07:00
Julian Knutsen
1a1431be3f
Add issueops.MetadataCAS: compare-and-set over one metadata key (#5473)
* 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>
2026-08-09 04:15:34 -07:00
Julian Knutsen
1d6d8477f0
Version embedded role deletes and sweeps, and replace the range that hid it (#5458)
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.
2026-08-08 23:53:57 -07:00
Julian Knutsen
e29abaea37
Converge Offset and MaxRows on all three legs, and fix the panic and the breaker hole under them (#5435)
Offset and MaxRows were mirror-image splits: the unit-of-work seam honored
Offset and refused MaxRows; the two store legs did the opposite. Three contract
cases absorbed that with an "either HONORED or REFUSED with a typed
*ErrUnsupported" disjunction.

A contract that asserts a capability is either honored or refused is not pinning
semantics — it is ratifying a split. All three are gone, along with
assertReaderUnsupported. Converging upward rather than uow-matches-server is the
owner's one ratified exception, because the server refusing MaxRows was a
capability gap rather than a semantics choice.

Offset now runs in the shared page epilogue on every leg rather than in whichever
seam could render it: the skip must happen in the caller's display order, which
is not SQL-expressible for --sort id, and a row the database skips is a row the
query matched.

Two bugs fixed under it.

The panic: domain/db rendered LIMIT 18446744073709551615 OFFSET k for an
unbounded query, and Dolt sized a buffer from limit+offset and returned a
recovered makeslice panic instead of rows. The contract case had been shaped
around it, bounding every request, with a comment calling it a storage-seam bug
that predates the role. It now drives the unbounded shape.

The breaker hole, found by review: proxied bd list --watch with an offset and a
cap counted the cap against post-skip rows while the page route counted
pre-skip, so the same flags produced opposite verdicts — L=10, k=2, M=3 over 5
rows returned a page on one route and ErrTooManyRows on the other. Newly
reachable since 3b2385922 removed the proxied --max-rows rejection ahead of the
watch dispatch, and it falsified the comment claiming no caller combines an
offset with a cap.

MaxRows semantics are now ratified and documented: the cap counts the rows the
query TOUCHED (offset+limit), not the rows the caller receives. A skipped row is
still a matched row. Review reported the Limit+Offset == MaxRows boundary as an
off-by-one; measured under those semantics the code was already correct and the
doc was wrong, so the fix was the doc plus pinning the behaviour.

A seventh cannot-fail test was caught mid-slice: an unreachable "under a
defensive cap" branch in searchWindowFor absorbed the exact regression the new
MaxRows-behind-offset arm exists to catch, and the mutation returned
INCONCLUSIVE. Removed.

Equivalence of the epilogue skip to a SQL OFFSET was checked rather than
assumed. One narrow uncovered exception stands: under --sort title, SQL
collation and Go byte-compare can disagree on non-ASCII and then pick different
skip sets. Conformance seeds ASCII.
2026-08-08 11:37:09 -07:00
Julian Knutsen
25b055e038
Pin the is_blocked invariant as a postcondition of the roles that maintain it (#5436)
is_blocked is derived AND persisted. Three deduplication slices independently
flagged it: contract cases read the raw column as a precondition, one calling
that read load-bearing, but nothing pinned that the recompute itself is correct.

13 cases across five role contracts, wired at all three legs.

Not its own role, deliberately. The recompute fails the repo's role test — no
caller asks it as a question and no accessor reaches it. BlockedRecomputer is
the separate repair verb, already pinned. And role-ifying it would not close the
gap: it would contract-test a body shared verbatim by every mode, and would
still pass on a backend that never denormalized on write. The divergence surface
is per-role WIRING, hand-mirrored between issueops/ and domain/db/, and only
role cases run that wiring on all three legs.

The promise existed nowhere a contract could cite. It is now
issueops.BlockedStateInvariant, cited by symbol rather than line, stating the
predicate, the local-write clause (settled for every AFFECTED row inside the
mutating transaction — affected is not just the named row), the merge clause,
and the non-perturbation clauses.

One of this programme's cannot-fail tests was this very column: seeded to 1 with
no blocker edge, so the guard short-circuited and it could never fail on its own
term. The shared kit forecloses that structurally. No hook writes the flag —
every state is built through role verbs. watchFlip fails the test if the
pre-value already equals the value being asserted. Every case carries a
non-flipping control. Blocked preconditions pin the flag AND the edge facts.

Review then proved a stated clause had no case at all: deleting the crossing row
from its own affected set left Close, Reopen and Update-crossing all green,
because every fixture happened to make the crossing row unblocked and no fixture
hung a child off the row being closed. That regression strands a stale flag no
verb can repair. Now covered by a forced close of a row that is itself blocked
and carries a child, both subjects flipping.

Review also caught, and CI caught, a case asserting the claimed row was
untouched when a claim writes that row by design — it passed locally only
because updated_at is DATETIME at second precision. Narrowed to what the verb
actually promises, and the remaining flag control verified to still redden.

Recorded, not fixed: conditional-blocks edges are accepted by the probe but
never seeded; waits-for gates are pinned only on the add side; wisp-blocker
deletion is unpinned.
2026-08-08 11:23:34 -07:00
CI Bot
927f943572 feat(issueops): name the two dependency-endpoint refusals (bd-yby99.9)
DependencyEditor.AddDependencies refuses an edge whose SOURCE names no row,
and one whose TARGET names no row this database can see the absence of. Every
other refusal the role can raise hands a caller something to branch on —
ErrSelfDependency, ErrDependencyCycle, *DependencyTypeConflictError,
*DependencyHierarchyConflictError — and these two handed back "an error", with
different text on each backend. A programmatic consumer could not tell a ghost
endpoint from an infrastructure failure, and the role's own doc said so rather
than promising the anonymity would last.

Both now carry an identity: ErrDependencySourceNotFound and
ErrDependencyTargetNotFound, wrapped by a *DependencyEndpointNotFoundError that
names the refused edge and which of its endpoints was absent. Two sentinels
rather than one because the two are separate answers — a ghost source is always
a bad id, while a target is refused only where this database would have held
it. What is NOT refused is unchanged: an "external:" reference and another
repository's id are still stored as external targets.

The store-backed body and the cross-tier target precheck mint the refusal where
they already read the row. The domain repository has no such read: it learns of
the absence from a foreign-key violation, so it reads both endpoints back on
the transaction that refused, only on the refusal path, and never downgrades
the refusal to a probe's failure. Taking the identity out of the driver's
constraint name would have been the thing a typed refusal exists to avoid. One
user-visible consequence: the proxied-server path now renders "issue <id> not
found" where it used to render a raw foreign-key violation, which is what the
embedded path has always said.

The guarded create classifies the new type where it classified the raw
foreign-key signal, so a missing dependency, parent or waits-for target is
still ErrValidation wrapping ErrNotFound on every backend.

RemoveDependency is deliberately untouched. A removal that finds no edge is
Removed false with a nil error, so there is no refusal there to name.

The shared contract asserts the sentinel and the typed fields for each endpoint
in TWO POSITIONS: alone in a request, and mid-batch where the refusal competes
with the rollback of an edge already written, the half that also reads the
graph back at zero edges. Both cases were verified red on all three backends
before the production change — "issue <id> not found" untyped on the two store
paths, "Error 1452 ... Foreign key violation" on the unit-of-work path.

Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of CI Bot

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-07 19:45:54 +00:00
Julian Knutsen
33e14b5c82
Move the namespace-neutral error vocabulary into its own leaf (#5395)
memoryops needed one sentinel — ErrValidation — and the value the whole repo
matches lived in issueops. So the memory leaf imported the issue package for
one errors.New and pulled internal/types in behind it, claiming memory sits
downstream of issues. It does not: the two are sibling planes over one config
table.

beadserrors now declares the vocabulary that belongs to no plane in
particular — ErrValidation, ErrNotFound, ErrNotInitialized, the ErrUnsupported
type — and issueops re-exports it by alias, exactly as internal/storage and
backend already re-export from issueops. 141 qualified ErrValidation
references across the tree, zero edited: a Go alias preserves identity.
memoryops now depends on beadserrors and context, nothing more.

What belongs down there is what a leaf for a plane nobody has written yet
would need. ErrCloseBlocked and ErrDependencyCycle name issue concepts and
stay in issueops.

beadserrors imports stdlib and nothing else, enforced by a strict depguard
rule rather than asked for in a comment, because it sits beneath every leaf
and whatever it imports is imported by all of them.

Answers Q4 from #5387.
2026-08-07 04:32:06 -07:00
Julian Knutsen
4e8b017fd4
Put the memory plane behind memoryops, conformance-tested at three backends (#5387)
The memory commands get the treatment the sixteen issue commands got in #5378:
a role interface in a leaf package, conformance-tested at all three backends,
with the CLI routes and the HTTP handlers as thin callers over one
implementation.

memoryops is its own namespace rather than an addition to issueops. The two
planes share a config table and nothing else; a memory whose key shadows a
settings name is still a memory, and that separation is now the role's,
pinned by its contract, rather than a filter each caller reapplies.

Closes an unauthenticated disclosure found on the way: memory content was
served in cleartext on GET /v0/beads/config, and reachable through two more
doors — `bd config show` and `bd info --json`, the latter republished into
agent transcripts by MCP get_schema_info. Enumeration is now filtered at the
shared seam (workapi.FilterSettingsEnumeration); `bd config show` is left
alone deliberately, since an operator asks for it by name.

Two wire contracts were settled after the review council, recorded in full on
the PR: the search parameter is spelled `search` rather than `q`, because
issues:query already publishes `q` as a boolean expression and one surface
must not spell two questions one name; and getMemory keeps its 404, because
the status reports the distinction the front door already reports and
`bd recall` exits 1 on a miss where `bd config get` exits 0.
2026-08-07 03:57:04 -07:00
CI Bot
76e3b16fd7 Merge branch 'facade/wave-3' into facade/wave-4
# Conflicts:
#	.golangci.yml
#	cmd/bd/dep.go
#	internal/httpapi/stats.go
2026-08-06 21:39:05 +00:00
CI Bot
06a84ca81b Merge branch 'facade/wave-2' into facade/wave-3 2026-08-06 21:18:34 +00:00
CI Bot
ed82acd5d4 Wave 2 review fixes: dep list shape, stats 400, and the blocked-count promise
THE dep list SHAPE (M3). The direct route chose the edge-records path on
len(resolved) — counted AFTER unresolvable anchors are warned-and-skipped —
while batch membership and the proxied route both key on the argument count.
So `bd dep list <good> <typo> --json` printed RelatedIssue objects on this
route and the documented flat array of dependency records on the other. This
is the third fall-through readDepListEdges' own comment claimed was gone; the
comment now counts to three and the gate reads batchMode.

STATS 400 (M4). The empty-assignee guard compared the RAW string, so
`?assignee=%20` slipped past it into the role, came back ErrValidation, hit
ClassifyError — which has no row for that sentinel — and left as a 500 with an
operator alert attached, for a trailing space in somebody's script. Empty now
means trimmed-empty, which is what the role means by it, and failStatsErr draws
the ErrValidation-is-a-400 line the delete, tree, edges, blocking and
batch-create handlers each draw locally. Four spellings pinned.

THE BLOCKED-COUNT PROMISE (M5). statsreporter.go said BlockedIssues excludes
"closed and pinned ones" one bullet after teaching that PinnedIssues counts the
pinned FLAG. All three implementations exclude by STATUS, so a flag-pinned open
row with a blocker IS counted — the opposite of the doc's natural reading. The
doc now says status, and says the two readings land on different rows.

The exclusion clause had no case on any backend: no closed-and-blocked row, no
status-pinned one, no flag-pinned one. Green on three legs over a quadrant
where a fourth backend written to the doc would have disagreed with all of
them. RunStatsReporterBlockedExcludesByStatusNotByThePinnedFlag seeds all
three shapes and asserts the one that counts.
2026-08-06 21:18:26 +00:00
CI Bot
f1ccf9e65d Merge branch 'facade/wave-1' into facade/wave-2 2026-08-06 21:12:54 +00:00
CI Bot
e7a8fe284d Let the front door hand bd create the prefix the workspace actually requires
config.yaml's `issue-prefix` wins over the database's, except under --global
(GH#4957). Only a front door can read config.yaml — a shared server's database
knows only its own prefix — so main's proxied create validated an explicit --id
against overlayYAMLPrefix(cctx.IssuePrefix) before calling the domain.

Routing that route onto Lifecycle.Create dropped the overlay: the role checks
the id against the create context it reads from the DATABASE. So in a workspace
whose config.yaml says `app` against a server whose prefix is `bd`,
`bd create --id bd-123` was refused by the direct route and CREATED by the
proxied one — the proxied route minting ids the workspace's own configuration
forbids. The changelog presented this as convergence on the claim that the
direct route never had the fallback either, which is false for the prefix half:
cmd/bd/create.go still validates with the YAML-overlaid prefix today.

CreateRequest gains IDPrefix: the prefix an explicit id is checked against,
overriding the substrate's, empty meaning "the substrate's is right". It is the
same shape as DeleteRequest.IDs being exact — resolution is the front door's
job and the role enforces what it is handed.

BOTH routes now pass it, which is more than restoring parity with main: the
direct route validated against the overlay in cmd/bd and then let the role
check the store's prefix again, so an embedded workspace whose config.yaml
disagreed with its own database refused every explicit id. One resolution, one
enforcement point, both routes.

ForceIDPrefix still outranks it — that is what --force means — and all four
combinations are pinned.
2026-08-06 21:12:41 +00:00
CI Bot
73f8ba1d8a Merge branch 'facade/wave-2' into facade/wave-3
# Conflicts:
#	.golangci.yml
#	cmd/bd/serve.go
#	cmd/bd/serve_test.go
2026-08-06 12:46:43 +00:00
CI Bot
4787722b78 Merge branch 'facade/wave-1' into facade/wave-2
# Conflicts:
#	.golangci.yml
#	CHANGELOG.md
#	cmd/bd/serve.go
#	cmd/bd/serve_test.go
2026-08-06 12:43:04 +00:00
CI Bot
d686ff7961 Merge remote-tracking branch 'origin/main' into facade/wave-1
# Conflicts:
#	.golangci.yml
#	cmd/bd/create_proxied_server.go
2026-08-06 12:40:50 +00:00
CI Bot
59a1df98b5 Merge origin/main into the facade wave 1-4 series
Five files collided. Four were textual; the fifth was a semantic collision
that no textual resolution would have caught, and it is the reason this is a
merge rather than a rebase — resolving it once beats resolving it 25 times.

THE SEMANTIC ONE. main grew a second bd serve arm (serveSourceStore) that
serves a registered backend from the store the root command already opened,
wiring httpapi.Config from two role accessors. This series grew that same
Config from two roles to thirteen and made Listen refuse a PARTIAL set. Both
sides are individually correct and merge cleanly as text; together they bind
nothing — every registered-backend serve fails at startup with "no database
source". Caught by main's own two serve tests, which is what those tests are
for.

serveIssueRoles now returns the whole set as a struct rather than a growing
list of unnamed results, so a role added to Config without being added here
is a compile error at the call site instead of a startup failure. It stays a
struct rather than an httpapi.Config because the gate test in serve_test.go
requires every httpapi.Config literal in cmd/bd to sit in a function that
consulted serveDatabaseSource, and the extraction has not.

Two test doubles needed the new accessors. serveRolesStore returns nil for
the eleven it does not exercise, which is honest: it never reaches Listen,
and reader and claimer are enough to pin the peel DEPTH that test is about,
since serveIssueRoles peels once and calls every accessor on that one value.
serveIdentityStore does reach Listen, so its roles must be non-nil; they
embed their interfaces rather than implementing them, keeping that file's
stated preference for a nil-panic naming the method over a stub that
answered.

THE TEXTUAL FOUR.

.golangci.yml — both sides edited the same forbidigo path lists. Resolved as
set arithmetic against the merge base rather than by picking a side, then
verified programmatically: every addition from either side survives and every
removal from either side survives.

CHANGELOG.md — unioned.

create_proxied_server.go — rerere replayed a prior resolution; verified by
reading that it carries both main's refusal text and this series' CreateOnly
lifecycle flag rather than one at the cost of the other.

serve.go and serve_test.go — took main's substantive rewrites, re-applying
this series' corrections on top: the extended unauthenticated-surface warning
now names bulk delete, and the roles paragraph says "every role accessor"
rather than "both".

serve_test.go's AST gate keys off Reader+Claimer as the roles-source signal.
That is sound for the question it asks — which database source did this
Config name — but the pair is now hand-maintained against a thirteen-role
struct, so it carries a note pointing at bd-lidlu.
2026-08-06 05:40:12 +00:00
CI Bot
903cbe0313 fix(delete): stop rewriting live rows' text to say a surviving issue was deleted
`bd delete <wisp> --cascade --force` deleted the wisp, LEFT ITS DEPENDENTS
ALIVE, and then edited those dependents' neighbours to say they were gone.
After the call a surviving issue's description, notes, design or acceptance
criteria read `[deleted:bd-xxxxx]` about a row that was still in the table.
`bd wisp gc` hardcodes cascade, so this was reachable from routine
housekeeping rather than from an exotic flag combination.

The cause was one set computed twice, from different inputs:

  issueops/delete_role.go  FindAllDependentsInTx(ctx, tx, ids)         <- all ids
  issueops/delete.go       FindAllDependentsInTx(ctx, tx, regularIDs)  <- wisps dropped

The first produced the set whose citations were rewritten. The second produced
the set that was actually deleted. A row reachable only through a named WISP
root landed in the first and not the second, so the cascade silently
under-deleted what the caller asked for AND the rewrite corrupted text on rows
nobody had named. Two harms, one drift.

Converged on deleting the closure rather than narrowing the rewrite: that is
what --cascade promises, what issueops/deleter.go's DeleteRequest.Cascade says
the closure is ("in both planes"), and what the unit-of-work body — the other
Deleter implementation — already did through domain.deleteMany. The store body
was the outlier.

The two sets can no longer drift because there is now only one. A new
issueops.DeletionSet is resolved ONCE by ResolveDeletionSetInTx, and the same
value is handed to the neighbourhood read, to DeleteResolvedSetInTx and to
RewriteDeletedReferencesInTx. Nothing downstream recomputes it.

Two further cross-plane defects in the same neighbourhood, both found by the
new cases rather than by reading:

  - The store body's dependents guard read the DURABLE half of the request
    only, so a wisp named with a durable dependent was neither refused when
    unforced nor reported as orphaning when forced. It now asks about every
    named id in both planes, which is what the leaf always said and what the
    uow body always did. The storage-seam guard inside DeleteIssuesInTx stays
    durable-only on purpose and says why: the server-backed store peels wisps
    off before reaching it, so widening it there would make the two stores
    refuse differently.

  - The uow body left a DANGLING edge: there is no foreign key from
    dependencies to wisps, so deleting a wisp did not remove the sync-plane
    rows pointing at it. Force promises the dependent is orphaned, not that it
    keeps an edge into a row that no longer exists. The store body has always
    deleted those rows explicitly; domain.deleteMany now does too.

Three conformance cases pin the quadrant, on all three wirings. All three were
RED on the store legs before this change:

  CascadeFromAWispRootDeletesTheClosure
      "Deleted = 1, want 3 — the wisp, the durable row that depends on it,
       and ITS dependent"
  GuardsAWispNamedWithADurableDependent
      "Delete(dryRun=false) unforced over a wisp with a durable dependent:
       error = <nil>, want ErrDependentsOutsideRequest"
  NeverCallsALiveRowDeleted
      "del-live-dependent STILL EXISTS and the survivor's description calls it
       deleted: \"unblocks [deleted:del-live-dependent], tracked under
       [deleted:del-live-root]\" — the rewrite set is wider than the deletion set"

The third is the one that makes this class hard to reintroduce: it reads a
surviving row's stored text back and requires every `[deleted:<id>]` marker to
name a row that is really gone, and every id that is still there to still be
named verbatim. No count can see that — an implementation whose rewrite set is
a superset of its deletion set reports a perfectly plausible
ReferencesUpdated.

The suite was 59 cases green on three legs while two of them contradicted the
third: no existing case seeded a cross-plane dependent edge. ErasesAcrossBothPlanes
used an edge-free issue/wisp pair and every cascade and guard case was
durable-only.
2026-08-06 04:27:26 +00:00
CI Bot
4588d867a1 feat(issueops): put bd dep tree behind the TreeWalker role (bd-lx5iu)
`bd dep tree` had two implementations of one walk. The direct route resolved a
partial id, opened a prefix-routed store and called store.GetDependencyTree; the
proxied route took the id verbatim, opened a unit of work and called the use
case. Each then carried its own copy of the `both`-direction merge, the status
prune, the mermaid and human rendering and the empty-tree wording. The copies
agreed, which is the only reason nobody noticed that a `both` walk was two
independent reads with nothing spanning them. Both now build one
issueops.WalkTreeRequest and ask for the role.

THE ROLE, and both its neighbours said in advance why it had to be one.
Relations and EdgeReader each exclude the tree in the same words -- "a recursive
walk has a depth, a cycle policy and a node shape of its own" -- and all three
are on this contract: MaxDepth, the first-visit rule, TreeNode. It is not
CycleDetector either: a cycle has NO anchor and a tree is nothing but its
anchor, and the two disagree about what an edge is -- this walk follows every
type except `relates-to`, the cycle report follows `blocks` and
`conditional-blocks` only -- so one workspace can honestly have no cycles and a
tree that revisits a node.

ONE BODY, THREE LEGS, AND THAT IS ONE VOTE. Unlike every other role in
backend/conformance, all three implementations reach the same function: the two
stores wrap issueops.WalkDependencyTreeInTx in five lines around their own
transaction and the unit of work reaches it through a new domain repository
method. So TestTreeWalkerContract x 3 is one reading of the walk plus an engine
check, not three backends agreeing, and the contract file says so at the top.
What the legs still buy is the WRAPPERS, which is where every measured drift in
this graph family has actually lived -- so the refusals assert SENTINELS rather
than message text and the cap case asserts the typed error's fields. The parts
that decide what the answer MEANS are pure (ValidateWalkTreeRequest,
PruneTreeByStatus, MergeBidirectionalTree) and are pinned without a database.

TWO USER-VISIBLE CHANGES ON THE PROXIED ROUTE, both in the owner's Q11 set, both
in CHANGELOG.md.

  PARTIAL IDS RESOLVE. `bd dep tree a1b2` worked on a direct workspace and
  failed on a team server, because this route passed the argument to storage
  verbatim. It resolves in its own short-lived read unit of work before the role
  is asked for anything, so a lookup that finds nothing reports the lookup
  failure rather than a provider that cannot offer a surface.

  --max-rows IS HONORED. It used to be refused outright ("not supported in
  proxied-server mode") because the unit-of-work path threaded no cap. The cap
  is on the role's request now, so the shared body enforces it for all three
  backends and the flag means the same thing wherever the command runs. It is
  still POST-HOC -- a tree walk has no query filter to thread a cap through --
  and both the leaf doc and --help say so. The shared --max-rows help text
  forked for this (addRoutedMaxRowsFlag): the proxied-server refusal is still
  true for the eight other commands that take the flag.

A DEFECT FIX NOT ON THAT LIST, recorded as AMBIGUITIES.md A-twk-1: a `both` walk
now sees ONE database state on every route, where it used to be two
unsynchronised reads that could show half an edit.

Q7 IS OBEYED. --show-all-paths stays a no-op -- accepted, ignored, and now
DOCUMENTED as ignored -- and TreeNode.Truncated stays always-false for the same
reason. The one-visit rule that makes both dead is now a stated promise
(TreeResult.Nodes) and a conformance case (RendersASharedSubtreeOnce), so
implementing either as a side effect of a later refactor fails a test instead of
shipping.

CONFORMANCE. backend/conformance/tree_walker_contract.go holds fifteen cases
citing the leaf doc by line, run at all three implementations with ZERO parks:
45 subtests green. Seeding a cycle takes raw SQL for the reason the
cycle-detector contract records -- no supported write creates one -- so that one
case uses the fixture's Exec hook.

HTTP. GET /v0/beads/dependencies/tree, spec first and the types generated
against it. TreeNode is x-go-type-pinned to internal/types, so `bd dep tree
--json` and the response body are one compatibility domain, and
DependencyTreePage's Items are pinned in pinning.go -- the trap wave 2 fell into
with DependencyEdges (bd-5o3gt), not repeated here. A root that names nothing is
a 404, which is the difference from GET /v0/beads/dependencies: one anchor
leaves no other answer to preserve. No max_rows on the wire; the cap is a CLI
circuit breaker. `capabilities` gains dependencies.tree, and TreeWalker becomes
a required field of the store-shaped httpapi.Config, which costs the in-tree
tests a line each and no shipped caller anything (bd serve builds a provider).

NOT TOUCHED: the legacy DetectCycles seam bd-5g4f2 is about. This walk reads
GetDependencyTreeInTx and never AppendBlockingGraphInTx, so the two-cycle-answers
problem is exactly where it was.

Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check green;
TestTreeWalkerContract 15/15 at dolt, embeddeddolt and uow; internal/httpapi 0
failures including the eight new tree-route cases; the pure tree_walk tests
green; TestEmbeddedMaxRowsNonListPaths green (DepTreeMaxRows still exits 2);
BEADS_TEST_PROXIED_SERVER=1 TestProxiedServerDep2 green including the four new
Tree cases; TestProxiedLookup* green; TestCorpusGolden green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-06 03:09:18 +00:00
CI Bot
27ffb42e1f feat(init): put bd init's identity seam behind Bootstrapper and InitVerifier (bd-zl3u8)
`bd init` had two implementations of what a workspace's identity IS. The direct
route read issue_prefix out of the config plane at init.go:1358 and _project_id
four hundred lines later, decided adopt-vs-write with two helper predicates, and
wrote both keys by name. The proxied route called domain.BootstrapUseCase, which
held its own list of which keys an identity is made of, wrote them
unconditionally, and folded the Dolt remote into the same call. The two agreed on
the key names and disagreed on the rule, and no test compared them.

ONLY THE IDENTITY SEAM IS A ROLE. Everything else init does — creating .beads/,
writing metadata.json and config.yaml, initializing git, installing hooks,
starting a Dolt server — CREATES the substrate or the workspace around it, and a
role is reached through an accessor ON a store, so it cannot be what makes the
store exist. init.go alone is 3,060 lines; this commit touches the part that
happens inside the database.

TWO ROLES, AGAINST THE VersionReconciler PRECEDENT. That one is a read and a
write on one role because they are two shapes of one question, and every word of
that is true here too. The test that separates them is different: can one caller
be entitled to the READ and not the WRITE? Here yes, and not hypothetically —
`bd init --team-server` adopts a bts-provisioned identity and is forbidden to
write one, and a gateway credential may be read-only. Those paths now hold an
InitVerifier and never obtain a Bootstrapper, which the type system checks;
with one role they would hold the writer and the suppression would stay where it
is today, in three should* predicates on the CLI.

Q8 ANSWERED IN THE ROLE. Bootstrap over an already-identified substrate is
ErrAlreadyIdentified, carried by an *AlreadyIdentifiedError naming what was
found, decided from the same read the write would have followed inside ONE
transaction. Either marker is enough: a substrate several rigs share carries a
prefix one of them chose, and overwriting it renames every id the others are
about to mint. The guard now sits below both front doors instead of in front of
one, so gateway and adopt paths inherit it, and re-identifying is something
somebody asks for rather than something init does twice.

THE ROLE OWNS THE IDENTITY AND NOTHING ELSE. BootstrapProject wrote six values;
BootstrapRequest carries two. The fingerprints, the synced-at marker and the
recorded binary version are refreshed on EVERY init, adopt or not — a fresh clone
of an already-identified database needs its own fingerprints precisely because it
bootstrapped nothing — so a refusable one-time write would mean either a refusal
that stops recording them or a write that is no longer one-time. bd_version has a
second reason: it is VersionReconciler's key. The Dolt remote left too; it is
where the database syncs to, not what it is, and putting them in one call is what
let a remote that could not be created fail a bootstrap that had already
succeeded. domain.BootstrapUseCase is DELETED and domain.ConfigUseCase gains
SetMetadata, the write half of the GetMetadata it already published, so the
unit-of-work body can read, refuse and write in one transaction.

THE DEFECT. Proxied `bd init` against a database another rig had already
identified rewrote both markers with its own derived values. It verifies and
adopts now, printing the direct route's existing line, with the role's refusal as
the backstop. The direct route's two identity reads also became one snapshot, so
the prefix it adopts and the project id it reconciles against can no longer come
from either side of a concurrent write; shouldConsultInitProjectID still gates
whether the id is USED, so which identities init adopts is unchanged.

CONFORMANCE. backend/conformance/bootstrapper_contract.go holds twelve cases —
both roles in one file, because every promise on either is a statement about the
other — run at all three implementations with ZERO PARKS and zero divergences.
They deliberately do not re-test the decision: the validator's and the refusal's
whole tables are pinned without a database in internal/workapi/bootstrap_test.go.
What only a real backend can show is asserted instead: that the identity is there
for the NEXT caller (a new transaction on the unit-of-work backend), that a
refusal and a validation failure leave the markers EXACTLY as they were, that the
verifier reports an unreadable identity as an error rather than as an empty one,
and that a bootstrap costs at most one version-control entry. Two independent
bodies plus an engine check, not three votes: dolt and embeddeddolt share
internal/storage/issueops.BootstrapInTx and VerifyIdentityInTx and differ only in
how they reach a transaction. The bodies live there rather than in an importable
store<role> package because the read and the write it qualifies must see one
snapshot, which storage.DoltStorage cannot express — so there is no constructor
for a depguard entry to deny.

NO HTTP OPERATION, and that is a decision. A server can only serve a database it
is already bound to, and binding it required the identity this role writes, so
the only caller that could reach such an endpoint would be asking a running
server to identify a workspace that is by construction already identified — which
is the refusal. Bootstrapping over an unauthenticated surface is a different risk
class from reading one. The read half already has an endpoint:
ContextResponse.project_id on GET /v0/beads/context is InitVerifier's answer, on
the wire, today. Recorded in both leaf docs and in the checklist.

USER-VISIBLE, for the wave's changelog pass: proxied init adopts instead of
overwriting on a shared database; `bd init` no longer heals a substrate carrying
a prefix and no project id, which is Q8 as written; an explicit BEADS_DIR outside
the repo now gets a project id written from its own metadata.json instead of
being left half-identified. Reasoning and the alternatives are in
/data/tmp/sd-server/AMBIGUITIES.md as A-ini-0..7.

A-ini-0 IS A FALSE PREMISE IN THE BRIEF, not a finding about the code: bd-zl3u8,
bd-jtp1h and bd-yby99 do not exist in the workspace at BEADS_DIR. Verified by two
bd binaries failing to open it and by a direct SQL read of all 5,603 issues.
Everything else the brief asserted about the code checked out, so the spec used
was the brief plus Q8 plus A2.

Verified: build, vet, gofmt clean; golangci-lint 0 issues (its unparam check is
what found resolveInitIssuePrefix's now-dead `write` return, removed here);
TestBootstrapperContract 12/12 at dolt, embeddeddolt and uow; internal/workapi,
internal/storage, internal/telemetry, internal/jira, issueops, the root layering
pins and the whole internal/storage/domain and internal/storage/uow packages
green; internal/httpapi green and `make api-check` clean with no spec or
generated diff; TestInit* and TestResolveInit*/TestApplyInitGateway* and
TestCorpusGolden and TestDoctor* green under BEADS_TEST_EMBEDDED_DOLT=1;
TestProxiedServerExternalCreate, TestProxiedServerPing and TestProxiedServerUpdate
green under BEADS_TEST_PROXIED_SERVER=1, each of which runs
`bd init --proxied-server` in its harness; TestProxiedLookup green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-06 03:01:33 +00:00
CI Bot
cf0a42cdae feat(delete): put bd delete behind the Deleter role and converge both routes (bd-x82so)
THE TWO ROUTES DISAGREED ABOUT WHAT --force MEANS on a destructive command.
On a local database `--force` deletes the named beads and orphans their
dependents; on a team server it deleted the whole dependent subtree, `--cascade`
was REFUSED outright ("not supported in proxied-server mode (delete always
cascades)") and Cascade was hardcoded true at both call sites. So there was no
way to delete one bead on a team server without taking everything under it, and
asking for the safer behaviour was an error.

Q1 ANSWERED IN THE ROLE. issueops.Deleter has one method, reached through
store.Deleter() and the provider's own accessor, and the three modes are request
fields: no flags refuses over a dependent the request did not name, Force
orphans it, Cascade deletes the closure. The guard is workapi's and the body's,
below every front door, for the reason Sweeper's require-a-filter gate is: a
second front door that inherited the capability without the guard would orphan a
workspace's graph by omission — which is exactly what this commit's HTTP
operation would otherwise have been.

IT IS A DIFFERENT ROLE FROM Sweeper, not a mode of it. Sweeper erases a set the
caller DESCRIBED; this erases rows the caller NAMED. That is what decides where
each one's safety lives: a description can be accidentally too wide, so Sweeper
carries a require-a-filter refusal; a list of ids cannot be, so this one's guard
is about the graph.

THE DEFECT. The direct route's batch path deleted the rows in one transaction
and then rewrote `[deleted:ID]` into the neighbours' text afterwards, discarding
every update error. A failure in the window left a workspace whose beads were
gone and whose descriptions still cited them by id. The existence probe, the
guard, the cascade expansion, the deletion and the rewrite are now one
transaction. WHAT THAT COSTS is written into the leaf beside the promise: the
transaction is as large as the deletion plus its neighbourhood, so a batch with
a very large neighbourhood fails whole. It is NOT Sweeper's trade (bd-hysee) —
the delete itself was already one transaction on every route — and the part that
is new is named rather than measured, which is recorded for sign-off.

TWO MORE DEFECTS the single call site removed. The one-id path held its own
transaction that removed each edge by hand, so it never reported labels, events
or orphans; and `domain.DeleteIssuesParams.EnforceCascadePolicy` and `.Force`
were declared, documented in fifteen lines describing exactly these three modes,
and READ BY NOTHING. They are deleted; the policy lives in the role now.

THE CONTRACT IS WHAT WAS DELETED, not what was reported.
backend/conformance/deleter_contract.go holds eleven cases, each citing the leaf
doc, run at all three backends with ZERO PARKS and zero divergences. Every case
that acts asserts row counts through QueryScalar rather than trusting the result
the delete reported about itself. They are TWO INDEPENDENT BODIES plus an engine
check: dolt and embeddeddolt share internal/storage/issueops.DeleteInTx and
differ only in how they reach a transaction, and the unit-of-work provider
reaches the same questions through the domain use cases. It does NOT duplicate
backend/conformance/audit_issue-lifecycle.go, which stays the right home for
`DeleteIssues` at the STORAGE seam: that suite's Factory hands back a bare
storage.DoltStorage, so the unit-of-work backend — where the guard did not exist
at all before this commit — can never run a case placed there.

`bd serve` gains POST /v0/beads/issues:delete, spec first. The dependents guard,
the all-or-nothing id resolution and the reference rewrite are the role's, so
the handler is argument validation and a projection. `cascade` and `force`
default false, which is the guarded mode; DeleteIssuesResult is not
x-go-type-pinned for the reason SweepResult is not, and a reflection test keeps
the projection honest. No page envelope, so nothing to pin in pinning.go.

USER-VISIBLE, and the CHANGELOG says so loudly: a team-server script relying on
the implicit cascade starts leaving orphans; `bd delete <one-id>` without
--force now refuses over an outside dependent, converging the direct route's
three paths onto the answer two of them already gave; the proxied `--json`
result gains `orphaned_issues`. Reasoning and the alternatives are in
/data/tmp/sd-server/AMBIGUITIES.md as A-del-1..6.

Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
(regenerate-and-diff plus the httpapi suite) green; TestDeleterContract 11/11 at
dolt, embeddeddolt and uow; the internal/workapi delete unit tests; the
internal/storage, internal/telemetry and root layering pins;
TestConformance/Audit/issue-lifecycle and the dolt TestDeleteIssues* family
(this commit refactors DeleteIssuesInTx's guard); TestEmbeddedDelete,
TestEmbeddedDeleteJSONDependencyErrorContract, TestBurnWisps,
TestWispGCProtectsActiveWisps and TestCLI_WispGCExcludeType under
BEADS_TEST_EMBEDDED_DOLT=1; TestProxiedServerDelete{,ForceOrphans,Wisp,
Concurrent}, TestProxiedServerMolBurn and TestProxiedServerWispGC under
BEADS_TEST_PROXIED_SERVER=1; and TestProxiedLookup*.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-06 02:59:08 +00:00
CI Bot
d10a388340 feat(list): put bd list behind Reader.List and the new BlockingAnnotator role (bd-5k21g)
STAGE TWO OF TWO. Stage 1 (aa10a725e) added MaxRows and SkipCounts to
ListRequest and flipped no routes; this is the flip, plus the one role the
decoration needed.

TWO PARTS, and the role first because the flip needs it.

THE ROLE. `issueops.BlockingAnnotator` answers the decoration a listing prints
beside each row — `(parent: X, blocked by: Y, blocks: Z)` — for the ids of a
page that has already been chosen. It is its own role rather than EdgeReader
growth (Q12 asked and answered two), and the distance between them is larger
than it looks: EdgeReader returns STORED ROWS of every type with targets
spelled as stored, no status consulted, and a per-anchor Missing flag from an
existence probe; this one returns a DERIVED summary of two types with closed
blockers dropped, the inbound direction included, and NO existence probe at
all. It is not Reader growth either — it has no order of its own, nothing it
returns depends on how the page was chosen, and a ListRequest field would have
implied the annotation was part of the query.

THERE IS NO MISSING FLAG, and that is a decision the leaf states rather than an
omission: an id that names nothing and an id with no live blocking edges
decorate identically, so a probe would be a read whose answer no caller can
use. One conformance case asserts that ABSENCE of a distinction.

A BLOCKER THIS DATABASE HOLDS NO ROW FOR COUNTS AS OPEN — an `external:`
reference, a foreign-repository id, a row whose issue was deleted. An
unreadable status is not `closed`, and a listing that hid a blocker it could
not resolve would report work as unblocked on the strength of a row it never
found. Both implementations already did this; it now has a sentence and a case.

THE ORDER WITHIN EACH LIST IS NOW PINNED, ascending with repeats collapsed, and
this is the commit's ONE user-visible change. Both lists are joined into one
line of output, so the query's natural order was user-visible bytes that could
move between runs. It affects only rows with two or more live blockers, and it
is recorded as A-blk-2.

TWO BODIES, NOT THREE. dolt and embeddeddolt share
storage/issueops.ExecuteBlockingAnnotation inside their own read transaction;
the unit-of-work provider is the genuinely separate one — it reads BOTH
dependency tiers for every id and merges, where the store side partitions the
ids by plane, and it resolves statuses only for the ids a row mentioned.
FinishBlockingAnnotation is what makes the SHAPE of the answer one decision
rather than two. Seventeen cases, three wirings, ZERO PARKS.

THE HTTP HALF. GET /v0/beads/dependencies/blocking, spec first, `make api-gen`
after. `IssueBlocking` is x-go-type-pinned to the role package the way `Cycle`
and `CycleMember` are, and BOTH the schema and the envelope's Items are pinned
in internal/httpapi/pinning.go — the v2.6.0 allOf trap was checked (the
generated type is a bare alias) and bd-5o3gt did not become two. The size bound
is maxDependencyAnchors, SHARED with the stored-edge read rather than given a
constant of its own: the two operations are asked about the same page of ids,
and two numbers would let a client ask one about a page the other refuses.
`dependencies.blocking` joins the capability vocabulary; `checkDatabaseSource`
grows a required role, which is the edit that reaches code this commit did not
write.

THE FLIP, one mode at a time and named as such in the code. FIRST `--json`:
the role's List runs the same LoadStoreListConfig, the same BuildListFilter and
the same workapi.FinishPage the branch ran longhand, so the page is unchanged
bytes and ErrTooManyRows still reaches handleMaxRowsError for exit 2. SECOND
every text rendering, with SkipCounts set — stage 1 added that field for this
arrival, and without it the flip would trade a plain scan for three aggregate
joins on the most-run command in the tree. THIRD the decoration.

WHAT STAYS OFF THE ROLE is --watch and the hierarchical --parent tree, the two
modes that consume the FILTER as a value. The bead also named --deps and
--format, and its stated reason — "reach no epilogue on either route" — is
false for both: they run FinishPage and printTruncationHint today. What is
genuinely off-role in those two is the WHOLE-GRAPH dependency-record load they
perform, which is neither a page nor the blocking decoration; their page comes
from the role like every other mode's. Recorded as A-blk-3 with the reading
this commit proceeded under, which is also the reading stage 1's own message
states ("stage 2 moves bd list's TEXT path onto the role").

The proxied route loses `runListProxiedReady`: --ready is ListRequest.ReadyFlag
and picking the ready query from it is the role's job on both routes. Two
functions differing only in which use-case method they called is the drift this
replaces.

PROVABLY INERT AT THE CLI, measured rather than argued: 31 `bd list` / `bd
children` invocations — every output mode, both cap knobs, --ready, --parent,
--format, --deps — run against a binary built from integration/facade-wave-3
and one built from this commit, over ONE shared workspace, differ on exactly
the two multi-blocker lines A-blk-2 predicts and nothing else in 687 lines. A
base-against-base run isolates the one other moving line as the
once-per-period install tip.

The forbidigo exception list did NOT shrink, and the count in
issueops/reader.go's claim is unchanged. cmd/bd/list.go and
list_proxied_server.go were never on it; cmd/bd/list_show_filter_modes.go still
is, because the tree walk, the watch loop, the proxied builder call and `bd
show --current` all still name the type. Said in the config rather than implied
by silence.

Verified: build, vet, gofmt clean; golangci-lint 0 issues; the seventeen new
cases at dolt, embeddeddolt (BEADS_TEST_EMBEDDED_DOLT=1) and uow, all green
with no skips; internal/httpapi and make api-check; internal/storage,
internal/telemetry, internal/jira, internal/workapi/..., issueops and the root
layering pins; the embedded `bd list`/`bd children`/max-rows CLI suites,
TestProxiedServerList under BEADS_TEST_PROXIED_SERVER=1 (58 subtests including
tree_parent, the three format modes, ready pagination and the three max-rows
refusals), TestProxiedLookup*, and the protocol corpus package.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-06 02:56:57 +00:00
CI Bot
8386871574 feat(create): put bd create --file behind the BatchCreator role (bd-lu170)
`bd create --file plan.md` had two implementations of one bulk create. The
direct route built types.Issue values in cmd/bd/markdown.go and handed them to
store.CreateIssues; the proxied route parsed the same templates again, opened a
unit of work, read a create context, checked the types itself and looped the
domain use case. Both now build ONE issueops.CreateBatchRequest from one shared
projection, and the difference between the two routes is which accessor answers.

THE ROLE. A batch's REQUEST is its transaction boundary, which is the same
reason BatchCloser exists and cannot be a loop over Lifecycle.Close: N creates
one call at a time are N transactions and N history entries, and the caller who
wants them to land together has no way to say so. It is its own role rather than
a Create overload because it is ALL OR NOTHING where the batch close keeps its
survivors, and one method cannot make both promises. The difference is what has
already happened: a close records work that is done, so a rollback destroys
information the batch was carrying; a create makes the work, so a refused item
leaves no survivors, and half a created plan cannot be re-run without
duplicating the half that landed.

It is born with Provenance, which CreateRequest does not have. Both --file
routes have always written `bd: create N issue(s) from <path>`, and a label
composed from the result cannot spell a file the result does not carry, so
without the field this commit would have caused the regression Q16 recorded
rather than inherited it.

USER-VISIBLE, and bigger than the bead described. The bead and the Q11 batch say
direct --file is non-atomic today - "a bad row can leave earlier rows created".
Reading the path does not support it: markdown.go built every issue first and
made ONE store.CreateIssues call, which both stores run in a single SQL
transaction. What was true is worse, and is recorded as Q25/Q26 in
AMBIGUITIES.md with A-bcr-2:

  - a dependency naming an id that does not exist was SILENTLY DROPPED on the
    direct route (the batch engine skips a dangling edge and nothing passed
    OnSkippedDependency), while the proxied route already failed on it. Every
    requested edge is now written or the batch refuses. An `external:` target
    and an id belonging to another repository are still written, exactly as
    `bd dep add` accepts them.
  - --ephemeral, --no-history, --mol-type and --validate were accepted and
    IGNORED on the direct route while the proxied route acted on all four, so
    `--file --ephemeral` created durable issues locally and wisps on a team
    server. All four now mean what they mean everywhere else, templates are
    linted on both routes, and created_by/owner are set as the single-issue
    create sets them.
  - --file --json emits the stored post-create rows on both routes. Additive.
  - proxied --file loses its config.yaml fallback for types.custom, the
    convergence Q17 already recorded for single-issue create.

--graph is untouched, per Q10: an upsert over a declared shape is a different
contract and gets its own role when it gets one.

CONFORMANCE. backend/conformance/batch_creator_contract.go holds nine cases,
each citing the leaf doc by line, run at all three implementations with ZERO
parks: 27 subtests green. They are TWO independent bodies plus an engine check,
not three - dolt and embeddeddolt share issueops.ExecuteCreateBatch, which
prepares every item and hands the slice to one CreateIssuesInTxWithResult, while
the unit-of-work body creates item by item through the domain use case and keeps
"all or nothing" by returning early and letting the transaction roll back. That
is also why no case asks for a FORWARD reference inside a batch: the store body
could resolve one and the uow body provably cannot, so the role promises only an
edge onto an EARLIER item and the contract says so at the case site (A-bcr-4).

The store-backed body is an InTx function rather than an internal/workapi/store
package, the documented variant EdgeReader introduced: it must assign every id
before any row is written so an item's edge can name a sibling, which cannot be
expressed above storage.DoltStorage. It needs no depguard entry for the same
reason - the shared function takes a transaction, so no front door can call it.

HTTP. POST /v0/beads/issues:batchCreate is new canonical surface, spec written
first and the types generated from it. It is a collection-level custom method
spelled the way ready:count is, which leaves POST /v0/beads/issues free for the
single create that belongs there; it does not collide with the claim row's wide
POST wildcard, because that pattern requires the separating slash
(TestBatchCreateDoesNotShadowTheClaimRoute drives both). BatchCreateResponse
carries no allOf, so the oapi-codegen v2.6.0 pin-dropping trap does not apply,
and its Items are pinned to []types.Issue in pinning.go.

The wire publishes no `id` member, which is what keeps the role's
ErrAlreadyExists off a vocabulary that has no already_exists code (A-bcr-5): the
server assigns every id and `bd import` remains the upsert surface. The role's
ErrValidation is answered by the operation's own failure path rather than by
ClassifyError, because the dangling-edge refusal wraps BOTH ErrValidation and
ErrNotFound and the shared classifier reaches ErrNotFound first - a 404 for a
request that addressed no resource. Neither branch quotes the role's message: a
refused edge arrives as a driver error naming tables and constraints, and 4xx
details here reflect the caller's input.

httpapi.Config's roles source grows to eight roles. The half-set cases that
built a Config by hand now go through rolesConfig, so the next role does not
have to edit six literals that are not about the role set.

Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check clean;
TestBatchCreatorContract green at dolt (9/9), embeddeddolt (9/9) and uow (9/9);
./internal/httpapi green including eleven new batch-create tests; TestCorpusGolden
green (the corpus has no --file capture); TestCreateFromMarkdownFile green; the
cmd/bd create suites green with BEADS_TEST_EMBEDDED_DOLT=1 and the proxied
integration create suites green with BEADS_TEST_PROXIED_SERVER=1;
TestProxiedLookup green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 16:43:11 +00:00
CI Bot
519fb1479b feat(issueops): put bd purge and bd prune behind the Sweeper role (bd-pn231)
`bd purge` selected closed wisps in one transaction and deleted them in
another. A bead closed, unpinned or cited in the window between the two was
judged on one state and acted on in a different one — the TOCTOU the bead
names — and the proxied twin held a second copy of the whole flow: its own
candidate filter, its own glob match, its own closed_at recheck, its own
reference scan and 190 lines of output kept character-identical to the direct
route's by hand.

PURGE AND PRUNE ARE ONE CAPABILITY, which the design left open and the code
answers plainly: both routes already ran ONE function with a `purgeScope`
struct choosing the tier. So issueops.Sweeper has ONE method, reached through
store.Sweeper() and the provider's own accessor, and SweepRequest.Tier selects
the plane — `ephemeral` is purge, `durable` is prune, and the two are disjoint
by construction. What genuinely differed became request fields rather than a
second role: the require-a-filter refusal keys on Tier, and the citation
protection is ASKED FOR (ProtectReferenced) instead of being inferred from a
command name, which is what the shared body did (`scope.cmdName == "prune"`).

Q9 ANSWERED IN THE ROLE. The require-a-filter gate is
workapi.ValidateSweepRequest, below every front door: a durable sweep with
neither a cutoff nor an id pattern is ErrValidation. It is a safety invariant,
not presentation — without it a second front door is one handler away from an
unguarded mass delete, which is exactly what this commit's HTTP operation would
otherwise have been. The CLI keeps its friendly message, and says in place that
it is there for the WORDING while the guard is the role's; the contract case is
what proves the guard survives that branch being deleted.

THE DEFECT, AND ITS PRICE. The whole sweep is now one transaction, so the set
the result describes IS the set it deleted. That gives up the server-backed
store's batched wisp deletion (200 per transaction, added for Dolt's 10s write
timeout after bd-2ehd and ff-tqm): a sweep too large now fails WHOLE. That is
the better failure — the partial one it replaces reported a deleted count of
ZERO while having deleted rows — and the other two backends already worked this
way. It is written down as a promise WITH its cost, and recorded for sign-off.

TWO MORE DEFECTS the single call site removed. `--dry-run` passed force=false
to the delete where the real run passed force=true, so a preview could FAIL
over dependents the sweep would have orphaned — and the CLI answered that
failure with zeros. And `filepath.Match`'s error was discarded on both routes,
so `--pattern '['` printed "No closed beads to prune" and exited 0; it is now
ErrValidation quoting the pattern.

THE CONTRACT IS WHAT WAS DELETED, not what was reported.
backend/conformance/sweeper_contract.go holds ten cases, each citing the leaf
doc, run at all three backends with ZERO PARKS and zero divergences. Every case
that acts asserts row counts through QueryScalar rather than trusting the
result the sweep reported about itself, which on a destructive operation is the
assertion that matters; every case scopes itself with an id pattern, because a
sweep is asked of a whole TIER and an unscoped one would clear the next case's
seeds. They are TWO INDEPENDENT BODIES plus an engine check: dolt and
embeddeddolt share internal/storage/issueops.SweepInTx and differ only in how
they reach a transaction, and the unit-of-work provider reaches the same four
questions through the domain use cases.

THE HTTP OPERATION, spec first (per bd-jtp1h's A2 scope decision):
POST /v0/beads/issues:sweep, capability `issues.sweep` — the first DESTRUCTIVE
operation on a surface that was reads plus one claim. It is a collection-level
custom method with a body rather than DELETE with a query string, because a
dropped query parameter widens what is erased where an unknown body member is
refused by name. The handler decodes six members and calls the role; it does
not implement the safety gate, the tier vocabulary or the glob, all of which
are the role's ErrValidation reaching the wire as a 400 through failSweepErr.
No component carries allOf and none is x-go-type-pinned — there is no canonical
Go struct whose JSON encoding is this body, since the CLI publishes these
numbers under `purged_count`/`pruned_count` — so the projection is tested
instead. `bd serve --help` grew a DESTRUCTIVE OPERATIONS section and the
--allow-non-loopback warning now says peers can bulk-delete closed beads.

`bd gc` keeps the closed-candidate recheck by calling the SAME pure function
the role calls (workapi.FilterSweepCandidates), so the two cannot drift; the
reference matcher and its 10K-body budget moved to internal/workapi with the
scan. cmd/bd/purge.go and purge_proxied_server.go LEFT the forbidigo exception
list, which is how a role commit proves its front doors reached the role.

USER-VISIBLE, for the wave's changelog pass: the version-control label for a
sweep is now `bd: sweep <n> <tier> bead(s)` on both routes, where proxied wrote
`bd: prune <n> bead(s)` and direct wrote `bd: delete <n> issue(s)` — an HTTP
sweep is not `bd prune`, so the label names the operation and the tier from
every door; a malformed `--pattern` now exits non-zero; `--dry-run` no longer
refuses over dependents the real sweep orphans; and `bd serve` gains a
bulk-delete endpoint. Reasoning and the alternatives are in
/data/tmp/sd-server/AMBIGUITIES.md as A-swp-1..9.

Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
(regenerate-and-diff plus the httpapi suite) green; TestSweeperContract 10/10 at
dolt, embeddeddolt and uow; the internal/workapi, internal/storage and
internal/telemetry suites; TestEmbeddedPurge, TestEmbeddedPurgeConcurrent,
TestEmbeddedPrune, TestPrune_protectsBeadCitedByCustomStatusBead and
TestEmbeddedGC under BEADS_TEST_EMBEDDED_DOLT=1; TestProxiedServerPrune under
BEADS_TEST_PROXIED_SERVER=1; TestProxiedLookup*; and the root layering pins.
The protocol corpus has no purge/prune case to account for.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 16:40:26 +00:00
CI Bot
aa10a725e5 feat(list): put bd list's row cap and counts hydration on ListRequest (bd-b34o7)
STAGE ONE OF TWO. Fields, not methods, and no route flips — those are stage 2
(bd-5k21g). `issueops.ListRequest` gains MaxRows, MaxRowsSource and SkipCounts,
each with a conformance contract running at all three backends and zero parks.

MAXROWS IS THE EXACT INVERSE OF OFFSET, which is why it needed no new shape.
Offset is honored by the unit-of-work body — it renders OFFSET — and refused by
the store-backed one with a typed *ErrUnsupported. The cap points the other way:
the store search path enforces it after the scan (EnforceMaxRowsCap), and the
unit-of-work query path (internal/storage/domain/db) reads no cap at all, so a
request carrying one would come back as the FULL uncapped answer with nothing on
it to say so — a caller that set a circuit breaker handed exactly the runaway
query it was guarding against. It refuses instead, naming the operation and the
backend. `bd list --max-rows --proxied-server` has always refused one layer up
in the CLI for that reason; this is the same refusal for the callers that are
not the CLI. RunReaderListMaxRowsIsHonoredOrRefused mirrors
RunReaderOffsetIsHonoredOrRefused, including the never-silently-ignored clause,
and asserts the complement too: a cap the result set FITS inside must still come
back as an ordinary page, or a body that refused every cap out of hand would
pass.

MAXROWSSOURCE is the third field and the bead named two. It is attribution
only — it decides no answer — but `handleMaxRowsError` falls back to
"BEADS_MAX_ROWS" when it is empty, so a request that carried the number without
the source would make stage 2's route flip start telling operators to raise the
wrong knob. The contract asserts it comes back on the cap error.

SKIPCOUNTS is the SkipLabels precedent one column over: the three cardinality
joins are dropped and DependencyCount/DependentCount/CommentCount come back
zero, to be read as unknown rather than as none. It has to land WITH MaxRows —
stage 2 moves `bd list`'s TEXT path onto the role, and that path calls
SearchIssues today and projects no counts at all, so arriving on a counted page
without a way to opt out is a straight perf regression. The expensive member is
the reverse-blocker aggregate, which joins on a COALESCE key the pure-Go
analyzer cannot auto-index — the known embedded sore point, and the reason the
knob is worth having at all.

The contract's second half is the load-bearing one: NOTHING ELSE MOVES. Same
rows, same order, same has-more, same Parent — asserted by running the identical
request both ways rather than against a written-out expectation. Parent is the
tripwire: it rides the same mega-query and is not a cardinality, so an
implementation that made an aggregate join inner, or suppressed the parent join
too, would answer a strict subset and still look like it had "skipped the
counts".

WHAT THE SQL DOES. sqlbuild.SearchCountsSQL's two trailing hydration bools
become one CountsHydration value, so a path cannot pick up one opt-out and drop
the other, and both stores plus the unit-of-work repository read the pair
through one helper. A suppressed aggregate is projected as a constant IN PLACE
rather than removed: the scan reads the six extra columns positionally, so the
shape is invariant. Ready work passes the zero value at every call site —
types.WorkFilter carries neither knob, which is what "SkipLabels and SkipCounts
are not carried onto the ReadyFlag arm" means, now stated where a caller reads
it. MaxRows IS carried there; reader_ready_scope.go already claimed so, and this
is the commit that makes the claim true, since until now the field existed only
on the filter.

ONE HAND-ROLL DELETED. `bd list` built the filter through the shared builder and
then reached in and stamped filter.MaxRows/MaxRowsSource onto it — the
"build it, then change it" half-step this programme exists to make unreachable,
and the reason the cap was invisible to every implementation of Reader.List. The
cap is resolved in gatherListInput onto the request, BuildListFilter is now the
only writer of those two filter fields, and the proxied refusal reads the
already-resolved value (rejectResolvedMaxRowsUnderProxiedServer) so a malformed
BEADS_MAX_ROWS still warns exactly once.

PROVABLY INERT AT THE CLI, measured rather than argued: 22 `bd list` / `bd
children` invocations — every output mode, both max-rows knobs, the malformed
and negative cases — run against a binary built from integration/facade-wave-2
and one built from this commit, over ONE shared workspace so both read identical
data, differ on exactly one line of 617. `bd list --max-rows -1 --status bogus`
now reports the malformed flag instead of the invalid status; both exit 1, it
needs two bad arguments to reach, and it is recorded as A-lst1-3.

NO OPENAPI OPERATION AND NO NEW QUERY PARAMETER, deliberately, recorded as
A-lst1-1. `bd list`'s operation (GET /v0/beads/issues) already exists and is
already on the role, and neither field can be published on it yet: `bd serve`
always builds a provider-backed server, which REFUSES max_rows, so the parameter
would be one the reference server can never honor; and skip_counts would set
three unconditional integers on a PINNED response component to zero, leaving a
client unable to tell "no dependencies" from "not computed" — the failure
comments_omitted exists to prevent on the detail view. `make api-check`
regenerates nothing.

Verified: build, vet, gofmt clean; golangci-lint 0 issues; the two new cases at
dolt, embeddeddolt (BEADS_TEST_EMBEDDED_DOLT=1) and uow, plus the whole Reader
contract at all three; the builder golden (35 recorded cases plus two new ones
for the new fields) and the counts-SQL shape test; internal/httpapi and
make api-check; internal/storage/{issueops,domain/...}, internal/workapi,
internal/types, internal/telemetry, the root package; the embedded
`bd list`/`bd children`/max-rows CLI suites, TestProxiedServerList under
BEADS_TEST_PROXIED_SERVER=1 (including reject_max_rows_flag,
reject_max_rows_env and allow_max_rows_zero), TestProxiedLookup*, and the
protocol corpus package.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 16:36:31 +00:00
CI Bot
671c7801d2 feat(query): put bd query behind the Querier role and stop it dropping matches (bd-pohmh)
`bd query "type=bug OR label=urgent"` has been answering with a prefix of its
answer and calling it complete. The expression language has OR, NOT and
parentheses, which no storage filter expresses, so both routes fetched a WINDOW
of candidate rows — max(3*limit, 100) — and applied the expression to those in
memory. A match past row 100 was absent from the page and unreported by
has-more. The same six lines of arithmetic were written twice, once per route,
and both copies were wrong in the same way.

THE ROLE. issueops.Querier, reached through store.Querier() and the provider's
own accessor. One method over a request whose predicate is a SENTENCE rather
than a set of fields, which is what makes it a role instead of a mode of
Reader: a ListRequest is a conjunction — every field narrows — and no
arrangement of its twelve callers' fields expresses a disjunction. It is
equally not a raw query passthrough; the language names no table, no join and
no column outside a closed vocabulary, which is why a contract can promise
anything about it at all.

THE FIX, which Q3 approved as user-visible. A predicate query's filter now
carries NO row limit: the predicate sees every candidate row, the page is the
first Limit MATCHES of the complete matching set, and has-more is exact. The
decision has one home, internal/workapi.BuildQueryPlan, which both bodies
execute. The cost is stated rather than hidden — a broad OR over a large
workspace now reads every row its base filters admit — and CHANGELOG.md says so
in the same words.

WHAT PINS THE FIX, at three levels, because the contract alone cannot see it.
TestBuildQueryPlanLeavesAPredicateQueryUNBOUNDED asserts the arithmetic in
microseconds. TestAPredicateQueryFindsAMatchBeyondTheOldWindow seeds 101 rows at
ONE backend and reads back the match at row 101 — verified to discriminate:
with the old window temporarily reinstated it returns zero rows. The portable
contract asserts the PROMISE the window broke (a page is a prefix, has-more is
exact) and, confirmed by the same experiment, does NOT discriminate the old
window at its small scale; the contract's header says so rather than implying
coverage it does not have.

THE CONTRACT. backend/conformance/querier_contract.go holds nine cases, each
citing the leaf doc by line, run at all three backends with ZERO parks. TWO
independent bodies plus an engine check: dolt and embeddeddolt share
internal/workapi/storequerier, and the unit-of-work provider is genuinely
separate — it is the only leg on which the Offset case takes its HONORED branch,
since that seam renders OFFSET where the store body refuses uniformly.

TWO SMALLER USER-VISIBLE CHANGES ride along, both filed in AMBIGUITIES.md
(Q22, Q23) for the owner's batch. `--offset` with an OR/NOT expression is no
longer refused: the offset skips MATCHES, which is only meaningful now that
every match is seen, so an error became an answer. `--limit -1` is now
ErrValidation instead of an undocumented second spelling of unlimited. The
`--offset` + `--sort` refusal survives and moved INWARD — the role makes it, for
every caller, because the order is applied to the rows the query bounded and
each page of an offset walk would be sorted for itself — so its wording changed
with its address, as did the wording of a malformed expression on both routes.

A DEFECT FOUND AND NOT FIXED, recorded as A-qry-1 rather than papered over: an
UNLIMITED request carrying an Offset renders SQL the Dolt engine answers with a
recovered panic (makeslice: cap out of range, out of topRowsIter). It predates
this role — `bd query --offset N --limit 0 --proxied-server` built the same
filter — and it is a storage-seam bug, so the contract case asks its question at
a bounded limit and says why at the case site.

THE HTTP OPERATION, spec first (per bd-jtp1h's A2 scope decision):
GET /v0/beads/issues:query, capability `issues.query`, answering a new QueryPage
{items, has_more}. It publishes no cursor and no `offset`: a predicate query's
matching set is assembled outside the database, so there is no keyset position
to encode, and an offset is honored by one database source and refused by the
other, which is not a difference to put on a wire. QueryPage carries no allOf
and its Items are pinned in pinning.go beside ReadyPage's and IssuesPage's — the
edit wave 2 missed once (bd-8ri3m). Adding a second sort enum made oapi-codegen
disambiguate the FIRST one, renaming the generated ListReadyWorkParamsSort
constants (Hybrid -> ListReadyWorkParamsSortHybrid); nothing outside the
generated file named them. httpapi.Config's roles source grows a required eighth
member, and a Config complete under the previous release is now refused at
Listen rather than nil-dereferencing on the first issues:query request.

WHAT ELSE CONVERGED. Both output modes read ONE query — the counted one --json
always used — so a predicate can no longer be applied to two different row sets
depending on the flag (A-qry-1's neighbour, Q24). The direct route prints the
truncation hint for the first time, not by new choice but because it finally has
an honest has-more to print.

Incidental: internal/storage/role_accessor_decorator_test.go's four
near-identical "the four read roles" paragraphs — one appended by each wave-2
slice — are collapsed into the one accurate paragraph the table needs. Same
defect as bd-8ri3m, comments only.

Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check green;
TestQuerierContract 9/9 at dolt, embeddeddolt and uow;
TestAPredicateQueryFindsAMatchBeyondTheOldWindow; the internal/httpapi package
suite; internal/workapi, internal/storage, internal/telemetry, internal/query
and the root package; TestEmbeddedQuery under BEADS_TEST_EMBEDDED_DOLT=1 and
TestProxiedServerQuery under BEADS_TEST_PROXIED_SERVER=1; TestProxiedLookup*.
The protocol corpus drives no `bd query` invocation and is untouched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 16:36:05 +00:00
CI Bot
75b2374890 feat(issueops): put the startup version reconciler behind the VersionReconciler role (bd-gkmft)
The version markers had two implementations of one rule. The direct route read
bd_version and bd_version_max out of the metadata plane in
cmd/bd/version_tracking.go, compared them with doctor.CompareVersions and wrote
them back; the proxied route opened a unit of work and called a ReconcileVersion
method on the config use case, which held its own copy of the same comparison,
the same two downgrade guards and the same high-water rule. The two agreed, but
nothing made them agree and no test compared them. Both now ask for a role, and
the difference between the routes is which accessor answers.

THE ROLE BELONGS TO NO COMMAND, and it is the only one in this programme that
does not. It fires from PersistentPreRun on EVERY startup, on both routes,
before the command the user typed has run — which is exactly why it went
unnoticed: `bd version` prints two strings, opens no store and reaches none of
this, so the state machinery was hiding behind a command that does not use it.

THAT ORIGIN IS A CONSTRAINT ON THE PROMISES, not a piece of history, and the
leaf doc says so where a reader will meet it. A role that runs before every
command pays for itself on every command, so it does two point reads on the path
that changes nothing, loads no configuration, takes no lock, repairs nothing —
and, the clause that matters most, it NEVER refuses the command in front of it.
A downgrade is an OUTCOME with a nil error, because an older binary is allowed
to use a workspace a newer one has opened; a genuine failure is an error the
CALLER logs and walks past, which both front doors do at debug level. A role
whose callers must ignore its errors has to say so where the promise is made
rather than leave each caller to decide.

TWO METHODS, ONE ROLE. RecordedVersion and ReconcileVersion are two shapes of
one question — the write's promise IS a statement about what a later read
returns — which is what the governing rule permits a role to be born with, and
WorkspaceConfig set the precedent. It is not padding: the direct front door
needs the READ alone. autoMigrateOnVersionBump probes a read-only store first so
an already-current workspace never pays for the writable open, and before this
commit that probe read the metadata key by hand — the "CLI knows the storage
key" shape this programme exists to remove, on the hottest path in the codebase.

WHY IT IS NOT WorkspaceConfig WITH TWO MORE KEYS. Two planes, two lifetimes. A
workspace setting is durable and travels with the database; these two markers
are dolt-ignored, do not survive a clone and are deliberately different per
machine. Publishing them through the settings plane would put a value that
cannot be shared behind an interface whose whole promise is that its values are.

ONE DECISION, THREE SUBSTRATES. workapi.PlanVersionReconcile is the pure planner
every implementation decides through; domain.ConfigUseCase LOSES ReconcileVersion
and gains SetLocalMetadata, the write half of the GetLocalMetadata it already
published, so the unit-of-work body can read, plan and write in ONE transaction.
Deleting the use-case method is what makes the rule single-sourced rather than
duplicated under a role.

CONFORMANCE. backend/conformance/version_reconciler_contract.go holds nine cases
run at all three implementations with ZERO parks and zero divergences. They
deliberately do NOT re-test the decision: the planner's whole table — upgrade,
no-op, both refusals, the catch-up to the mark, the dotted comparison in which
1.2.0 and 1.2.0-rc1 are equal — is pinned without a database in
internal/workapi/versionreconcile_test.go, and repeating it here would be
testing one pure function three times over three sql-servers. What only a real
backend can show is asserted instead: that a recorded marker is there for the
next caller (a new transaction on the unit-of-work backend), that a refusal and
a validation failure write NOTHING, that reconciliation adds no history entry at
all, and that a reconciliation which CANNOT COMPLETE reports an error and leaves
both markers standing. Two independent bodies plus an engine check, not three
votes: dolt and embeddeddolt share internal/workapi/storeversionreconciler.

The fixture carries one hook the frozen roleFixtureKit cannot supply, built at
each wiring site the way CycleDetectorFixture.Exec is: the two states that
matter most — a recorded version BELOW the high-water mark, and its catch-up —
are states the role can never produce, so they are seeded past it.

THIS IS THE FIRST COVERAGE THE DIRECT ROUTE'S RECONCILIATION HAS EVER HAD. Its
round-trip tests (MigratesVersion, AlreadyMigrated, RefusesDowngrade,
TracksMaxVersion) were deleted with the SQLite backend and never replaced; the
note recording that is still in cmd/bd/version_tracking_test.go. The seven
subtests of the deleted use-case method go with it, replaced by the exhaustive
planner table plus nine cases at three backends.

NO HTTP OPERATION, and that is a decision rather than an omission — recorded in
the leaf doc and as A-ver-2 for the owner. The markers are clone-local: they
describe the machine holding the database, so a remote client reading them
learns something it cannot compare against anything it holds. The one version
fact a client CAN act on, the serving binary's release, is already published as
ContextResponse.bd_version, which the document already names as the only field a
client may compare as a version. A write endpoint is worse: reconciliation is an
effect of a PROCESS STARTING, and a client asking a server to record the
client's version would be asking it to lie about which binary holds the
database. If the owner wants a read-only GET /v0/beads/version, the role, the
accessor and both bodies are already here.

NO USER-VISIBLE CHANGE. Every outcome is identical; only three debug lines
moved. One accidental behaviour became deliberate: a binary whose Version string
is empty used to be handled by the downgrade guard on a populated workspace and
by an equality short-circuit on an empty one, and is now an explicit
ErrValidation that writes nothing either way.

ENFORCEMENT. storeversionreconciler joins the cmd-bd-role-constructors deny
list. The version path never named types.IssueFilter, so there is no forbidigo
exception to remove. engdocs/ADDING_AN_ISSUEOPS_ROLE.md gains the two things
this role taught the checklist: a role may honestly have NO HTTP surface, and a
contract case may need a fixture hook for a state the role cannot produce.

Verified: build, vet, gofmt clean; golangci-lint 0 issues;
TestVersionReconcilerContract green at dolt (9/9), embeddeddolt (9/9) and uow
(9/9); the planner unit tests, both decorator enumerations, the root layering
pins, internal/jira and the internal/storage/domain/db config suite green;
internal/httpapi green and `make api-check` clean with no spec or generated
diff; TestReconcileVersionPersistsAcrossUOW green; TestProxiedLookup green;
`-run 'TestTrackBdVersion|TestAutoMigrateOnVersionBump|TestGetVersionsSince|TestMaybeShowUpgradeNotification|TestInitDoltMetadata'`
green under BEADS_TEST_EMBEDDED_DOLT and TestProxiedServerContext /
TestProxiedServerInfo green under BEADS_TEST_PROXIED_SERVER; TestCorpusGolden
green, so no command's JSON moved.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 16:35:01 +00:00
Steve Yegge
7c5e4236a1
feat(import): port bd import to proxied-server mode (bd-o58fz) (#5355)
* feat(import): widen issueops batch-create surface from *sql.Tx to DBTX (bd-o58fz)

Mechanical signature widening: CreateIssuesInTxWithResult and its transitive
closure (batch context, ID generation, orphan check, conditional upsert,
labels/comments/dependencies persistence, child counters, blocked recompute)
now take the existing DBTX interface instead of *sql.Tx. *sql.Tx satisfies
DBTX, so every classic caller compiles unchanged and no SQL changes; the
domain/db Runner (proxied unit-of-work) satisfies the same interface, which
lets the proxied import port call the SAME batch-upsert code instead of
mirroring its semantics in parallel SQL.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvU6bUda8oQjvG3zoa4uyX

* feat(import): add the Importer capability — one-transaction bulk import behind the uow provider (bd-o58fz)

The public issueops.Importer role lands one whole import batch in ONE unit
of work with ONE history entry: issue rows through the same batch-upsert
engine the classic stores run (issueops.CreateIssuesInTxWithResult over the
DBTX seam widened in the previous commit), memory records, and the optional
issue_prefix reconciliation. Engine callbacks are folded into the result
inside the attempt so RunTxResult's serialization retries cannot double-count.
Accessor follows the BatchCloserSource capability pattern on doltSQLProvider.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019aBRPPEe7c9LiiM6NABJJg

* feat(import): port bd import to proxied-server mode through the Importer capability (bd-o58fz)

Removes the proxied refusal. The parse loop, dedup filter, dry-run
classification, stale pre-filter, result assembly and reporting are now
shared seam-based code (importIssueLookup / importTitleSearcher), so both
modes classify and report through the same functions; the proxied write is
ONE ImportBatch call — rows, memories and the issue_prefix reconciliation in
one transaction with one history entry, per the one-commit-per-invocation
doctrine. The stale guard keeps its classic two-half shape (pre-filter read
+ RejectStaleUpserts inside the write transaction).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019aBRPPEe7c9LiiM6NABJJg

* test(import): pin the Importer role contract on the uow backend (bd-o58fz)

One batch = one history entry with direct content assertions (labels,
comments, dependency edges, memory value, commit message); idempotent
re-import; the in-transaction stale guard and --allow-stale restore; empty
batch commits nothing; prefix-sync-only commits under the sync message;
empty actor refused.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019aBRPPEe7c9LiiM6NABJJg

* test(import): proxied-server import journey (bd-o58fz)

TestProxiedServerImport: round-trip with direct content assertions (labels,
comment text, blocks edge, memory value) and the one-commit-per-invocation
oracle; idempotent re-import commits nothing; stdin '-' semantics and the
bd-axluy redirect guard; stale skip / --allow-stale restore / newer-row
upsert with the updated-issues report; --dry-run writes nothing; --dedup;
import as the sanctioned upsert door for an occupied ID.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019aBRPPEe7c9LiiM6NABJJg

* lint(import): annotate three gosec G705 stderr-progress lines (bd-o58fz)

Lion's #5355 gate review: import.go renderImportOutcome dedup/stale lines and
the import_shared.go chunk-progress line were missing the G705 nolint the
sibling renderImportDryRun lines already carry. Approve-on-green per #5346
convention.

* lint(import): annotate the fourth G705 progress line gosec surfaced on re-run (bd-o58fz)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-05 09:05:22 -07:00
CI Bot
b1b253f35b feat(ready): put bd ready's published total behind the ReadyCounter role (bd-s10oa)
`bd ready --limit 100` prints "showing 100 of 412", and the 412 came from
nowhere in particular. The direct route computed it inline: unwrap past the
storage decorators, type-assert to storage.ReadyWorkCounter, and fall back to
an unbounded ready query when the assertion missed — twice, once in the --json
branch and once in the text one, with two different fallbacks. The proxied
route could not compute it at all and published no `total` key, so the same
script read a number under one workspace topology and nothing under another.

THE ROLE. issueops.ReadyCounter, reached through store.ReadyCounter() and the
provider's own accessor. It answers a question neither neighbour can: Reader
answers with a PAGE and its verdict is has-more ("did the limit hide
anything"), where this is "how many" — strictly larger, and already published
output, so collapsing the two would change what a shipped surface says. Counter
answers a predicate over one table, and the ready predicate is blocker-aware:
it reads the dependency graph and the wisp tier, which no CountRequest can
describe. Counter's own doc already said the count of ready work would be its
own role for that reason.

It takes issueops.ReadyRequest VERBATIM, the precedent ClaimNextRequest set, so
a listing, a claim and a count ask ONE question of ONE set. Limit and Offset are
ErrValidation for the reason a claim refuses them: a cardinality has no page, so
a limit would answer "how many of the first N" and an offset would subtract the
rows it skipped from the size of a set that still holds them.

THE CONTRACT IS AN IDENTITY, not a resemblance:

	CountReady(r).Total == len(Reader.Ready(r with Limit=0).Items)

at every implementation. backend/conformance/ready_counter_contract.go holds
seven cases, each citing the leaf doc by line, run at all three backends with
ZERO parks. They are TWO independent bodies plus an engine check: dolt and
embeddeddolt share internal/workapi/storereadycounter (one indexed COUNT(*) per
plane minus their overlap), and the unit-of-work provider is genuinely separate
code that runs the unbounded ready query and takes its length — which is why
the wisp-tier case is written the way it is, since that is where a COUNT and
the page it sizes are assembled by different arithmetic.

A DEFECT THIS FOUND, and it is not the count's. `bd ready`'s directory-label
default (GH#541) never reached the ReadyClaimer role. claimNextRequest re-ran
the gatherer's own emptiness test against in.filter — and the gatherer had
already written the default INTO that filter, so the test saw a non-empty label
set and skipped. The branch could never fire. In a directory with
`directory.labels` configured, `bd ready --claim` therefore claimed from the
WHOLE ready front while `bd ready` beside it listed only the configured scope:
exactly the "hand an agent work the listing never offered it" that
ReadyClaimer's contract exists to forbid. The gatherer now RECORDS its decision
(readyInput.dirLabels) and both roles read it, so there is one answer instead of
two derivations of it. Caught by writing the count's own test for the same
line, and pinned by cmd/bd/ready_role_request_test.go.

WHAT ELSE CONVERGED. Both routes and both output modes now ask one question
through one accessor: the direct route's two inline epilogues become one call,
and the proxied route's `pagination.total` exists for the first time. The
"showing X of N" text a human reads and the total a script parses are the same
number by construction. cmd/bd no longer names storage.ReadyWorkCounter at all
— the capability is required by the store body's PARAMETER TYPE, so a backend
that cannot size the ready set fails to compile instead of falling back to a
mega-query at runtime.

THE HTTP OPERATION, spec first (per bd-jtp1h's A2 scope decision):
GET /v0/beads/ready:count, capability `ready.count`, answering
`ReadyCount {total}`. It publishes no `limit` and no `sort`: a cardinality has
no page and no order, and the handler sends the listing's own sort default so
the request stays the listing's request rather than one that resembles it. The
filter vocabulary is decoded by ONE function shared with GET /v0/beads/ready
(readyFilters), so the two operations cannot admit different parameters — which
is what the identity rests on over the wire.
`TestCountReadyAndListReadyAdmitTheSameFilters` compares the two predicates
built from one query string. No component here carries allOf and none is
x-go-type-pinned: the pinned seven are canonical Go structs whose JSON encoding
IS the contract, and there is no canonical struct for this number — the CLI
publishes it inside its own stdout envelope, which is not a wire type — so
pinning would weld the body to a CLI presentation type rather than prevent a
drift. The generated output was read to confirm it (a struct with `Total
int64`, not an alias), which is the v2.6.0 trap this document warns about.

httpapi.Config's ROLES database source grows a REQUIRED third member. That is
the sharp edge for the next role commit and is now written down in
engdocs/ADDING_AN_ISSUEOPS_ROLE.md as step 13: a Config carrying the old pair
would bind and then nil-dereference on the first request that reached the new
handler, so Listen refuses it with the same message a half-set pair gets.

USER-VISIBLE, for the wave's changelog pass: proxied `bd ready --json --limit N`
now publishes `pagination.total`; `bd ready --claim` now honours the
directory-label scope on both routes.

Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
(regenerate-and-diff plus the httpapi suite) green; TestReadyCounterContract
7/7 at dolt, embeddeddolt and uow; the httpapi package suite; the direct-route
`bd ready` suites under BEADS_TEST_EMBEDDED_DOLT=1 and the proxied ones under
BEADS_TEST_PROXIED_SERVER=1, including the pagination envelope that now asserts
the total; TestProxiedLookup*; and the ready protocol-corpus tests, which are
byte-identical.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 09:47:24 +00:00
CI Bot
b6b319b981 feat(issueops): put multi-id bd dep list behind the EdgeReader role (bd-nhsno)
`bd dep list a b c --direction=down` asks a different question from every
other dep read: it answers with RAW EDGE ROWS keyed by source, for many
anchors at once, and it has to say per anchor whether that anchor exists.
Both routes answered it off-role — the direct one out of
GetDependencyRecordsForIssues, the proxied one out of a unit of work — and
neither could tell "this issue has no dependencies" from "there is no such
issue".

THE ROLE. Relations is the near sibling and it cannot answer this. It is
SINGLE-ANCHOR, it answers with the ISSUES on the far end of an anchor's
edges, and an edge whose target this database has no row for — an
`external:` reference, an id in another repository — is silently not a
neighbor. A missing anchor is ErrNotFound there, which a batch cannot use
without discarding the anchors it did find. Different answer shape,
different miss policy, different arity: three, so a new role and a new
accessor rather than a second Relations method. Q12 confirmed the split
against merging it with BlockingAnnotator, which answers a derived
best-effort decoration rather than stored rows.

The direction is OUTGOING only and there is no parameter for it. The inbound
bulk read is a different read against a different key with its own
cross-table de-duplication, and no front door asks for it; a direction
nothing sets would be a promise nothing checks.

TWO DEFECTS THE ADOPTION FIXES, both of them the same shape — a silent
change of JSON document:

  - the KNOWN DEFECT. The direct route's batched read fell through to the
    hydrated neighbor listing on ANY error, so a transient failure turned
    `bd dep list a b --json` from an array of dependency records into an
    array of ISSUES, with no error and no warning.
  - the same fall-through fired whenever routing split the anchors across
    stores, so a cross-rig batch emitted that other document every time. The
    role is reached per store now and the answers merge back into argument
    order, so a routed batch and a local one have one shape.

Also fixed on both routes: `--type` used to test emptiness BEFORE filtering,
so an anchor whose every edge the filter rejected printed a header with no
rows under it. The role filters, so it prints "has no dependencies".

USER-VISIBLE, approved in the Q11 batch: PROXIED `bd dep list` NOW REPORTS
GHOST ANCHORS. It used to hand the raw arguments to the dependency use case,
which keys its answer by source and has no entry for an id that names
nothing, so a typo printed "<id> has no dependencies" and a script read a
clean graph. The role probes each anchor, so a typo now prints the warning
the direct route has always printed for an argument it could not resolve —
on stderr, in both modes, which is what leaves `--json` the flat array of
dependency records the command documents. The proxied route still resolves
nothing: ids go to the role exactly as the caller spelled them, because that
route has never done partial-id resolution.

One behaviour had no prior decision behind it and is recorded as Q15 rather
than chosen quietly: a repeated anchor now collapses onto its first mention,
where the old loop over a keyed map printed it twice.

CONFORMANCE. backend/conformance/edge_reader_contract.go holds fourteen
cases, each citing the leaf doc by line, run at all three implementations
with ZERO parks. They are TWO independent bodies plus an engine check, not
three: dolt and embeddeddolt both call storage/issueops.ExecuteEdgeRead
inside their own read transaction, and the unit-of-work provider is the
second body — it probes existence through two batched by-id use-case reads
where the stores run one batched EXISTS over both tables.

The store-backed body is an InTx function rather than an
internal/workapi/store<role> package, which is a documented deviation from
the twelve-step checklist and the reason is Relations': the anchor probe and
the edge read must share ONE transaction, or an anchor can be reported
missing by a probe that raced a create the edge read then saw. That cannot
be expressed above storage.DoltStorage. engdocs/ADDING_AN_ISSUEOPS_ROLE.md
now names that variant, including why it needs no depguard entry — the
shared function takes a transaction, so no front door can call it.

HTTP. GET /v0/beads/dependencies is new canonical surface, spec written
first and the types generated from it. `items` is an array of the already
x-go-type-pinned `Dependency`, so the CLI's `--json` and this body stay one
compatibility domain; the new `DependencyEdges` envelope carries no allOf,
so the oapi-codegen v2.6.0 pin-dropping trap does not apply, and the
generated `Dependency` is still an alias. A ghost anchor is on `missing`
rather than a 404, for the reason the role reports it per anchor. There is
no `limit` and no cursor: `bd dep list` has none either, so the QUESTION is
bounded instead — at most 100 `issue_id` values — which bounds the work
without truncating an answer a client could not then page.

httpapi.Config's roles source grows from two roles to three, and Listen
refuses a partially-set set for the reason it already refused a half-set
pair: the missing role is a nil dereference in a handler on a live server.

Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
clean; TestEdgeReaderContract green at dolt (14/14), embeddeddolt (14/14)
and uow (14/14); ./internal/httpapi green; TestCorpusGolden green, so the
committed `bd dep list --json` fixture is byte-identical; TestEmbeddedDep
and TestProxiedServerDep2 green with their gates set; TestProxiedLookup
green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 09:42:06 +00:00
CI Bot
bbb44b3996 feat(issueops): put bd dep cycles behind the CycleDetector role (bd-wfkbv)
`bd dep cycles` had two implementations of one sweep and the post-add cycle
warning had two more. The direct route walked store.DetectCycles; the proxied
route walked the same lossy slice off the use case; and dep.go and
dep_proxied_server.go each carried a copy of the arrow-path warning. The two
copies agreed, which is the only reason nobody noticed that the slice they
agreed about was map-ordered and silently shortened. All four now build one
issueops.DetectCyclesRequest and ask for the role.

THE ROLE. A cycle has no ANCHOR. Every Relations request names a source and
answers with that source's neighbours; this one is asked of the whole graph and
answers with paths, so a Relations request type would have carried an anchor
field a sweep must ignore. Its own role and its own accessor per the governing
rule.

TWO USER-VISIBLE CHANGES, both ruled on by the owner (Q4, Q5), both recorded in
CHANGELOG.md.

  Q4 CANONICAL OUTPUT. Every source of nondeterminism is removed, not just the
  order of the answer, because ordering the answer would not have been enough:
  a depth-first enumeration records one cycle per BACK EDGE, and which edges are
  back edges depends on the walk. The roots came off a Go map and the adjacency
  lists out of an unordered SQL read, so two runs against an unchanged database
  could disagree about which cycles EXIST, not merely about their order. The
  walk is now sorted at both, each path is rotated to its lowest id, and the
  paths are sorted against each other.

  Q5 HONEST PARTIAL. A member the database cannot describe used to be dropped
  from the path, so a 3-cycle rendered as a 2-cycle and looked complete, and a
  wholly undescribable cycle vanished from the report and from the
  `Found N dependency cycles` count. Every member is now carried with its id,
  its DESCRIPTION is omitted rather than the member, and the cycle is marked
  Partial. There is no separate total, because there is no cycle the slice
  omits -- the reading of "still counted" is recorded in AMBIGUITIES.md
  (A-cyc-1) along with what it would cost to add one.

  `bd dep cycles --json` therefore emits a new shape: an array of
  {members:[{id, issue?}], partial} where it emitted an array of arrays of
  issues. The protocol corpus has no dep-cycles capture, so nothing was pinned
  to the old bytes.

WHERE THE BODY LIVES, and why it is not a store<role> package. The work is a
graph read plus a hydration that must see one snapshot, and a transaction is
not reachable through storage.DoltStorage. So the sharing happens one level
down at issueops.DetectCycleReportInTx -- the function both stores' legacy
DetectCycles already call -- with a five-line accessor in each store package
and a new domain repository method for the unit of work. Two wrappers over one
function is still ONE vote. The parts that decide what the answer MEANS are
pure (CanonicalCyclePaths, BuildCycles) and pinned without a database.

CONFORMANCE. backend/conformance/cycle_detector_contract.go holds eight cases
citing the leaf doc by line, run at all three implementations with ZERO parks:
24 subtests green.

SEEDING ONE TAKES RAW SQL, which is a fact about the system rather than a
shortcut. No supported write can create a cycle -- the editor's per-edge probe,
its whole-graph gate and the storage seam all refuse -- so there is no verb that
produces the state this role reports. And foreign keys (dependencies.issue_id
-> issues, wisp_dependencies.issue_id -> wisps) mean an undescribable member is
reachable only with foreign_key_checks off. That is not academic: those are
exactly the paths a cycle arrives by. Recorded as AMBIGUITIES.md A-cyc-2 with
the alternative if the owner would rather the contract not write that way.

HTTP. GET /v0/beads/dependencies/cycles, spec first and the types generated
against it. Cycle and CycleMember are x-go-type-pinned to the ROLE package, so
the CLI's --json element and the HTTP item are one struct; the bijection test
grew a per-schema import path to cover them and immediately caught a missing
json tag on Partial. No allOf on either component (the v2.6.0 trap), verified
in the generated output: both emit `type X = issueops.X`. No limit and no
cursor -- truncating would shrink the count, which is the number an operator
acts on -- so has_more is documented as always false. httpapi.Config's roles
source now requires the third role beside Reader and Claimer, refused at Listen
for the reason a half-set pair is.

ONE DEFECT FIXED BESIDE THE TWO RULINGS: proxied `bd link` ran its cycle sweep
and its title lookups INSIDE the write transaction, so the warning described a
graph nobody else could see. It now runs them after the commit, through
depEdgeFeedback, which is where the dep routes already did it.

Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
green; TestCycleDetectorContract 8/8 at dolt, embeddeddolt and uow;
internal/httpapi 0 failures including the five new cycle-route cases;
TestProxiedLookup* green; TestEmbeddedDep* green;
BEADS_TEST_PROXIED_SERVER=1 TestProxiedServerDep* green; TestCorpusGolden
green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 09:36:14 +00:00
CI Bot
c1c283e5ce feat(issueops): put bd status behind the StatsReporter role (bd-4ze25)
`bd status` (and its `bd stats` alias) had two implementations of the same
command. The direct route asked the store for statistics and, under
--assigned, built an assignee filter, ran a ready-work query and folded
five status counts itself; status_proxied_server.go did all four again
through a unit of work. Both now build an issueops request and ask for the
role, and the difference between the two routes is which accessor answers.

THE ROLE. Its numbers are DEPENDENCY-AWARE — the blocked count reads the
denormalized transitive is_blocked flag and readiness is derived from it —
so no predicate over the issues table describes them and this is its own
role rather than a sixth Counter dimension, which is what issueops/
counter.go already said it would be. Stats and AssigneeStats are born
together because they answer the same question of two sets; they are two
METHODS rather than one with an Assignee field because the assignee answer
fills four fields of the same struct by different definitions, and a
request whose optional string silently changed what a number meant is the
shape this programme exists to remove.

WHAT THE LEAF DOC NOW SAYS OUT LOUD, none of it written down anywhere
before: BlockedIssues counts the graph, not the "blocked" status;
ReadyIssues is arithmetic and NOT the cardinality of `bd ready`;
PinnedIssues overlaps every status bucket so the buckets do not sum to
Total; the workspace-wide answer excludes the wisp tier while the
assignee-scoped one merges it; --no-blocked is a HINT whose only report is
BlockedIssues being nil; and EpicsEligibleForClosure and AverageLeadTime
are structurally always zero, which is why `bd status`'s "Extended:"
branch has never once printed.

CONFORMANCE. backend/conformance/stats_reporter_contract.go holds thirteen
cases, each citing the leaf doc by line, run at all three implementations
with ZERO parks and zero divergences. Unusually for this suite they are
THREE genuine votes: the two stores share the role body (storestats) but
dolt/queries.go, embeddeddolt/statistics.go and domain/db/issue.go each
spell the blocked count and the ready subtraction themselves. Every
workspace-wide case asserts a before/after DELTA — a summary takes no
predicate, so there is no IDFilter to scope it with the way the Counter
contract scopes its cases.

HTTP. GET /v0/beads/stats is added to the Tier-1 document FIRST and the
types generated from it: a `Statistics` schema x-go-type-pinned to
types.Statistics (checked: the pin survives, and the schema is now in the
JSON-tag bijection test), a StatsResponse envelope mirroring the CLI's
--json shape minus `recent_activity`, which no shipped path populates. The
handler calls the same role both CLI routes call. `blocked_count_skipped`
is DERIVED from the answer, never echoed from the request, because the
hint is a hint. httpapi.Config's roles source grows a third field and
requires it with the other two: a source that answers some operations and
faults on others is not a source.

ENFORCEMENT. cmd/bd/status.go and status_proxied_server.go no longer name
types.IssueFilter or types.WorkFilter, so `status` LEAVES the forbidigo
exception list (63 -> 61 of 388 files). The role-constructor depguard list
gains storestats.

TWO USER-VISIBLE CHANGES, both improvements and both small: `bd status
--assigned` reports the underlying failure instead of the bare "failed to
get assigned statistics", identically on both routes; and the proxied
--no-blocked warning now fires from the ANSWER rather than from the route,
so a backend that gains a fast path stops printing it with no edit.

Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
clean (no codegen drift, whole httpapi package green);
TestStatsReporterContract 13/13 at dolt, embeddeddolt and uow;
TestEmbeddedStatus and TestProxiedServerStatus green with their gates set;
TestProxiedLookup green; TestCorpusGolden green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 09:27:16 +00:00
CI Bot
270515915f feat(config): put bd config's stored settings behind the WorkspaceConfig role (bd-kzepq)
`bd config` had two implementations of the same four verbs. The direct route
called store.SetConfig/GetConfig/GetAllConfig/DeleteConfig in cmd/bd/config.go;
the proxied route opened its own unit of work and called the config use case in
config_proxied_server.go, then printed the same lines a hundred lines away. Both
now build an issueops request and ask for the role, and the difference between
the two routes is which accessor answers.

THE ROLE. issueops.WorkspaceConfig is the workspace's DURABLE SETTINGS PLANE:
the key-value rows the workspace database holds. It is born with four methods
because read, write, remove and enumerate over ONE keyed namespace are four
shapes of one question — the governing rule forbids appending to a role, not a
role being born whole — and because their promises are statements about each
other: SetSetting's promise is about what a later GetSetting returns, and
UnsetSetting's about what a later ListSettings omits.

The methods are GetSetting/ListSettings/SetSetting/UnsetSetting rather than
Get/List/Set/Unset, and that is not verbosity. Reader already has Get and List,
and the decorator conformance tests drive ONE sentinel that implements every
role at once; two roles with the same method name and different signatures make
that sentinel unwritable. The collision was the design telling us the short
names belong to issues.

ONLY THE KV SLICE IS A ROLE, and the rest is a deliberate no. `bd config show`,
`drift`, `apply` and `validate` are multi-source diagnostics over config.yaml,
environment variables, git config, this plane and server state at once. Three of
those five sources are files on the CLIENT's filesystem, which a server
answering for a remote workspace can never read, so a substrate role claiming to
answer them would be claiming to see something it cannot. `bd config set-many`
is off the role too, for a different reason: it exists to make N keys ONE Dolt
commit, the role writes and commits one setting per call, and
TestProxiedServerConfigSetMany pins the difference. A batched write is a
separate capability, exactly as `bd create --file` stays off Lifecycle.Create.

TWO LIVE DEFECTS FIXED.

  1. THE PROJECTION, which is the Q11 user-visible change. Reads of the custom
     status and type vocabularies are TABLE-first: they consult custom_statuses
     and custom_types and fall back to the config string only when the table is
     empty. The store backends have always rewritten the table in the same
     transaction as the row; the unit-of-work backend wrote only the string. So
     on a team server `bd config set types.custom "session"` reported success,
     `bd config get` read it back, `bd doctor` re-verified against the string and
     reported all-OK, and `bd create -t session` answered "invalid issue type"
     for as long as the workspace lived. Fixed where dab71c5eb fixed it — in the
     config repository, so the row and its projection commit together — and
     verified by reverting the fix and watching ProjectsCustomStatuses and
     ProjectsCustomTypes fail on uow alone.

  2. `bd config set-many issue_prefix=x` re-prefixed the workspace. The
     single-key verb refuses the prefix in both spellings and points at
     `bd init --prefix`, `bd bootstrap` and `bd rename-prefix`; set-many
     partitioned its pairs by source and wrote the database ones straight
     through, so it never saw that guard. Beads created before the write and
     after it disagreed about their own namespace with nothing to reconcile
     them. The refusal is now in the role for every caller that goes through it,
     and at set-many's front door because it does not.

THE BRIEF'S THIRD PREMISE IS FALSE, and it is worth saying so: "uow SetConfig
skips issue_prefix normalization" is not true at this base.
configSQLRepositoryImpl.SetConfig has trimmed the trailing hyphen since the file
was created (4fcbd5882, verified with git log -L). The normalization half needed
no fix; the custom-table half did, and dab71c5eb is NOT in this base.

WHAT ELSE CONVERGED. The status.custom parse lived in THREE places (both routes
of `bd config set` plus set-many) and is now one; the routing that stays at the
front door — which source owns a key, and whether writing it would leak a secret
into git — stays there, because those are questions about files on this machine.

CONFORMANCE. backend/conformance/workspaceconfig_contract.go holds fourteen
cases run at all three implementations with ZERO parks. Its shape is
deliberately not the issue contracts': there are no rows to seed, so it asserts
PRECEDENCE (which of two writes a later read sees, and whether a refusal leaves
the earlier value standing) and SIDE EFFECTS. Every projection case reads the
TABLE through QueryScalar rather than reading the setting back through the role,
because reading it back through the role is exactly the check that passed on the
backend where nothing took effect. Two independent bodies plus an engine check,
not three votes: dolt and embeddeddolt share
internal/workapi/storeworkspaceconfig.

TWO ASYMMETRIES ARE PINNED RATHER THAN FIXED, because all three backends agree
and closing either is a user-visible change this slice was not approved for.
UnsetSetting does not undo SetSetting's projection, so removing types.custom
leaves the custom types applying (bd-yby99.33); and `bd config unset
issue_prefix` is not refused where `bd config set` is (bd-yby99.34). Both are
stated in the leaf doc and asserted by a case, so neither can drift or be closed
on one backend while the owner decides.

HTTP. GET /v0/beads/config and GET /v0/beads/config/{key}, spec-first, taking
the v0 surface from six operations to eight. A setting whose KEY marks it as
credential-bearing — notion.token is database-backed — is published with
`redacted: true` and NO value: withheld values are omitted rather than masked,
which is the document's own "verbatim or absent" rule, and the CLI is unchanged
because its caller already holds the database while this surface has no
authentication. There is no HTTP WRITE, and that is the honest answer rather
than a hedge: `bd config set` routes most keys to config.yaml or git config
before the database is reached, so a server-side PUT of `export.auto` would
return 200 and land a row nothing reads. `Setting` is the one unpinned response
component, with the reason in the document beside it — the CLI marshals an
ad-hoc map, so there is no canonical struct to pin to, and minting one would
mean changing `bd config get --json` in order to satisfy a rule about not
changing it. All three are recorded in AMBIGUITIES.md as A-cfg-1..3.

ENFORCEMENT. storeworkspaceconfig joins the cmd-bd-role-constructors deny list.
`bd config` never named types.IssueFilter, so there is no forbidigo exception to
remove. engdocs/ADDING_AN_ISSUEOPS_ROLE.md gains what step 12 now costs since
the owner's scope decision: the spec operation, the route row, the Op constant
and operationCodes row, the capability token, and the Config field that a
store-shaped database source must now carry.

Verified: build, vet, gofmt clean; golangci-lint 0 issues;
TestWorkspaceConfigContract green at dolt (14/14), embeddeddolt (14/14) and uow
(14/14); the workapi validator unit tests, the two decorator enumerations, the
root layering pins and internal/jira green; internal/httpapi green and
`make api-check` clean; TestProxiedLookup green; `-run Config` green under
BEADS_TEST_EMBEDDED_DOLT and, under BEADS_TEST_PROXIED_SERVER, green except
TestConfigValidateReadOnlyIsHermetic, which fails identically on a pristine base
worktree under the same filter and passes standalone on both. TestCorpusGolden
green, so `bd config --json` is byte-identical to the committed corpus.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 09:14:54 +00:00
CI Bot
0380accb62 feat(issueops): put bd count behind the Counter role (bd-m8hn7)
`bd count` had two implementations of the same command. The direct route
built a types.IssueFilter in cmd/bd/count.go, loaded the workspace list
config and applied the --include-infra policy; the proxied route did all
four again in count_proxied_server.go and executed against the use case.
Both now build an issueops.CountRequest and ask for the role, and the
difference between the two routes is which accessor answers.

THE ROLE. Counts are NUMBERS; Reader answers PAGES OF ISSUES. Different
question, so its own role per the governing rule rather than a counted
variant on Reader: a count has no order, no page and no cursor, and a
request type carrying paging fields a count must ignore is the shape that
makes a caller believe --limit 10 bounded the answer. Count and
CountByGroup are two shapes of ONE question and cannot be separated in
practice - the grouped answer carries the scalar Total, because label
buckets overlap and the sum is wrong - so the role is born with both.

WHAT CONVERGED, beyond the duplication:

  - the wisp-tier policy. BuildCountFilter is now the single definition of
    what `bd count` means, beside BuildListFilter, and the GH#4387
    cardinality-parity test moved from cmd/bd to internal/workapi where it
    compares the two SHARED builders instead of a CLI helper against one
    of them.
  - the grouped Total. "use the scalar count, not the sum, because label
    buckets overlap" lived in cmd/bd; an HTTP surface adding grouped
    counts would have had to rediscover it.
  - the config load. It happens inside the role, and only under
    IncludeInfra, so a plain count still makes one query.

CONFORMANCE. backend/conformance/counter_contract.go holds twelve cases,
each citing the leaf doc by line, run at all three implementations with
ZERO parks. They are TWO independent votes plus an engine check, not
three: dolt and embeddeddolt both hand back internal/workapi/storecounter,
and the unit-of-work provider is the second body.

ENFORCEMENT. cmd/bd/count.go no longer names types.IssueFilter, so `count`
LEAVES the forbidigo exception list - the hole it needed is closed rather
than merely unused. The reader-constructor depguard rule becomes
cmd-bd-role-constructors and gains storecounter, so it is a list the next
role extends by one line instead of a rule per role.

NO HTTP HANDLER EXISTS for count. `bd serve` publishes /healthz,
/v0/beads/context, /v0/beads/ready, /v0/beads/issues, /v0/beads/issues/{id}
and POST /v0/beads/issues/{id}:claim, and the spec is Tier-1 ratified, so
none was invented.

THE PER-ROLE COST, which no design budgeted, is now written down in
engdocs/ADDING_AN_ISSUEOPS_ROLE.md: twelve steps derived from this commit,
naming the accessor line in internal/storage/storage.go, the hook and
telemetry wrappers, the two store accessors, the unit-of-work source, the
three conformance wirings, the five places each decorator enumeration
lists a role, and the two lint edits. Every later new-role commit follows
it.

Verified: build, vet, gofmt clean; golangci-lint 0 issues;
TestCounterContract green at dolt (12/12), embeddeddolt (12/12) and uow
(12/12); TestEmbeddedCount* and TestProxiedServerCount* green with their
gates set; TestCorpusGolden green, so `bd count --json` is byte-identical
to the committed protocol corpus.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 05:27:39 +00:00
Julian Knutsen
d801ec43dc
feat(issueops): put every issue capability behind one library surface
Beads had two implementations of most issue verbs: one for the direct route
(the CLI talking to a store it opened itself) and one for the proxied-server
route (the CLI talking through a unit of work over a running Dolt server).
They drifted — different commit messages, different transaction boundaries,
different refusals, occasionally different answers.

Seven role interfaces now live in the leaf package issueops: Lifecycle,
Reader, ReadyClaimer, BatchCloser, DependencyEditor, Commenter and Relations.
Each is reached only through a store accessor, never a constructor, because
the accessor is where the hook and telemetry decorators add their layers.
Three implementations back every role — dolt, embeddeddolt, and the
unit-of-work provider the proxied route uses. Both routes call the same role
for close, dep add/remove/list, comment, ready --claim and update.

A depguard rule (httpapi-domain-boundary) denies internal/storage/domain from
internal/httpapi, so a handler cannot reach uw.IssueUseCase() past the roles
and open a second front door one lint-clean commit at a time.

Behaviour users will notice, all in the CHANGELOG:
  - bd close a b c is one Dolt commit, not three, and --claim-next moved
    inside that transaction so it fires only when something landed
  - the open-children guard moved into the transaction and its hand-rolled
    cmd/bd copy is gone, removing a read-then-write window that made
    bd close <child> <parent> depend on argument order
  - bd dep add --file honours deferred version commit
  - embedded bd comment writes the role's message and author
  - dep verb commit messages are the role's on the direct route

Wisp-sourced dependency edges are restored. Moving bd dep add onto the role
had pinned an edge's SOURCE to the issues plane, and the two routes did not
even fail alike: direct refused with "issue <id> not found", proxied threw an
fk_dep_issue violation. The comment justifying the pin claimed the issues
plane was "the only one its unit-of-work sibling can reach" — that was false;
domain.DependencyUseCase declared a full set of wisp twins with no production
caller. All three implementations now route per edge by the edge's own
source. A mixed request stays one transaction: parent-child-first ordering
and the whole-graph cycle gate span both planes, and a refusal rolls back
both. Behind the role, three bulk add verbs collapsed into one source-routed
AddDependencies, so no plane-pinned variant is left to reach for by mistake.

Six Provenance fields with no production caller were deleted rather than
wired — CloseRequest, CloseBatchRequest, ClaimNextRequest, AddCommentRequest,
AddDependenciesRequest, RemoveDependencyRequest. Each role already composes an
id-bearing message, so a caller could only restate the default and make it
unreachable from production. Two are not caller-settable even in principle:
CloseBatchCommitMessage names what LANDED and ClaimNextCommitMessage names the
id the claim WON. UpdateRequest and ReopenRequest keep theirs; commit messages
users see are unchanged.

Verified: build, vet and gofmt clean; golangci-lint 0 issues; protocol corpus
byte-identical under BEADS_PROTOCOL_REQUIRE_DOLT=1; all twelve
DependencyEditor conformance wirings green (four contract functions against
each implementation); TestEmbeddedDepAddWispSource runs bd dep add <wisp-id>
at the front door and was demonstrated RED against the pinned routing first.
Three internal/storage/dolt failures reproduce on pristine origin/main.

Known gaps are enumerated in the PR description rather than left to be found:
comment listing is on no role, bd dep tree and bd dep cycles have no role,
bd create and bd reopen are on Lifecycle only on the direct route, per-edge
line attribution is lost in bd dep add --file, multi-store bd close
--claim-next rides only the first store's batch, and the is_blocked staging gap
(bd-2y9ke, predates this change). Seven of the eight role interfaces now have a
shared conformance contract in backend/conformance, run at all three
implementations; main's Claimer, added in parallel by #5334, is the eighth and
has none yet.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 12:27:56 -07:00
Julian Knutsen
0a3ff99f34
Add issueops.Claimer and route the HTTP claim through it (#5334)
The claim was the one v0 operation not covered by the public facade: the
handler reached past it into the domain layer, driving
uw.IssueUseCase().ClaimIssue directly and carrying its own conflict type,
its own refusal shaping and its own transaction protocol. That is a
handler doing the library's job.

Claim is now a role of its own beside issueops.Lifecycle and
issueops.Reader, reached by its own accessor rather than appended as a
fifth verb:

- issueops.Claimer, with ClaimRequest, ClaimResult and the typed
  ClaimConflictError, which WRAPS the refusal rather than replacing it —
  errors.Is, the refusal's exact prose and beads.ParseClaimConflict's
  fragments all survive.
- storage.Storage.IssueClaimer(), implemented by both Dolt stores over a
  shared storageissueops.ExecuteClaim, and recursed through by the hook
  and telemetry decorators.
- uow.IssueClaimerSource / uow.NewIssueClaimer, where the HTTP path's
  semantics live, retry included.

handleClaim now does argument validation, asks the provider for the role
and returns the result. The wire is unchanged: no diff under
internal/httpapi/spec or internal/httpapi/apigen, and the existing claim,
spec-parity and bijection suites pass unmodified apart from the storage
commit message, which loses its "bd serve:" prefix now that the operation
is not the server's.

ClaimResult.Issue is deliberately the bare post-state row — no labels,
dependencies or comments, unlike UpdateResult. That is what the shipped
v0 response and `bd update --claim --json` both report today, verified
against an issue that does carry labels; hydrating it here would change
an already-published body.

Breaking for out-of-tree implementations of beads.Storage, which must add
IssueClaimer() to compile. Noted in CHANGELOG.md.

Agent-Signature: claude-opus-5

Co-authored-by: CI Bot <ci@beads.test>
2026-08-04 08:40:18 -07:00
CI Bot
0dd0133eaa refactor(ready): derive the --explain filter from workapi (bd-3fs.3)
bd-ehi collapsed the two ready-default builders into
workapi.BuildReadyFilter. A third fixed copy survived: runReadyExplain and
runReadyProxiedExplain each inlined WorkFilter{Status: StatusOpen,
SortPolicy: SortPolicyPriority}, so a change to what "ready" means would
have moved the listing and left the diagnostic explaining a different set.

Both now call readyExplainFilter, which asks the shared builder. The limit
stays 0 rather than taking workapi.DefaultReadyLimit: --explain is a
whole-graph diagnostic, and inheriting the listing's 100 would explain part
of a larger graph while reading as though it had explained all of it.

The forbidigo exemption for cmd/bd/ready*.go stays - readyInput still
carries a types.WorkFilter field, and the blocked views still pass a bare
one - but its reason no longer claims --explain takes readyInput's filter,
because it does not and now visibly builds its own.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 05:52:49 +00:00
CI Bot
a784160437 Merge origin/main into bd-serve-v0
Two resolutions, one textual and one semantic.

CHANGELOG.md: both sides opened `### Changed` with a new entry. Union, main's
breaking close-policy entry first, this branch's `IssueReader()` entry after it.

cmd/bd/update_proxied_server.go: git merged #5206's two close-policy arms into
applyUpdateProxiedAttempt cleanly and the package stopped compiling. #5206 wrote
them against the old four-value attempt signature
(`nil, *updateIDFailure, bool, nil`); bd-m2u had already collapsed that function
onto uow.RunTxResultWithin, whose attempt returns
`(proxiedUpdateAttempt, string, error)`. Both arms now return through
failedUpdateAttempt, which is the same verdict expressed in the new shape: a
terminal per-issue failure with an empty commit message, so the retry loop
neither commits nor retries and the refusal is printed exactly once.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 01:39:19 +00:00
Julian Knutsen
ff6eeedbf6
feat(update): enforce close policy when a status update crosses into done (#5206)
A generic status update crossing from a non-done into a done-category status now enforces close
policy — the open-children refusal and the live-direct-blocker refusal — instead of bypassing it.
bd update --force gains a second meaning: it overrides close policy as well as the assignee-transfer fence.

Enforcement lives at the two storage-layer update funnels rather than at call sites, so every status-capable
path is covered by construction. The override travels as a reserved update-map key each funnel pops before
field validation, so a caller that fails to plumb it is refused loudly by name rather than silently losing
the override.

Breaking for scripts relying on bd update -s closed to bypass the checks bd close applies. bd batch gains
'force=true'; an unforced refusal rolls back the batch. Tracker sync-pull always forces. bd batch close is
unchanged.
2026-07-31 18:23:06 -07:00