Commit graph

75 commits

Author SHA1 Message Date
Stephanie Jarmak
12b19a6df7
feat(dep): detect cycles through tracks edges (#6148)
* feat(dep): teach bd dep cycles to traverse tracks edges (gc-818bx)

Adds DetectCyclesRequest.IncludeTracks and a CanonicalMixedCyclePaths
walk so a molecule-root deadlock closing through a tracks edge (root
--blocks--> its own entry step, step --tracks--> root) is detectable,
while a cycle made entirely of tracks edges stays silent by
construction (guards against the PR #4933 false-positive regression).

Wired end to end: public issueops.DetectCyclesRequest -> pure
CanonicalMixedCyclePaths/AppendMixedCycleGraphInTx ->
DetectCycleReportInTx -> dolt/embeddeddolt/uow-domain transactional
wrappers -> `bd dep cycles --include-tracks`. Default request behavior
is unchanged (byte-identical code path when IncludeTracks is false).

Tests: pure-function unit tests for the new DFS variant (rotation,
parallel-edge dedup, self-loops, map-order determinism); conformance
cases against both dolt and embeddeddolt real backends plus the uow
provider (RunCycleDetectorIncludeTracksIgnoresAPureTracksLoop,
RunCycleDetectorIncludeTracksFindsTheMoleculeRootShape, and an added
DepTracks case in RunCycleDetectorFollowsOnlyBlockingEdges pinning the
default's exclusion); CLI-level flag registration and threading tests.

Scope: fix candidate 3 only, per gascity-pl's 2026-08-10 scope-narrowing
comment on gc-818bx (candidates 1/2 addressed upstream by gastownhall/
gascity PR #5202).

* fix(dep): find mixed cycles by SCC instead of single-pass DFS (gc-818bx)

CanonicalMixedCyclePaths could report no cycle for a graph that has a
qualifying one. A single global visited/onPath set only detects a back
edge to a node still on the active recursion stack, so a tracks-only
loop that fully closes and unwinds first (a->b->a) leaves b marked
visited-but-off-path by the time a scheduling edge into the same
component (a->c->b) is examined, and the c->b return edge is invisible
to the DFS.

Every internal edge of a strongly connected component lies on some
cycle within it, so replace the DFS with Tarjan's algorithm: find each
SCC, and for any SCC containing a scheduling edge, walk a deterministic
BFS return path back to that edge's source. Nodes, adjacency, SCC
membership, the chosen edge, and the return path are all sorted so the
result stays a pure function of the graph, matching the existing
determinism guarantee.

Adds the counterexample from exact-head review: a--tracks-->b,
b--tracks-->a, a--blocks-->c, c--tracks-->b, which the prior
implementation reported as acyclic despite the qualifying a->c->b->a
cycle.

* fix(dep): fail loudly if SCC path invariant breaks (gc-zo8a7)

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of sjarmak

* fix(dep): keep every default cycle in the --include-tracks report

CanonicalMixedCyclePaths emitted one cycle per strongly connected
component, so a tracks edge joining two separate blocks-only deadlocks
collapsed them into one reported cycle and --include-tracks could report
fewer cycles than the default walk.

The widened report is now the union of the default depth-first walk on the
scheduling-only subgraph and, for each blocks/conditional-blocks edge
inside a component of the widened graph, that edge closed by its shortest
return path over either edge type. The first set is the default report by
construction; the second adds cycles that close through tracks edges. Every
reported cycle still contains a scheduling edge, so tracks-only loops stay
out. The report holds at most one cycle per internal scheduling edge plus
the default cycles.

A missing return path inside a component is an invariant breach; it now
returns an error through DetectCycles instead of panicking.

* test(dep): pin tracks edge direction in the cycle detector contract

A two-node cycle reads the same under edge reversal, so the existing
IncludeTracks cases could not tell a walk that follows issue_id ->
depends_on_id from one that follows the reverse. The new three-node case
seeds a -> c (tracks), c -> b (blocks), b -> a (tracks), whose reported
path is a, c, b and becomes a, b, c if the edges are reversed.

Also refresh the cycledetector.go line citations this branch shifted.

* perf(dep): share one return-path search per target in the --include-tracks report

CanonicalMixedCyclePaths ran one breadth-first search per scheduling edge
inside a component, O(E(V+E)). On a dense tangle E grows with the square of
V, so the report grew with the fourth power of the component size.

Group the component's scheduling edges by target and close every edge into a
target from one shortestPathTree rooted there, confined to the component.
closeMixedCycle now reads the return path out of that tree and still returns
an error, never loops, when the tree does not reach the edge's source.

TestShortestPathTreeClosesEachEdgeAsAPerEdgeSearchDid checks over generated
graphs that each edge closes to the cycle reachPath produced for it alone,
ties included. BenchmarkCanonicalMixedCyclePathsDenseTangle (80 issues, a
blocks edge for every ordered pair, one tracks edge back): 26.3 ms and
27.8 MB per call before, 5.4 ms and 2.8 MB after.

* fix(dep): scope the --include-tracks guarantee and bound its output

Review iteration 1 (maintainer fixup) for the one gating major. The
IncludeTracks doc claimed that requiring "at least one blocks/
conditional-blocks edge" on every reported cycle is what keeps out the
`bd doctor` regression that "produced thousands of cycles". That rule is
NECESSARY, NOT SUFFICIENT. One tracks-only loop fuses everything it
touches into a single strongly connected component, after which every
scheduling edge inside that component lies on a cycle and is reported --
even where those scheduling edges alone are strictly acyclic and the
default walk reports nothing. A 10-step molecule whose entry step tracks
back to its root yields 9 reports against the default walk's 0.

The doc's own BOUND paragraph conceded the volume ("never more than twice
the distinct scheduling edges") while the paragraph above it claimed the
guard prevented it. The algorithm is correct and is unchanged; what was
wrong is the contract written over it, plus the absence of any cap on a
diagnostic that can now be edge-count sized.

A census found the claim in 5 sites, not the 2 the review cited:
  issueops/cycledetector.go                       IncludeTracks field doc
  internal/storage/issueops/cycle_report.go       the BOUND paragraph
  internal/storage/issueops/cycles.go             AppendMixedCycleGraphInTx
  cmd/bd/dep.go                                   flag registration comment
  internal/storage/issueops/cycle_report_test.go  section header
backend/conformance/cycle_detector_contract.go:246 already scoped it
correctly ("a loop made entirely of tracks edges stays silent") and is
left alone. The PR body and the contributor's commit messages assert only
the true narrow rule, so neither needed correcting.

--limit caps the RENDERED list (default 50, 0 = no limit), matching the
idiom in list/search/stale/find_duplicates. It is a rendering cap and not
a narrower request because CycleReport.Cycles promises to omit no cycle:
the printed total stays the whole report's, the truncation says how much
it held back, and --json is never capped.

TestCanonicalMixedCyclePathsBoundsAFusedMoleculeByItsSchedulingEdges pins
the manufacture direction ...KeepsDeadlocksATracksEdgeFuses left open --
that one fuses two real deadlocks and checks neither is lost; this one
fuses none at all and still gets 9 reports.

Also taken, both non-gating: dropped the dormant
`json:"include_tracks,omitempty"` tag, since no serializer of
DetectCyclesRequest exists in the tree and handleDependencyCycles calls
requireNoQuery, so the tag advertised a wire contract the server refuses;
and added a comment naming the backend conformance cases as the only pin
on the row->edge admission switch.

Declined this iteration: factoring appendDependencyGraphInTx and
AppendMixedCycleGraphInTx onto one shared row loop (nit, gate impact
none). It restructures the SQL read path that, per the finding directly
above it, is pinned only at the conformance layer, and
appendDependencyGraphInTx also backs AppendSchedulingGraphInTx -- the
write-time gate behind every `bd dep add`. That is a wider blast radius
than a zero-gate-impact nit earns inside a fixup whose subject is a doc
overclaim; it belongs in its own change.

Validation: go build ./... clean; go vet clean on the 4 touched packages;
golangci-lint v2.10.1 reports 0 issues on issueops/...,
internal/storage/issueops/... and cmd/bd/...; internal/storage/issueops
full package 749 PASS / 0 FAIL / 0 SKIP (748 before, +1 new); cmd/bd
dep-cycles selector 9 PASS / 0 FAIL / 0 SKIP; internal/httpapi
Cycle|SpecParity 6 PASS / 0 FAIL. Mutation: making tracks edges unable to
fuse a component reds the new pin plus 5 incumbents (the feature dies);
reporting only one cycle per component reds the new pin ALONE (1 of 14),
so it covers a degradation no existing test catches.

Review iteration 2: the remedy above re-entered its own finding class. Both
iteration-2 items indict text THIS fixup wrote, not the contributor's.

The --limit cap is UNCONDITIONAL -- `if limit > 0 && len(shown) > limit` never
consults includeTracks -- yet every rationale iteration 1 wrote for it was
scoped to the widened walk, and the IncludeTracks field doc still closed with
"the base walk this type's doc above describes is unchanged". True of the walk;
false of its rendering, since plain `bd dep cycles` printed every cycle at base
and now prints at most 50. That is the same defect class as the major this
commit exists to fix: a doc claiming a scope the mechanism does not honor.

Of the two arms the review offered, only documenting the true scope is
available. Gating the cap on includeTracks reds this PR's own incumbent test:
printCycleReportForTest calls runDepCycles(false, limit), so
TestDepCyclesTruncatesTheRenderedListButNotTheCount/capped asserts the DEFAULT
walk truncates. Measured, not assumed -- that arm fails capped and
registered_default while no_limit passes. The implementation, the flag's help
string and the tests already agreed the cap is unconditional; only the prose
disagreed, so the prose moved:
  cmd/bd/dep_cycles.go      runDepCycles doc: the cap is unconditional, bounds
                            both walks, and names the behavior change vs base
  cmd/bd/dep.go             flag comment: caps both walks; the widened walk is
                            what makes the cap necessary, not what scopes it
  issueops/cycledetector.go the "Default false" closer: the walk is unchanged,
                            its RENDERING is not
Also the nit: the opening paragraph argued no flag can narrow either question
while --limit had no carve-out, where IncludeTracks had one. It now says no flag
narrows the ANSWER, and that --limit caps only what is PRINTED.

New renderer arm "registered default" closes the gap the minor named: every
existing arm drove an explicit limit, so the shipped 50 was pinned only by
TestDepCyclesLimitFlagRegistration's DefValue != "0". It reads the default off
the command and renders past it, so it tracks whatever ships; ids are
fixed-width so "past the cap" cannot match as a prefix of one inside it.

Mutation (3 arms, control restored byte-identical by cp -- the fixset was
uncommitted): gate the cap on includeTracks => capped + registered_default RED;
default 50 -> 0 => LimitFlagRegistration + registered_default RED (the new arm
independently catches an unbounded default); shown[:limit+1] => capped +
registered_default RED, so the arm pins the boundary and not merely "some
truncation". no_limit stays green under all three by design.

Validation: gofmt clean, git diff --check clean, go build ./... rc=0, go vet
clean on cmd/bd and issueops, cmd/bd dep-cycles selector 9 PASS / 0 FAIL / 0
SKIP (same top-level roster, +1 subtest). No production behavior changed this
iteration -- doc text plus one test arm.

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

---------

Co-authored-by: sjarmak <t@t.co>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-30 20:20:17 -07:00
Harry Miller
dfdedf5dfb
fix(status): disclose the counted rows bd list will not show (#5763)
* feat(stats): count the rows the default listing suppresses

bd status counts the issues table; bd list hides gates and templates on
account of what they are. The two therefore disagree, and nothing
reconciles them: a teardown driven by bd list leaves a gate behind and
status reports a total the operator cannot account for from any listing.

Break the suppressed rows out as their own counts. TotalIssues keeps
counting the database, which is what a command titled "Issue Database
Status" should report; these say how much of that total no default
listing will show. Every backend's statistics path funnels through
ScanIssueCountsInTx, so one query serves all of them.

Infra types need no counterpart here: they live on the wisp plane, which
this query does not read.

* fix(status): disclose the counted rows bd list will not show

bd status reported "Total Issues: 2" for a workspace whose every listing
showed one, because gates and templates are suppressed from a default
bd list. Nothing connected the two numbers, so the remainder read as a
phantom -- most visibly after a teardown driven by bd list, which leaves
its gates behind and then cannot see them.

Report the suppressed rows under the summary they qualify, naming the
flag that reveals each kind. The breakdown is printed rather than a
single hidden-total, since a template gate would otherwise be counted
twice. Nothing is printed when there is nothing suppressed.

Stacked on the statistics counts that make this reportable.

* docs(api): put gate_issues and template_issues on the Statistics schema

The Statistics schema is pinned to types.Statistics, so the two new
counts were on the wire the moment the struct grew them, and
TestWireTagBijection fails the openapi gate until the spec says so:

    Go fields with no spec property: [gate_issues template_issues]

Document both as a breakdown of total_issues rather than an addition to
it — they count rows the default `bd list` suppresses, which
total_issues already includes — and warn against summing them, since a
row can be both a gate and a template.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(status): give --assigned the same disclosure, and test the behavior

Three points from review.

1. `bd status --assigned` never printed the line. AssigneeStats does not
   go through ScanIssueCountsInTx - it folds one actor's rows through
   workapi.FoldStatsAssigneeSummary, which left both new fields zero. That
   route's filter sets only Assignee, so IsTemplate stays nil and the
   actor's gates and protos really ARE in those rows while
   `bd list --assignee` suppresses both: the same reconciliation gap, one
   scope down. The fold now counts them, and its doc says they are set
   deliberately rather than borrowed from a workspace-wide answer.

2. The infra-type suppression is now explained rather than asserted away,
   and the answer is that a durable infra row is NOT unreachable, so the
   third breakdown is filed as GH#6439 rather than dismissed. Both the
   plane routing and the listing's exclusions read the workspace-configured
   types.infra set, and writing that key only invalidates a cache
   (dolt/config.go) - it never moves rows already written. So durable rows
   created while a type was not infra stay durable once it becomes one, and
   a type evicted from the set creates durable rows outright, which the
   create contract already pins ("evicted infra type",
   issue_operations_contract.go). Counting them needs that configured set,
   which ScanIssueCountsInTx - portable SQL with no config seam, called
   from six backend sites - cannot reach; guessing with the built-in names
   would be wrong in exactly the workspaces where it matters.
   suppressedTypeSummary's doc now carries that reasoning.

3. The behavior itself had no test - both existing cases exercised a pure
   string formatter, and would pass with the render call site deleted. Now:

   - TestRenderStatusEmitsTheSuppressedRowsLine captures renderStatus's
     stdout, asserts the line and both parts, and asserts it sits after the
     totals it reconciles rather than in the extended block. It fails with
     the call site removed ("renderStatus did not emit the disclosure
     line"), plus a companion asserting the line is absent when there is
     nothing to disclose.
   - Three conformance cases in stats_reporter_contract.go, wired into all
     three role wirings (dolt, embeddeddolt, uow), so the new SQL is
     checked cross-backend rather than at one call site:
     BreaksOutTheRowsTheDefaultListingSuppresses (with the negative rows a
     loose predicate would also move), BreaksOutAGateThatIsAlsoATemplate
     (the two suppressions are independent, so a proto's gate step counts
     in both), and AssigneeStatsBreaksOutTheSuppressedRows for the fold.
     statsReporterCounts and assertStatsReporterDelta carry the two fields.
     All three are behavioral reds against zeroed counts, not compile
     errors:

         GateIssues moved by 0 (0 -> 0), want 1
         TemplateIssues moved by 0 (0 -> 0), want 1
         GateIssues = 0, want 1 - the actor's gate is in this answer but
           not in `bd list --assignee`

4. Nit: pluralCount takes both spellings instead of appending "s", so a
   caller with an irregular plural is not silently mis-served.

Also adds the CHANGELOG entry the behavior change was missing, including
the GH#6439 gap.

Reported-by: bee-ghosttrack
Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(conformance): declare the new stats cases in the order the table runs them

TestRoleContractCasesCoverEveryContractCase checks more than coverage: the
roleContractCases table has to list cases in the order their contract file
DECLARES them, because that is the order the unit-of-work leg's runners use
and the order its config-writing cases depend on.

I declared all three new cases together, then registered the assignee one
with the other assignee cases in the table, so the two orders disagreed:

    roleContractCases is out of declaration order at position 449: table
    has RunStatsReporterAStatusOutsideTheTalliesIsCountedOnlyInTotal,
    source has RunStatsReporterAssigneeStatsBreaksOutTheSuppressedRows

Fixed by moving the declaration rather than the table entry, since the
assignee case belongs beside the other assignee-scoped ones anyway - the
grouping the table already had was the correct one. Caught by CI because I
ran go vet over backend/conformance but not its tests; both now pass.

Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs(changelog): move this PR's entry under [Unreleased]

The 1.3.0 cut renamed the old [Unreleased] block, so the entry this branch
added there now merges cleanly into the released [1.3.0] section (#6643).

Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(status): complete the disclosure's remedy and pin its population

Maintainer review fixes for PR #5763 (adopt-pr iteration 1). Four of the
five review findings taken; the nit is declined with its measurement.

Finding 2 (minor, gate impact minor) - the printed remedy was incomplete.
The two counters come from the same scan as TotalIssues and are status-blind
with it, but the flags they named lift only the TYPE exclusion, so a CLOSED
gate was counted while `bd list --include-gates` still would not show it.
Gates are closed as the work they guard completes, so that is the ordinary
case rather than an edge.

Took the "complete the hint" arm over the "scope the counters" arm. Every
other field ScanIssueCountsInTx fills is workspace-wide; the disclosure
exists to account for TotalIssues, a database number printed three lines
above it; and scoping these two to the listing's population would leave them
explaining nothing about the total they are broken out of. `--all` "replaces
the status exclusions only" and lifts no type exclusion of its own
(backend/conformance/reader_contract.go:487), so the two flags together are
exactly the remedy. Recorded the population in the types.go field comment,
the status.go doc, and the CHANGELOG, which printed the old example verbatim.

Finding 3 (minor) - the three new conformance cases seeded only open rows,
so a backend counting over every status and one counting only the listing's
population returned identical numbers on all of them. Added a closed gate and
a closed proto to the first case. Proved it now decides the question: scoping
both SQL SUMs with `AND status <> 'closed'` reds exactly that case
("GateIssues moved by 1 (0 -> 1), want 2") while the all-open sibling
BreaksOutAGateThatIsAlsoATemplate stays green.

Finding 4 (minor) - the normative role doc in issueops/statsreporter.go
enumerated only the six prior counts. Added the two to that scan's bullet and
corrected two statements this PR had falsified: the headline "six counts of
one set", and the AssigneeStats bullet's "the fold ... tallies the five
statuses and nothing else", which stopped being true when the fold gained the
two increments.

Finding 1 (minor, gate impact minor) - ran `make bazel-sync`. It proposed
exactly one line, `+ "status_suppressed_test.go"` in cmd/bd/BUILD.bazel, and
nothing else, confirmed by porcelain rather than by bazel-sync-check.
Generator-owned, not hand-edited.

Finding 5 (nit) - declined. The three helpers already in package main
(pluralIssue, pluralize, plural) all DERIVE the "s" and cannot render a
caller-chosen pair; the tree's one two-form helper, pluralWord, is unexported
in internal/storage/issueops, and exporting it so a CLI string could reach it
would add exported surface to a storage role for a cosmetic. Recorded that
trade in pluralCount's doc comment instead.

Validation: `go build ./...` and `go vet` (6 pkgs) clean, gofmt clean,
`git diff --check` clean; cmd/bd 4/4 named PASS, internal/httpapi
TestWireTagBijection|TestSpec* PASS, internal/workapi PASS,
internal/storage/uow TestStatsReporterContract 18/18 subtests PASS. Both new
pins are mutation-proved: reverting `--all` reds all four table cases, both
flag subtests and the render-path pin, while the absence assertion stays
green.

Not done here: the PR body carries the same stale example line
("1 gate (--include-gates)"). Review iterations do not touch the PR surface,
so that correction is stamped for finalize.

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

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
2026-09-30 15:44:40 -07:00
Karel Bourgois
e8f318316f
feat(count): --include-ephemeral, the plane knob bd count never had (#6240)
* feat(count): --include-ephemeral, the plane knob `bd count` never had

`bd count` can admit the wisps table only through `--include-infra`, which
makes four changes at once. This adds the flag that makes just the first one,
mirroring the `--include-ephemeral` that `bd list` gained in #6098.

## Why the plane is unreachable on its own

The write path routes on STORAGE CLASS, not type — dolt's `useWispsTable` is
`Ephemeral || NoHistory || WispType != "" || IsInfraType`. So a `no_history`
task lives in the wisps TABLE while remaining ordinary durable work, and a
default `bd count` never sees it.

Recovering it today means `--include-infra`, which this repo's own doc calls
"FOUR changes at once and not one": it admits the plane, drops the infra-type
exclusions, changes the template treatment, and reconciles cardinality with
`bd list --all`. Its template exclusion then silently drops template rows of
the named type — so a caller who wanted the plane trades one silent undercount
for another.

`ListRequest.IncludeEphemeral` has been the narrow answer on the listing side
since #5476, and #6098 gave it a CLI flag. `CountRequest` had no equivalent
field at all. This is the missing half of that pair.

## The change

- `issueops.CountRequest.IncludeEphemeral` — the plane knob alone: exactly the
  first of `IncludeInfra`'s four changes, with none of the other three.
- `internal/workapi/count.go` — one line, `} else if !in.IncludeEphemeral {`.
- `cmd/bd/count.go` — flag registration, matching `bd list`'s wording.
- `internal/httpapi` — `include_ephemeral` on `countIssues`, in the spec; the
  generated `types.gen.go` is `make api-gen` output, not hand-edited.

Unset, the count is durable-plane only: the historical answer, unchanged. Every
default is untouched.

It does NOT promise a count and a listing agree. They already differ on
TEMPLATES without this flag and still do with it — a count includes template
rows unless `IncludeInfra` excludes them, a listing excludes them unless
`IncludeTemplates` admits them. That predates this and is unchanged by it; only
`IncludeInfra` sets out to reconcile cardinality, and it pays with three
changes beyond the plane.

## Verification

    ok  github.com/steveyegge/beads/internal/workapi
    ok  github.com/steveyegge/beads/internal/httpapi
    ok  github.com/steveyegge/beads/issueops
    --- PASS: TestEmbeddedCountIncludeEphemeral (39.71s)
    --- PASS: TestCountIncludeInfraFlagShape
    --- PASS: TestParseCountRequestCarriesEveryFilterFlag

`TestEmbeddedCountIncludeEphemeral` was run with `BEADS_TEST_EMBEDDED_DOLT=1`
and really executed — 39.71s, not a skip. The default fast tier would have
skipped it and reported `ok`.

`make api-gen` reproduces `types.gen.go` byte-for-byte from the spec hunk, so
the two cannot drift apart in review. `go build ./...`, `go vet` and `gofmt`
clean.

Claude-Session: https://claude.ai/code/session_01X1jMLQTSrCwtzFRS1xeUC6

* count: reframe the comments for this repo, not the fork they came from

Review on #6240 (bee-ghosttrack): five comment blocks were written from the
fork's point of view and become false once merged here — "belongs upstream",
"the half that still has to go upstream", "the fork's old wide default",
and "upstream's default" meaning the current default.

Find-and-replace, as asked: the reasoning is kept, only the frame of reference
changes. "upstream's default" -> "the default before this change"; the bd
list sibling "landed in #6098"; the infra-type divergence is "pinned, not
fixed, here" with the reason; the embedded test's fork-maintenance history is
replaced by what it actually pins. No code changes.

* build(bazel): list the two test files this PR adds in their go_test srcs

Maintainer review fixes for #6240, review iteration 1. The synthesis and the
quality scorecard both returned approve with no required changes; this commit
takes the one minor whose subject is the PR's own added files.

Taken:

- Change Impact / Blast Radius (minor, gate impact minor). The PR adds
  cmd/bd/count_include_ephemeral_embedded_test.go and
  internal/workapi/count_skipwisps_test.go, but neither was listed in its
  package's explicit go_test srcs, so the PR's own assertions were invisible to
  `bazel test`. Both rows are now listed.

  Gazelle's verdict, not a hand-guess: `make bazel-sync` was run (bazel 9.2.0 is
  available here) and it produced exactly these two entries. Its full output
  also rewrote 12 other BUILD.bazel files -- pre-existing base drift from other
  PRs' files, plus dep/select churn -- which is out of scope for this PR, so the
  generated result was reverted and only the two rows this PR is responsible for
  were re-applied, at the slots gazelle chose. Both srcs lists remain sorted
  with no duplicates (cmd/bd bd_test 637 entries, internal/workapi workapi_test
  24 entries).

  The cgo build tag on count_include_ephemeral_embedded_test.go does not exempt
  it: the repo lists tag-gated *_embedded_test.go files anyway (99 of the 101 in
  cmd/bd are listed, and the sampled ones are simultaneously listed and tagged).

Declined:

- Test Evidence Quality (nit, gate impact none). The filing lane itself marked
  it optional and explicitly said not to gate on it, and its own reasoning holds:
  internal/storage/dolt/counts.go and internal/storage/embeddeddolt/counts.go
  both delegate to the same issueops.CountIssuesInTx, differing only in
  transaction acquisition.

Validation: go build ./... and CGO_ENABLED=1 go vet on cmd/bd, internal/workapi
and issueops all clean; go test ./internal/workapi/ ./issueops/ ok. No
production code changed -- the commit is two generated-list rows.

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

---------

Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-29 16:56:23 -07:00
postoso
9017d33745
feat(count): accept --has-metadata-key (#6282)
bd list, bd ready and bd search all take --has-metadata-key. bd count did
not, so counting the rows that merely carry a key meant listing them and
measuring the page. This is the last metadata-filter parity gap between
count and the listings.

The storage layer already carries the filter: types.IssueFilter has
HasMetadataKey and sqlbuild.AppendMetadataClauses consumes it. What was
missing is the role field, the builder wiring, the CLI flag and the HTTP
contract, so this is one change rather than a stack.

Parsing matches list_input.go and ready_input.go, including the key
validation. BuildCountFilter now passes the key to ValidateMetadataFilters
instead of the empty string it passed before, which makes the role's
existing refusal reachable from the count surface; failReadErr already
classifies that error as a 400 on has_metadata_key.

apigen types are regenerated from the spec via go:generate, not hand
edited. The pinned CLI docs are untouched.

Fixes #6160

Co-authored-by: postoso <postoso@users.noreply.github.com>
Co-authored-by: Gas City Adopt-PR <noreply@example.com>
2026-09-29 13:16:37 -07:00
Julian Knutsen
2ec0b2f072
feat(purge): live-dependent protection, --wisps-plane selector, hour-precision --older-than, --limit (#6883)
* feat(purge): live-dependent protection, --wisps-plane selector, hour-precision --older-than

An orchestrator's wisp retention step deletes every closed row in the
wisps table older than N hours, except a closed wisp that an
open/hooked/in_progress wisp depends on through parent-child, tracks or
blocks. `bd purge` could not express that: it selected the ephemeral
TIER (so closed --no-history beads, which live in the wisps table, were
left behind), it deleted a closed molecule root whose step was still
open, and it floored --older-than hours to whole days (36h swept rows
24h old). All three land together so `bd purge --wisps-plane
--older-than 168h --force` covers that step.

Live-dependent protection (issueops.SweepRequest.ProtectLiveDependents,
SweepSkips.LiveDependent): a candidate is held back when a live row
depends on it through a SweepLiveDependentEdgeTypes edge (parent-child,
tracks, blocks), read from both dependency tables. "Live" is the same
not-done set the reference scan uses, custom statuses included, so it
is a superset of open/hooked/in_progress. `bd purge` always asks for it
(no opt-out: removing live work's root is `bd delete`'s job); `bd prune`
does not. Reported as live_dependent_skipped in --json.

Wisps-plane selector (issueops.SweepWispsPlane, `--wisps-plane`): the
candidates are every closed row in the wisps TABLE, whatever its
ephemeral/no_history/wisp_type values, via a new single-plane search
(issueops.SearchWispsPlaneInTx) that the store backends call directly
and the unit-of-work provider reaches through
IssueUseCase.SearchWispsPlane, so embedded, server and proxied share one
body. It reaches durable-tier (no-history) rows, so it carries the
durable tier's require-a-filter gate.

--older-than (purge and prune): day values keep their meaning (7, 7d,
2w); anything else is a Go duration taken exactly (36h, 168h, 90m).

Tests: three new Sweeper contract cases (wisps plane clears the whole
table, wisps plane requires a filter, protects live dependents) run on
dolt, embeddeddolt and the uow provider; workapi unit tests; a CLI
retention scenario run in embedded, shared proxied and managed-local
proxied modes (fails against origin/main); TestParseOlderThan.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(uow): classify IssueUseCase.SearchWispsPlane as a read in the notifying parity partition

TestRecordingIssueUseCaseCoversItsSurface requires every IssueUseCase
method to be either wrapped by the notifying decorator or exempted with
the reason it fires no hook. SearchWispsPlane reads state and changes
none, like SearchIssues beside it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(purge): refuse out-of-range --older-than; add --limit for bounded drains; cross-plane protection test

Review follow-ups on #6883.

--older-than: a day count past what a time.Duration holds (213504d,
30501w) used to wrap silently — 213504d became 25m26s, which on a
destructive command selected almost every closed row. It is now refused
as out of range; ParseDuration already refused oversized h/m/s values.

--limit N (issueops.SweepRequest.Limit, SweepResult.Remaining): one
purge deletes at most N rows, oldest closed_at first (then id), after
every protection, and reports the rest. --json adds remaining and
has_more when --limit is given. At ~15ms/row on the proxied path a
single unbounded sweep of a large backlog can outlive a caller's
deadline, roll back, and never clear; a bounded loop cannot. Negative
limits are ErrValidation at the role and refused at the CLI.

Tests: TestParseOlderThan out-of-range rows; contract cases
LimitTakesTheOldestClosedFirst and ProtectsLiveDependentsAcrossPlanes
(a live issues-table bead depending on a closed wisp via parent-child,
tracks and blocks keeps it) on dolt, embeddeddolt and uow; workapi
units for the ordering and the negative-limit refusal; the CLI
retention scenario now drains with --limit 1 and checks the overflow
refusal. CHANGELOG notes that sub-day Nh values used to round UP to a
day (12h is now taken exactly) and lists the protection under Changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 00:57:24 -07:00
Julian Knutsen
f66375459f
test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828)
* test(bazel): add internal/testutil/bazeltest runfiles helpers

Repository-path resolution for tests that works identically under plain
go test (package cwd, full checkout), bazel test locally, and remote
execution (declared runfiles only):

- IsBazel, RepoRoot (BEADS_TEST_REPO_ROOT, then the runfiles workspace
  root, then a go.mod walk), OverrideRoot (drop-in condition for existing
  helpers; empty under plain go test), CallerDir
- Runfile for $(rlocationpath) values, GOROOT for type-checking tests
- ShardFreeEnv for helpers that re-exec a test binary

Every helper reduces to the pre-Bazel behavior under go test.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(bazel): declare source/data reads for 14 scan-guard targets

Source-scanning and repo-file tests read files their Bazel targets never
declared, so they failed under `bazel test` (and could not run on remote
workers at all). Declare narrow inputs as `data` and resolve paths through
bazeltest where the test located the tree via runtime.Caller:

- tools/bazel/go_srcs.py (run by `make bazel-sync` after gazelle) keeps a
  managed `go_srcs` filegroup in the packages whose Go source tests scan,
  plus `//internal/storage:tree_go_srcs` for the storage-tree walk. Bazel
  globs stop at package boundaries, so the aggregate needs one filegroup
  per package; the script keeps it in sync and gazelle-stable.
- Hand-written narrow inputs: //internal/storage/schema:migrations,
  //:docsync_files, //plugins/beads:plugin_files, and exports of
  .gitattributes, .claude-plugin/marketplace.json, cmd/bd list.go and
  ready.go, testutil/testdoltcommon.go, scripts README.md and the release
  catalog, each visible only to its consumer.
- runtime.Caller-based roots in backend, backend/conformance,
  internal/storage, internal/formula and test/docsync now go through
  bazeltest.CallerDir / OverrideRoot; relative-path tests need data only.
- integrations/ leaves .bazelignore (it is still gazelle-excluded) so the
  docsync link check can declare integrations/beads-mcp/PYPI.md.

Under --config=prcore every target reports the same PASS/SKIP/FAIL test
set as `go test -race -short` for its package, locally and remotely.
Plain `go test` behavior is unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(bazel): guard generated go_srcs and harden bazeltest root override

- tools/bazel/go_srcs.py: add --check (print diff, exit 1 on stale blocks);
  new `make bazel-sync-check` target runs it.
- scripts/bazel_policy_test.go: under go test, assert every tree_go_srcs
  (//internal/storage) lists exactly the BUILD.bazel packages below its
  root, run go_srcs.py --check, and forbid BUILD files under docs/ and
  engdocs/ (they would cut subtrees out of //:docsync_files).
- bazeltest: honor BEADS_TEST_REPO_ROOT only when it holds go.mod
  (RepoRoot fails loudly otherwise); drop the unused GOROOT() helper,
  whose compiled-in branch could never fire under rules_go.
- scripts/ci/lib/test-env.sh: unset BEADS_TEST_REPO_ROOT.
- Document the hand-listed out-of-tree link targets in //:docsync_files.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* build(bazel): re-sync BUILD files with main

Regenerated with make bazel-sync after commits that landed while the
scaffold PR was in CI (new internal/execenv, gitenv, gitignore packages
and new sources/deps).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(bazel): declare init_safety_help.go for docsync

TestInitSafetyCLIHelpCoversReCloneGotchas (#6431) reads
cmd/bd/init_safety_help.go; export it to //test/docsync only.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-27 08:24:08 -07:00
Julian Knutsen
57ef364501
build(bazel): side-by-side Bazel scaffold + policy tests (#6798)
* build(bazel): add side-by-side Bazel scaffold (module + gazelle)

Add a Bzlmod Bazel build alongside the Go toolchain. `go build` and
`go test` are unchanged; nothing in CI invokes Bazel yet.

- MODULE.bazel: rules_go 0.63.0, gazelle 0.53.0, Go SDK 1.26.7 (matches
  the go.mod toolchain directive), go_deps from go.mod.
- ICU policy (engdocs/ICU-POLICY.md): a go-mysql-server gazelle_override
  selects the pure-Go regex backend and excludes regex_cgo.go, and
  .bazelrc builds with --@rules_go//go/config:tags=gms_pure_go, so no
  target depends on go-icu-regex or links libicu.
- third_party/patches: three module_override patches for dolt deps that
  ship WORKSPACE-era BUILD files, adapted from the gascity project.
- .bazelrc: prcore/ci test configs (inert for now; they match pr-core's
  test selection, not yet its environment isolation) and a generic
  remote-exec config with a bounded remote timeout. Executor endpoints and
  TLS credentials come only from a gitignored .bazelrc.local/user.bazelrc
  or a CI rc outside the workspace.
- .bazelversion pins Bazel 9.2.0; .bazelignore skips separate modules,
  non-Go trees, nested agent worktrees (.claude, .worktrees) and local
  data/output dirs (.beads, .dolt, dist, .runtime, tmp), so a primary
  checkout neither builds nor gazelle-rewrites nested worktree copies.
- Gazelle-generated BUILD.bazel files for every Go package.
- Makefile: `make bazel-sync` (gazelle + bazel mod tidy).
- .gitignore: bazel-* output symlinks and machine-local rc files.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(bazel): policy tests for the Bazel configuration

Add scripts/bazel_policy_test.go, plain Go tests that run under both
`go test ./scripts` and `bazel test //scripts:scripts_test`:

- MODULE.bazel go_sdk.download version equals the go.mod toolchain.
- ICU policy: .bazelrc sets gms_pure_go for build, the go-mysql-server
  gazelle_override excludes regex_cgo.go, and the root BUILD.bazel
  carries `# gazelle:build_tags gms_pure_go`.
- .bazelversion pins an exact Bazel release.
- .bazelrc.local and user.bazelrc are gitignored (parsed from .gitignore
  and cross-checked with git check-ignore when in a checkout).
- No remote-execution endpoints or credentials in committed bazelrc-like
  files, Markdown docs or .github/**: remote/BES/TLS flags
  (--remote_executor, --remote_cache, --bes_backend, --remote_header,
  --tls_client_certificate, ...) with a literal value, with or without a
  URL scheme, and non-loopback gRPC URLs in rc/.github files. Placeholders,
  $VARIABLES, and loopback are allowed; Markdown gRPC URLs (OTel exporter
  docs) are not flagged. Skipped outside a git checkout, e.g. in the Bazel
  sandbox.

Each check is a pure function also exercised against fixtures that break
the invariant. The files the tests read are declared as data via
//:bazel_policy_files so they resolve from runfiles under Bazel.

scripts/check-build-tags.sh now treats Bazel invocations as governed by
.bazelrc: the shell command segment that invokes Bazel (split on &&, ||,
;, |, $( and backticks) is exempt from the per-line `go` tag check, while
a bare `go` in another segment of the same line is still flagged. When
any scanned file invokes Bazel (or .bazelrc exists) .bazelrc must set
--@rules_go//go/config:tags=gms_pure_go for build.
scripts/check_build_tags_test.go covers both in a temp repository.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(scripts): split bazel lines in pure bash so check-build-tags works with BSD sed

BSD sed (macOS) does not expand \n in s/// replacements, so the segment
split never happened and the Bazel-exemption tests failed on macos-latest.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(scripts): skip check-build-tags tests when bash lacks mapfile

macOS runners use /bin/bash 3.2, which has no mapfile; check-build-tags.sh
has always required bash >= 4, so the new tests are skipped there.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-27 03:41:02 -07:00
mtccressall
d14ed67f71
fix(list): expose comment bodies in bd list/show --json (be-73x) (#6473)
* fix(list): expose comment bodies and mark the omission in bd list --json (be-73x)

`bd list --json` reported comment_count and carried no comment text and no sign
that any was missing. The consequence is not a missing field: a content search
over a listing answers with a well-formed, NON-EMPTY result set whose matching
rows are absent, and nothing about that answer invites a second look. An empty
result invites suspicion; eight rows do not.

Two halves, and the second is the one that fixes what was actually reported:

  1. --include-comments on `bd list` populates each row's comments with the
     full bodies, the list twin of `bd show --include-comments`. Opt-in: it
     costs one query per row that has comments.
  2. Every row with a nonzero comment_count whose bodies were NOT hydrated now
     carries comments_omitted=true, by default, with no flag. A flag nobody
     knows to pass does not fix a silent hole; a marker on the row does.

The bodies ride on types.Issue.Comments, which already carried the `comments`
key for export/import and was simply never populated on this path, so the only
new field is the marker.

Hydration is one shared body (workapi.HydrateListComments) called from BOTH
issueops.Reader.List implementations, the store-backed and the unit-of-work
one. Those are separate bodies that have answered one contract method
differently before; it runs in the page epilogue beside FinishPageAt, after the
trim, so a page never pays for rows it is about to drop.

The source parameter is a CONSTRUCTOR rather than a source, and that is
load-bearing. Building the unit-of-work comment source eagerly made a
capability only the opt-in path uses into a requirement every caller had to
satisfy, and turned `GET /v0/beads/issues` into a 500 on a provider without a
comment use case — on requests that had asked for no comments. A count-only
listing now constructs nothing, pinned by a test that fails if the constructor
is called.

Tests pin each implementation separately rather than duplicating: unit tests
over a fake source, an embedded-dolt test over the real CLI on the direct
route, and a proxied-server test over the real CLI on the unit-of-work route.
Sabotage-controlled three ways — no-op the shared body and all three suites go
red; unwire either reader alone and only that reader's CLI test fails, which is
what proves neither integration test is redundant.

Not addressed, deliberately: gt-mfp5 (bd comment does not advance updated_at,
the orthogonal recency axis) and be-ozp (bd ready --json carries no marker; it
does not route through Reader.Ready).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XK4B7N2CrgfKGEQvDTPM4D

Executed-By: beadsrig/polecats/dag

* fix(list): do not read a skipped comment count as proof of no comments (be-73x)

Codex review of the parent commit, correctly.

`IncludeComments: true` combined with `SkipCounts: true` returned a page with
no comment bodies at all — no error, no marker, nothing — while
`IncludeComments` documents a guarantee to populate them. The hydration loop
skipped any row whose CommentCount was zero as an optimisation, and SkipCounts
zeroes every count: `issueops.ListRequest.SkipCounts` says in its own doc that
a zero then means UNKNOWN rather than none.

That is this bead's own failure mode reintroduced one layer down by the fix for
it: a silent, well-formed, empty answer to a request that asked for content.

I had considered the interaction and resolved it wrongly, in a comment reading
"the count is authoritative here because the JSON route never sets SkipCounts".
True of today's CLI callers, and not a property of the contract — issueops
.ListRequest is a PUBLIC request type and permits both fields at once. A
comment saying "X cannot happen because of how callers behave today" on a
public type is a bug with a justification attached, and worse than no comment,
because it tells the next reader the case was checked.

countsKnown is now a parameter rather than an assumption; call sites pass
!req.SkipCounts.

  countsKnown true   a zero count proves a row has nothing; skip its query.
  countsKnown false  query every row, because nothing proves otherwise, and
                     mark no row omitted, because comments_omitted asserts a
                     nonzero count the page cannot support.

The second half is the mirror defect on the marker path — the same conflation,
the other direction — which the review did not name.

No behaviour change on any current CLI path: the JSON route never sets
SkipCounts, so it passes countsKnown true, and the text route asks for no
comments and marked nothing before either. Verified: `bd list --json` output
identical, and text output identical with and without the flag.

Regression tests HonorsIncludeWhenCountsAreSkipped and
MarksNothingWhenCountsAreSkipped. Sabotage-controlled: restoring the
count-authoritative skip fails the first with "issued 0 comment reads, want 2".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XK4B7N2CrgfKGEQvDTPM4D

Executed-By: beadsrig/polecats/dag

* fix(list): resolve the comment plane by residence, not by the row's flags (be-73x)

Maintainer review fixup for #6473, iteration 1. Both review lanes reached the
same major independently and the synthesizer re-verified it against the tree.

The new list hydration derived the comment table from the row's own
Ephemeral/NoHistory flags - issueops.IsWisp's rule, which is right for routing a
record being WRITTEN and wrong on a read. `bd import` pins a `no_history` record
to the DURABLE table while preserving the flag on the row, because clearing it
would change the content hash and break export->import->export byte-identity,
and every clone materializes its database by importing JSONL. So a promoted
no-history bead that has been through a round-trip is a durable row whose flags
say wisp:

  bd list --json --include-comments   read wisp_comments, found nothing, and
                                      returned comment_count=N beside an empty
                                      `comments`, with no marker and no error
  bd comment, bd show                 write and read that same row's comments on
                                      the issues plane, by found-table

That is be-73x's own failure mode reintroduced under the flag whose contract is
"gets them or gets an error", and a cross-role divergence: `bd list` and
`bd show` disagreed about one row. The mirror case is real too - an import
record whose `wisp_plane` key pins it to the wisps table with neither flag set
reads back as durable - so no flag-based rule gets both directions right.

The plane now comes from the seam that knows it. HydrateListComments takes a
CommentPlanes lookup instead of inferring; the unit-of-work reader answers it
from the wisps TABLE (IssueUseCase.GetWispsByIDs, the call edgeReader.ReadEdges
already makes for the same question), once per page, inside the page's own read
transaction. The store-backed seam passes SourceRoutesCommentPlanes because its
source routes ids itself (DoltStore.GetIssueComments picks the table from
isActiveWisp) and would buy a lookup for an argument it ignores. isWispPlane is
deleted: nothing on this path infers a plane any more. A nil lookup is an error
rather than a silent "durable", so a third seam has to answer the question
rather than inherit the default this bug was.

A MISSING WISPS TABLE STAYS "NO WISPS" rather than a failed listing, classified
through the same two helpers the counts query that produced the page uses
(dberrors.MissingTableName + sqlbuild.OptionalWispTable). Any other failure of
the lookup fails the call: a guessed plane answers with the wrong table's
contents and nothing in the response shows it.

Tests. The unit table now asserts residence AGAINST the flags, with each row's
comments present only on the plane it lives on, so a wrong-table read shows up
as missing TEXT and not merely as a wrong flag in a recorded call. Restoring the
flag inference reds exactly the two rows where flags and table disagree
(durable-carrying-no_history, wisp-table-carrying-no-flags) and leaves the two
agreeing rows green. The old `override_wins_over_flags` case is gone:
WispPlaneOverride is `json:"-"` and set only by import, in memory, so no scanned
row can carry it and that branch was unreachable on this path - which is what
made the suite look sufficient (Codex's separate minor, folded in here as the
same root cause). New seam-level tests drive the real uow Reader.List over both
shapes, and pin that a listing without the flag resolves no planes at all, that
a missing wisps table is tolerated, and that any other lookup failure
propagates; emptying the residence answer reds the wisp-row leg.

Also from the review, non-gating:

- types.IssueWithCounts.CommentsOmitted and the OpenAPI property stated the
  marker rule unconditionally on a type Reader.Ready and the claim response also
  return, neither of which calls the epilogue. Both now scope the rule to the
  List surfaces and cite be-ozp, which is where the parent commit deliberately
  left the ready surfaces. (`bd ready --json` does not route through
  Reader.Ready; GET /v0/beads/ready and ClaimNextResponse.claimed do.)
- GET /v0/beads/issues gained no `include_comments` parameter, so its
  description now says so and points at the detail read, in the idiom the
  `revision` paragraph above it already uses.
- One internal/httpapi list test for the new wire field: the marker present for
  a commented row, absent for an uncommented one. It was asserted only by the
  spec file; the detail twin has get_issue_test.go. Neutering
  markCommentsOmitted reds it.

Validation: go build ./...; go vet over the changed packages and again with
CGO_ENABLED=0; make api-check clean, so the spec edits oblige no regeneration;
go test ./internal/workapi/... ./issueops/... ./internal/types/;
TestBothReaderImplementationsAgreeOnTheListEpilogue plus the new plane tests in
./internal/storage/uow/; BEADS_TEST_PROXIED_SERVER=1
TestProxiedServerListComments 3 PASS and BEADS_TEST_EMBEDDED_DOLT=1
TestEmbeddedListComments 4 PASS.

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

---------

Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-27 02:12:13 -07:00
cyb3rd0g01
48b9e904dc
fix(import): seed issue_prefix from config.yaml before the batch guard needs it (#6624)
* fix(import): seed issue_prefix from config.yaml before the batch guard needs it

NewBatchContext (via ReadConfigPrefix) unconditionally requires an
issue_prefix row in the database's own config table before creating
any issue. bd init writes that row via SetConfig, but a database an
external tool provisioned directly (e.g. an orchestrator that created
the Dolt database via SQL and pointed config.yaml at it without ever
calling bd init) never gets one. Every bd import then failed with
"issue_prefix config is missing", even though config.yaml carried the
prefix and bd where/bd context resolved it correctly.

bd import already had logic to sync config.yaml's prefix into that
table, but only after a successful import — useless when the import
itself can't start without the row. This moves an equivalent, guarded
sync (only fires when the table is empty, never overwrites an existing
prefix) before the import attempt, reading config.yaml directly via
GetStringFromDir rather than the global config singleton, since that
singleton isn't guaranteed to be initialized this early in the import
path.

Added a regression test that reproduces the exact failure with stock
bd (bd init --server, then delete the config-table row and write
config.yaml by hand — no orchestrator involved) and confirms it now
imports successfully.

* fix(import): address review — proxied-mode parity, --global exclusion, GetString

Three issues from @bee-ghosttrack's review of ffb32fb:

1. Proxied-server mode had the identical bug: importer.go's ImportBatch ran
   CreateIssuesInTxWithResult (-> NewBatchContext -> ReadConfigPrefix) before
   its own SyncIssuePrefix reconciliation, in the same transaction. Seeds the
   prefix before create there too, when the table is empty.

2. --global was not excluded from either sync (import.go's existing
   post-import sync and this fix's new pre-import seed, plus the proxied
   path's SyncIssuePrefix source). config.yaml is per-project; the shared
   global store's own prefix must win in --global mode (selectCreateIDPrefix
   already established this for `bd create`), or a project's local prefix
   silently overwrites the shared database with two dolt commits.

3. GetStringFromDir's rationale didn't hold: config.Initialize() has already
   run by main.go's init() and prepareSelectedCommandContext, and
   GetStringFromDir skips the config.local.yaml overlay GetString honors —
   disagreeing with the sync 40 lines below it. Switched to GetString,
   matching import.go:415 and import_proxied_server.go's existing usage.

Smaller fixes: TrimSpace + validatePrefix on the seeded value (a failed
validation now warns instead of writing an invalid prefix); SetConfig/Commit
failures now warn to stderr instead of being silently swallowed.

Test changes:
- Added TestImporterUOW/SeedsPrefixBeforeCreateNeedsIt, exercising the
  proxied-mode fix directly at the unit-of-work layer (no CLI/container
  overhead) by clearing config-table issue_prefix and confirming
  ImportBatch still creates issues. Revert-mutant confirmed: fails with
  the identical "issue_prefix config is missing" without the fix.
- Rewrote the E2E test with this repo's server-mode conventions:
  skipIfNoDolt, uniqueTestDBName + dropTestDatabase, explicit --server-port
  — no longer leaks a database on the shared test server.
- Added TestCLI_Import_GlobalModeIgnoresProjectConfigYAMLPrefix (separate
  file, cgo-only build tag, using the shared-server harness from
  global_identity_integration_test.go): confirms a --global import does not
  adopt a project's config.yaml prefix. Revert-mutant confirmed: without the
  --global guards, the shared global store's prefix is overwritten by the
  local project's ("global" -> "localproj").

go build ./... clean; go vet ./cmd/bd/... (both with and without -tags
"cgo integration") clean; gofmt -l clean on all touched files.

* fix(import): commit the seeded prefix on an empty batch; one resolved prefix

Maintainer review fixup for PR #6624 (iterations 1-2). Addresses the two major
findings and the nearby minors/nits.

MAJOR — the proxied seed was discarded on a batch that landed no rows.
The seed wrote issue_prefix but left ImportBatchResult.PrefixSynced false, so
importBatchCommitMessage produced "" for a batch with Created == 0 and no
memories, RunTxResultWithin skipped uw.Commit on the empty message, and the
deferred closeAttempt ROLLED BACK the seeded row. `bd import` reported success,
the prefix never landed, and a re-run dedup'd again — the state never
converged. Reachable against a missing-prefix database whenever every input row
is dropped by the in-transaction stale guard or the CLI's title dedup. The seed
now reports itself through PrefixSynced, restoring the "the prefix sync runs
even when the batch is otherwise empty" contract (be-llaf) that
import_proxied_server.go's comment promises; the field's doc says so too.

MAJOR — that arm had no coverage in any lane that runs.
TestImporterUOW/SeedsPrefixEvenWhenEveryRowIsRejected pins it: empty stored
prefix + SyncIssuePrefix set + every row stale-rejected => the prefix is
committed, under the sync message, with history moving exactly one entry. It
fails on the pre-fixup tree on all four assertions. The existing
SeedsPrefixBeforeCreateNeedsIt cannot catch this (Created == 1 carries the
commit) and PrefixSyncAloneCommitsUnderTheSyncMessage runs with a non-empty
stored prefix, so its seed never fires. Both are tag-free and container-free,
so unlike the classic-path e2e they execute in ordinary lanes.

Minors and nits:

- Seed errors are returned, not warned. A SetConfig failure here is a
  precondition failure for the very next statement: swallowing it surfaced as
  the "issue_prefix config is missing" error this seed exists to prevent, and
  hid serialization failures from RunTxResult's retry classifier. Drops the
  os import.
- Classic path resolves ONE prefix for both its writers (importSyncPrefix;
  iteration 2 below extends the same resolver to the proxied path). The
  seed used a TrimSpace'd + validatePrefix'd value while the post-import sync
  used the raw one, so (a) a prefix the seed refused still reached the database
  through the sync, bypassing the guard this PR adds, and (b) a padded
  `issue-prefix: " bd"` made the two disagree and the sync overwrote the
  trimmed value. TestImportSyncPrefix pins the resolver with no store and no
  container; each arm mutation-proved independently. Side effect: the flagged
  worst_changed function drops from cyclo 25/cognitive 43 to 22/34.
- Warnings name the whole effect on both paths: an invalid issue-prefix
  disables the sync as well as the seed, which base did not do.
- The --global isolation test anchors what its "before" value IS, so the
  after == before comparison cannot go vacuous. The anchor is
  doltserver.GlobalIssuePrefix, NOT the --prefix passed to init: --prefix names
  the project's prefix and `bd init --global` always writes the constant
  (init.go), which an unanchored equality had been hiding.
- Comments record two boundaries the diff left unstated: the classic seed
  commits before an import that may fail (deferring it is not an option — the
  post-import CommitWithConfig is gated on dbPrefix != syncPrefix, which a seed
  makes false, so the row would stay uncommitted because store.Commit excludes
  config (GH#2455), and a dirty internal config key blocks the next pull); and
  a --global import against a global database missing its own
  config.issue_prefix stays unseedable by design.

Iteration 2 — three non-gating findings (both majors above stayed fixed; the
fresh synthesis and quality scorecard both say approve):

- The classic seed now runs BEFORE the memory writes. CommitWithConfig is
  DOLT_COMMIT -Am, so it stages everything dirty at that instant: with the seed
  below the memory loop, a `bd import` carrying memories against a
  missing-prefix database whose issue phase then failed left those kv.memory.*
  rows PERMANENTLY COMMITTED, under a message asserting the commit is the
  prefix seed — where at base the failure left the whole working set for the
  operator to discard. Seeding first restores "the only thing this commit can
  carry is the prefix". Pure statement reorder: the seed reads only issues,
  syncPrefix and the config table, and the ordering is now recorded as
  load-bearing at the block so a later edit does not undo it.
- The proxied path CALLS importSyncPrefix() instead of restating its four rules
  inline. The two copies were identical rule for rule — same globalFlag guard,
  same TrimSpace, same validatePrefix, byte-identical warning — but only the
  classic copy was pinned, so the underscore-key fallback ReadConfigPrefix
  honors, or hyphen normalization, could have reintroduced ACROSS import modes
  exactly the divergence the bullet above closed within one mode. One
  implementation now, so TestImportSyncPrefix's six rows govern both routes.
  Drops the os, strings and config imports from import_proxied_server.go.
- The uow subtests no longer lean on suite order.
  SeedsPrefixEvenWhenEveryRowIsRejected snapshots the sync-message history
  count before the batch and asserts +1: the old `n != 0` form could not fail
  in a full-suite run, because PrefixSyncAloneCommitsUnderTheSyncMessage has
  already committed under that message by then. Mutation-proved — routing an
  all-rejected batch to a "0 issues from ..." message reds only the new
  assertion ("moved 1 -> 1"), and the 1 in that output is precisely the count
  that would have satisfied the old form. SeedsPrefixBeforeCreateNeedsIt also
  restores issue_prefix the way its two neighbours do, instead of leaving the
  fixture to be restored by the code under test.

The PR description's stale "GetStringFromDir / config.GetString returned empty
in this exact spot" claim and its "single-file production change" scope claim
were corrected on GitHub, and the CI-lane reality for each added test is now
recorded there.

Validation (iteration 1): gofmt clean; go build ./...; go vet on cmd/bd,
internal/storage/uow and issueops; full internal/storage/uow package green
(570s, under a private temp root); focused cmd/bd import tests,
TestImportSyncPrefix, TestEmbeddedImport/prefix_sync{,_no_config_key} and the
--global isolation e2e all green.

Validation (iteration 2): gofmt and `git diff --check` clean; go build
./cmd/... ./internal/storage/uow/...; go vet on cmd/bd and
internal/storage/uow; full TestImporterUOW green in subtest order (9/9) plus
the mutation A/B above; TestImportSyncPrefix green (6/6). Two reds in the wider
`go test -run Import ./cmd/bd` are environmental on this box and reproduce
identically with the fix set stashed: TestCLI_Import_GlobalModeIgnoresProjectConfigYAMLPrefix
dies inside `bd init` because the cloned remote is one schema version behind
this build (v66 -> v67), and TestImportBlockedDuringMigrationFreeze cannot
start its server (port 3307 busy).

---------

Co-authored-by: ilasic <ilasic@reversinglabs.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
2026-09-26 15:01:04 -07:00
Harry Miller
0e317c4fc0
fix(query): apply bd list's piped-output limit policy to bd query (#6229) (#6744)
* fix(query): apply bd list's piped-output limit policy to bd query (#6229)

Root cause: bd list resolves an unflagged --limit through a policy that
treats piped stdout as unlimited (GH#4094), but bd query read its --limit
flag straight through, so its default of workapi.DefaultQueryLimit (50)
applied to piped output too. `bd query '...' | consumer` silently dropped
every row past 50; the truncation hint did not fire either, because it only
prints when stderr is a terminal.

Fix: factor the unflagged tail of bd list's policy into unflaggedLimit /
resolveUnflaggedLimit in list_input.go and call it from both commands, so
they cannot drift. bd list's switch is unchanged in behavior; bd query's
change is a single localized branch in gatherQueryInput.

Precedence for bd query, mirroring bd list:
  1. explicit --limit (including 0) wins
  2. piped stdout -> 0 (unlimited)
  3. agent mode on a terminal -> 20
  4. otherwise the 50 default
bd list keeps its own --all and list.limit branches ahead of step 2; bd
query has neither (its --all means "include closed", and there is no
query.limit config key), so none was invented.

Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* review: document the query path's absent defensive cap; unstale a reachability comment

Maintainer review fixes for PR #6744 (GH#6229). Both are comment-only; no
behavior changes.

issueops.QueryRequest.Limit now states that nothing backstops it. ListRequest
pairs its Limit with MaxRows, a circuit breaker for an oversized answer, and
neither knob that sets that one (--max-rows, BEADS_MAX_ROWS) is read anywhere
on the query path, so an unlimited query is unbounded in the plain sense. That
was already reachable via `--limit 0`; this PR makes a piped `bd query` reach
it without asking, which is what makes it worth writing down. Recording the
absence is the documented half of the reviewers' choice — threading a MaxRows
twin onto QueryRequest stays available as a follow-up.

unionCountsGoSideSortKeepsTheRightSubset's comment justified its case with
"DefaultQueryLimit means a limit is always set", which this PR falsified for
the CLI half: an unflagged piped `bd query '<expr>' --sort id` now arrives on
the IsGoSideSort path with Limit 0 and no bound. The HTTP surface still brings
a bound, because an absent `limit` parameter resolves to DefaultQueryLimit, so
the clause is requalified rather than dropped. The assertions were never
affected — they pass an explicit Limit: 5.

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

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
2026-09-26 02:50:09 -07:00
Julian Knutsen
b3d17caa6d Merge release/1.3.0 into main (post-tag forward-port)
Forward-ports the 38 commits that shipped on release/1.3.0 (tagged v1.3.0 at
f45b249ce) into main, as RELEASING.md mandates after a tag. None of them had
ever been forward-ported. Recorded as a merge so main becomes a superset of
the release branch and the lineage is in the history.

Migration ordinal collision (the reason this needed a human-shaped merge):
both branches independently claimed clone-local ignored slot 0026 under
different filenames, so git merged both in with no conflict and left the
series with two migrations at ordinal 26 — a single-integer cursor cannot
address that, and migrationSource.list() panics on it.

Main's ignored/0026_add_wisps_current_revision is renumbered to 0027.
Release's 0026_dep_rekey_dedup_marker is in the shipped v1.3.0 tag, so field
stores have already recorded it at 26 and it can never move; main's twin has
never shipped in any release, so it is the one that is free to move. 0027 was
unused in the ignored series (both sides topped out at 26).

This trips check-migration-hygiene.sh Check C (frozen migrations), which has
no exemption mechanism. That is expected and accepted: breaking the collision
requires a rename, and the ignored series' cursor table is itself dolt-ignored,
so its content hashes are clone-local and never participate in the cross-clone
ContentHashSkew comparison that Check C exists to protect. Main's 0067 body is
deliberately NOT edited for the same reason in reverse — it is main-plane and
its hash IS compared across clones.

Conflicts resolved:

  CHANGELOG.md                       release's finalized [1.3.0] section kept
                                     byte-identical; main's two unreleased
                                     entries (#6023, #5859) moved up under
                                     [Unreleased] where they belong
  cmd/bd/init_safety.go              union — release's added paragraph is
  cmd/bd/init_safety_help.go         accurate against the merged code (three
                                     exit-12 sources, incl. init.go:3147)
  internal/storage/uow/dolt_sql_provider.go
                                     kept main's newProvider refactor AND
                                     release's readOnly field/assertion;
                                     newProvider gained readOnly: opts.readOnly
                                     so release's read-through-refused-migration
                                     behavior survives main's refactor
  .github/workflows/main.yml         single -timeout=30m per release's #6091
  scripts/ci_workflow_test.go        design (flag on the invocation, not in
                                     matrix.test-flags); the shadowed 25m in
                                     matrix.test-flags removed
  scripts/migration-test/lib/versions.sh
                                     union — main's darwin/arm64 corpus plus
                                     release's v1.2.2 linux/amd64 entry
  integrations/beads-mcp/uv.lock     ruff 0.16.5 (release, newer); block is
                                     internally consistent, uv lock --check ok
  default.nix                        vendorHash left at main's value and is
                                     KNOWN STALE — see below

Version stamp lands at 1.3.0 (main had been sitting at the previously-released
1.2.2, this project's between-releases pattern). check-versions.sh: 24/24.

Known follow-up: default.nix vendorHash. The merged go.mod/go.sum is a genuine
union (release's kin-openapi/oapi-codegen bumps + main's newer Dolt stack) and
matches neither side, so neither recorded hash is correct. It must be
regenerated with scripts/update-nix-vendorhash.sh. The repo's automatic fixer
(update-vendor-hash.yml) is dependabot-only and will not run on this PR.
2026-09-15 22:09:13 +00:00
Vishnu J
f5a20fb66b
fix(list): honor --status when combined with --ready (#5924)
* fix(list): honor --status when combined with --ready (#5832)

`bd list --status X --ready` silently dropped --status and returned the
unfiltered ready set (typically open issues). BuildListFilter pinned
StatusOpen whenever ReadyFlag was set, and ReadyFilterFromIssueFilter
hard-coded the same pin, so a custom status or in_progress selector
never reached GetReadyWork.

--ready without --status still defaults to open. An explicit --status
is now the ready-work status selector, matching how other list filters
already compose with --ready. `--status all` remains the no-filter
spelling and keeps the open default.

* fix(list): status-aware --ready footer and honor-path contract docs (#5832)

The query intersection from the prior commit is unchanged. Round-1
review asked the ReadyFlag/Statuses contract comments and the text
footer to describe the honor path: default --ready is still open,
an explicit --status is named instead of "excludes in_progress".
2026-09-02 18:12:07 -07:00
postoso
267085264d
feat(count): support --metadata-field filtering (#6024)
* feat(count): support --metadata-field filtering

* fix(count): review refusal docs, guard test, and changelog

---------

Co-authored-by: postoso <postoso@users.noreply.github.com>
2026-09-02 17:25:57 -07:00
Julian Knutsen
9884b3dd33
chore(api): mark new exported packages experimental before v1.3.0 (#6036)
Maintainer decision D-7: the ~52k-line exported Go surface added since
v1.2.2 should not freeze as a v1 compatibility commitment at the 1.3.0
tag. backend/ and backend/conformance/ already carried a Stability
section; this adds the matching disclaimer to the other new root-level
exported packages.

Doc comments only, no behavior change.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-29 16:01:30 -07:00
Julian Knutsen
8aaefe2d4f
feat(httpapi): serve bd list's order with sort on listIssues (#5666)
* feat(httpapi): serve `bd list`'s order with `sort` on listIssues

The issue listing served one order, `(created_at DESC, id ASC)`, because the
cursor is a keyset position in it. The spec stated the constraint in its own
words: "the sort order is welded to the cursor contract, and a new order needs
new surface." That welding put the cost on every client wanting `bd list`'s
ordering — the only way to get it was to page the whole result set and sort
locally, which is the one cost on this surface that grows with the project.

Measured against a real `bd serve` over 1400 rows at the 200-row page an HTTP
client actually uses: walk-and-sort is 7 requests plus a client-side
comparator, `?sort=priority` is 1. Both are checked against `bd list --json`
row for row, because the claim that matters is not "fewer requests" but "the
same order".

`sort` takes `created` and `priority` and nothing else. Each value is a keyset
contract — a position shape, a strictly-after predicate, an index — not a
display preference, and both keys are provably total (priority and created_at
are non-null, id is unique) so a page boundary inside a run of equal keys
resolves on id. The seven other orders `bd list --sort` takes have no such key:
`id` is natural-numeric and no database expresses it, `updated` moves on every
write, `closed` is nullable, and status/title/type/assignee are mutable and
unindexed. `priority` here is (priority ASC, created_at DESC, id ASC), which is
both `bd list`'s flagless order and what `--sort priority` produces — a stable
priority sort over the created order is the same sequence — so one served order
retires the walk for both.

Absent `sort` still means `created`, permanently: it is the compatibility
contract for every client written before the parameter existed.

THE CURSOR NOW CARRIES ITS ORDER. This is the half that makes the parameter
safe rather than merely useful, and the obvious implementation gets it wrong.
The token was base64 of `{t,i}` with no binding, so a created-order cursor
replayed under `sort=priority` decoded perfectly and was read as a position in
a different total order — a page that skips and duplicates rows, served with a
200, undetectable by the client. Tokens are now `v2` with an explicit order
member, and decode takes the wanted order as a parameter so a mismatch is
unrepresentable at the seam rather than merely detectable past it. Outstanding
`v1` tokens stay readable as the created-order positions they are, so no
traversal in flight has to restart. This does not contradict "the token carries
no filters": filters select the set, the order decides what the position means.

Storage grows one field. IssueFilter.AfterPriority extends the existing
position; the predicate nests the created one rather than restating it, because
the created/id comparison is only reachable at the cursor's own priority.
Flattening it the way the created predicate's leading-bound trick invites looks
equivalent and is not — it re-delivers rows at the cursor's priority created
after it, which the new conformance walk catches against real Dolt.

NO INDEX MIGRATION, by measurement rather than by omission. A composite
(priority, created_at, id) index was tried on Dolt 2.2.0 against the production
predicate, in both the plain ascending and the mixed-direction spelling Dolt's
DDL accepts: the plan is byte-identical in all three cases, keeping the
single-column priority seek and the TopN. It would have bought write
amplification on every insert and every priority update for no measured change.
The sargability guard pins what is achieved — an IndexedTableAccess range on
idx_issues_priority — and records the measurement to redo if Dolt learns to
stream the composite.

Agent-Signature: claude-opus-5
Co-authored-by: CI Bot <ci@beads.test>

* fix(changelog): drop leftover diff3 conflict marker in sort entry

The rebased adopt-PR head left a stray '|||||||' merge-base marker on the first line of the new `sort` CHANGELOG entry (CHANGELOG.md:381), which `git diff --check` flagged as a leftover conflict marker. Remove only the marker line; the resolved entry content is unchanged. Maintainer fixup for PR #5666 adoption review.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-27 09:21:12 -07:00
Jim Wordelman
f6a191fd64
fix: canonicalActor collapses the --/__ axes correctly; claim-verify uses ActorMatches (be-p7dzx, bundled be-vc51) (#5856)
* test(feat): red — canonicalActor collapses the --/__ axes: misses gascity slash identities and widens ActorMatches (bundled with be-vc51 authorize/verify split) (refs be-fh0g)

* feat: green — canonicalActor collapses the --/__ axes: misses gascity slash identities and widens ActorMatches (bundled with be-vc51 authorize/verify split) (refs be-fh0g)

* docs(identity): correct the five contract surfaces that still document the pre---- collapse rule

canonicalActor stopped collapsing an exact "--" run when it started decoding
that run to "/", but five places still tell a reader the old rule: a run of
".", "_" or "-" matches any other such run. That is now false for "--", and
two of the five are public contract surfaces rather than internal comments --
the OpenAPI description a client reads, and the conformance text a backend
implementor is expected to satisfy.

Corrected in place, all saying the same thing: an exact "--" run decodes to
"/" because that is gascity's session-name encoding of a rig-qualified
agent's slash, so "a--b" matches "a/b" and no longer matches "a__b" or "a-b";
longer and mixed runs, "__" included, still collapse.

  issueops/releaser.go                      ExpectedAssignee's contract
  issueops/issueops.go                      the update-side cross-reference
  internal/httpapi/spec/openapi.v0.yaml     wire contract (source of truth)
  internal/httpapi/apigen/types.gen.go      regenerated via make api-gen
  backend/conformance/releaser_contract.go  cross-backend contract text

The conformance limb is annotated rather than re-pinned: the respelling it
exercises is "-" -> "_", which this change does not affect, so it stays green
either way -- which is exactly why CI could not catch the stale text. Adding a
"--" limb there would pin new cross-backend behavior and is a wider change
than correcting a contract description.

This is the keep-in-sync obligation identity.go records under ga-5ksp5,
applied to the documentation half.

* docs(changelog): record the --/__ equivalence-class change under [Unreleased]

The actor-matching change is user-visible and silent: it moves which stored
spellings compare equal for ExpectedAssignee on release and update, and for
claim/close/unclaim authorization. "gastown--mayor" starts matching
"gastown/mayor" and stops matching "gastown__mayor" and "gastown-mayor".

The entry says the widening is the intended fix -- "gastown--mayor" is the
agent "mayor" on rig "gastown" while "gastown__mayor" is the dotted alias
"gastown.mayor", and matching them was wrong -- and then states the part a
reader actually needs to act on: any stored "--" spelling that is NOT a
gascity slash encoding changes equivalence class with no error to notice.

---------

Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
2026-08-19 13:23:35 -07:00
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