beads/issueops/errors.go
Bee 2cae0c1ad8
fix(storage): a parent-child edge propagates only the parent's exogenous blockedness (#6506) (#6602)
* fix(storage): parent-child cascade propagates only exogenous blockedness (wy-3eb07b, #6506)

A parent-child edge used to cascade the parent's is_blocked bit to its
children WHATEVER set it. So the "close gate on the epic" idiom — P carries
blocks edges onto its own children C1 and C2 so P cannot close before them —
darkened the very children P was waiting for. Neither child could reach
bd ready, so neither could be worked, so neither could close: a permanent
lock, and the one direction cmd/bd/dep.go does not refuse.

The contract (#6506): a parent-child edge propagates only EXOGENOUS
blockedness. P counts as blocked FOR CHILD C iff P has a blocking reason —
an open blocks/conditional-blocks target, or a live waits-for gate — whose
target is NOT one of P's own parent-child children, or P's own parent is
(recursively) exogenously blocked. P's OWN is_blocked is unchanged: it really
does depend on open children. Only the propagation narrows.

DESIGN: a second-pass predicate on the parent row, not WITH RECURSIVE.
Both parent-child legs of shouldBeBlockedIDsUnionScopedSQL keep their
p.is_blocked = 1 conjunct and gain parentCascadesBlockedSQL, which says "p's
blockedness is not solely explained by p's own children":

    EXISTS (blocking reason of p whose target is not p's child)
      OR NOT EXISTS (blocking reason of p whose target IS p's child)

The second disjunct carries the contract's recursive clause through the
EXISTING fixpoint instead of through SQL recursion: a parent that is blocked
with no child-targeted reason of its own is dark either exogenously or
because ITS parent is, and either way its children inherit — one level per
pass, exactly as the cascade always converged.

A recursive CTE was the other candidate and is rejected on cost, not on
engine support. Its seed set is the direct-exogenous set, which includes the
waits-for gate, and the seed cannot be confined by the batch scope (%[3]s)
because a batch's ancestors are by definition outside the batch. That would
put an UNSCOPED whole-table gate evaluation into every batched mark/unmark —
the statement shape #6288 removed, now on every write instead of only on the
full repair. The predicate here is correlated to a parent that is already
known blocked, so it probes idx_dependencies_issue for a handful of rows.
The scope splice, the DISTINCT waits-for barrier and the doctor-count
lockstep are all untouched.

One gap this form does not express: a parent that is BOTH blocked by its own
open child AND darkened by an exogenously blocked ancestor is not
distinguishable from one blocked only by its children, so its children stay
bright. That is an under-propagation in a corner the contract would darken;
it needs a second stored bit (or the CTE above) to see, and it cannot
recreate the lock this commit removes.

Also: AffectedByDepChange{,ForWisp}InTx now seeds the parent's other children
on a parent-child edge change (appendSiblingsUnderParentInTx). Writing that
edge reclassifies the parent's blocking reason on the new child from
exogenous to child-derived, which flips the answer for the SIBLINGS — the
close-gate epic is built one child at a time, and the second edge is what
un-darkens the first. Without it the incremental write path and the full
repair disagree, which the new tests catch as a nonzero doctor count.

Tests (internal/storage/dolt/blocked_consistency_test.go), all four seeded
through the real write path and each verified RED against the pre-fix SQL
except the control:
  - ParentBlockedOnlyByItsOwnChildren: the repro, plus a GetReadyWork
    assertion that the children are workable again.
  - ExogenousParentStillCascades: the control — the fix narrows the cascade,
    it does not remove it. Green before and after.
  - ThreeLevelChainBothWays: GP exogenous darkens P and C; GP blocked only by
    its child P darkens neither. Repaired from an inverted plane too, since
    the chain is the case that needs more than one pass.
  - WaitsForGateOverOwnChildren: a gate whose spawner is the parent's own
    child does not darken; one on an outside spawner does.

TestRecomputeAllIsBlocked_CascadesThroughParentChild is unchanged and green,
including its single-pass lower-bound count — which is why the legs keep the
p.is_blocked = 1 conjunct rather than deriving the cascade from the graph
alone.

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

* feat(dep): warn when a parent blocks on its own child (wy-3eb07b, #6506)

`bd dep add P C` where C is already P's parent-child child is the "close gate
on the epic" idiom: P carries a blocks edge onto its own child so P cannot
close before it. dep.go refuses the OTHER direction (a child blocking on its
dotted-ID parent, "would create a deadlock") and says nothing about this one,
which is the direction that used to deadlock for real — the cascade darkened
the child, so it could never reach bd ready, be worked, or close.

Since the cascade fix the edge is harmless, so this is an advisory, not a
refusal: it names what the edge now means (the parent stays blocked; the
child and its siblings are NOT hidden from bd ready) so an operator does not
have to rediscover the contract from a query.

It fires only for blocks/conditional-blocks, only after the edge has actually
landed and committed, and stays silent on any read error — an advisory must
not turn a successful write into an error, and must not precede a refusal for
an edge that was never written (the hierarchy and cycle guards reject this
pair whenever both edges already exist, in either order, which is why the
shape usually arrives one edge at a time or through import).

Unlike the D1 implicit-blocks warning it is NOT gated on an interactive
stderr: that one fires on the documented-default majority path, where
training callers to ignore stderr is the risk; this one fires on a rare
deliberate shape, and an agent wiring a close gate is exactly the caller who
should read what it does.

Wired into both direct paths (`bd dep add` and `bd dep --blocks`); the
proxied-server paths return earlier and are untouched.

Tests beside the existing dep-add warning tests: the predicate table
(including the two controls — right id with a blocks edge is not a child, and
the parent's other children do not match), the message content, and the type
gate proving it returns before touching the store.

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

* feat(doctor): report parent-blocks-on-own-child edges (wy-3eb07b, #6506)

A new "Parent Close Gates" check lists every blocking edge from a parent onto
one of its own parent-child children — the close-gate idiom, where P blocks
on C1 and C2 so P cannot close before them.

INFORMATIONAL, with no --fix and no effect on the overall result. Before the
cascade fix these edges were a trap: the parent's blocked bit propagated to
its children whatever set it, so the gate hid the very children it was
waiting for and nothing under it could become ready. The cascade now
propagates only exogenous blockedness, so the edges are legal and usually
deliberate. What an operator wants from doctor is therefore the inventory —
which beads in this store use the idiom, and where a pre-6506 store's
mysteriously invisible children came from — not a repair, and certainly not a
warning that would train people to remove a working gate.

It is the mirror of the existing "Child-Parent Dependencies" check, which
finds a CHILD blocking on its PARENT (still a deadlock, still fixable). The
two differ in how they match: that one reads dotted-ID ancestry, this one
matches real parent-child edges, because the close gate is wired between
unrelated ids.

Tests beside the child-parent ones: the empty inventory (with an ordinary
hierarchy present, which must not be mistaken for a gate), and the reported
case with two controls in the same fixture — an exogenous blocker on the
parent and an ordinary blocker on the child, neither of which may appear.

Gate note: these live in package cmd/bd/doctor, which the brief's cmd/bd
selector does not reach; `go test ./cmd/bd/doctor/` was run in full.

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

* revert(dep): drop the unreachable parent-blocks-own-child warning (wy-3eb07b, #6506)

This reverts 34b7f5b42. The warning it added could never print.

Its precondition is "a blocks edge from P onto C succeeded AND C is already
P's parent-child child", and the store refuses exactly that edge.
CheckBlockingHierarchyInTx (internal/storage/issueops/dependencies.go) rejects
a blocker that is the source's own descendant, and it sits OUTSIDE the
SkipCycleCheck gate, so no caller opts out of it; batch_apply.go:533 applies it
again on the DependencyEditor path `bd dep add` actually uses. Written in the
other order, the parent-child edge that closes the pair is refused as a cycle.
So the reverted code paid a GetDependentsWithMetadata read on EVERY
blocks/conditional-blocks `bd dep add` to emit something no operator could
ever see, and its 102-line test pinned a predicate instead of a behaviour.

What an operator DOES hit is the refusal — and the cascade fix left its stated
reason false. It read "blocked status cascades to descendants, so <blocker>
would inherit the block and never close". Since #6506 a parent-child edge
propagates only the parent's exogenous blockedness, so the descendant does not
inherit and nothing deadlocks. The refusal still stands, because a blocks edge
is not how the hierarchy says "I close after my children" — so the reason now
names the form that is: a waits-for gate over the children, `bd gate`.

The same false sentence was the OpenAPI description of
Problem.blocker_is_ancestor, so it is corrected there too, with types.gen.go
regenerated by `go generate ./internal/httpapi/apigen/` to keep `make
api-check` green.

The doctor "Parent Close Gates" check from 4c5f2f77b is KEPT. A warning on a
write path that refuses the write is noise; an inventory of the edges a store
already carries — from import, from merge, from the pre-refusal past — is what
an operator can act on.

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

* fix(storage): the parent-child exogeneity test is over the whole SUBTREE (wy-3eb07b, #6506)

B1 of the adversarial review: 648ab0af6 tested "is this blocking reason's
target one of my own children" as a DIRECT parent-child child, but #6506's
contract is about blockedness originating outside the parent's own SUBTREE.
At depth 1 the fix worked; at depth 2 it left the permanent lock alive.

  P --blocks--> G,  pc C -> P,  pc C2 -> P,  pc G -> C

G is not P's child, so P read exogenous, so P darkened C, so C darkened G —
and G is the only row whose close can free P. Exactly the shape-1 mutual lock
the issue says no contract intends, one level down. Pinned as
TestParentChildCascade_ParentBlocksItsOwnGrandchild, verified RED at
4c5f2f77b: p/c/c2/g all blocked, all three children missing from ready work,
and the full repair changing nothing.

The test is now a real ancestor walk (subtreeWalkDepth levels of indexed
LEFT JOINs up from the reason's target), so a reason anywhere under the
blocker counts as its own.

Also B2 — the cost regression, which is the same edit, because the shape that
makes the test correct and the shape that makes it affordable are one
decision. The union's parent-child legs no longer carry a per-row correlated
EXISTS. They subtract an uncorrelated set instead:

    AND p.id NOT IN (parents explained by their own subtree)

and the UNBATCHED statements (full repair, doctor count) do not even spell
that set as a subquery: it is read ONCE per fixpoint pass and bound as ids.
A repair pass is four statements and each would otherwise derive the same set
twice; reading it once is the whole difference. The batched mark/unmark keep
the spliced subquery, where it is confined to the batch's own parents by the
existing scope splice and costs a few rows.

MEASURED, gastownhall/beads#6506 bar: full repair and doctor count <= 1.5x
origin/main, write path <= 1.2x. Committed benchmark
(internal/storage/dolt/blocked_scale_bench_test.go, -short-skipped), 1000
issues / 2870 deps / 333 blocked rows, embedded dolt 2.2.0, run INTERLEAVED
main/head to cancel machine drift, four pairs, medians:

                             origin/main 71c4cd08b   this branch   ratio
  full repair                 48 71 43 46 -> 47 ms   66 56 54 55 -> 55 ms  1.18x
  doctor count                55 62 44 53 -> 54 ms   67 61 57 57 -> 57 ms  1.06x
  write path, per CloseIssue  37 30 21 22 -> 26 ms   30 23 16 24 -> 23 ms  0.91x

All three inside the bar; the worst single PAIR is 1.38x on the repair and
1.30x on the count. The two sides disagree on blocked rows by construction
(604 on main, 333 here) — that IS the fix.

NOT inside a bar, and disclosed rather than hidden: the benchmark's fourth
timing, a 200-id RecomputeIsBlockedForIDsInTx (the bulk/import batched path,
which no metric in the review covered), is 53-63 ms on main against 400-556 ms
here — 6.9x at the medians. The cause is structural and measured: a batched
pass runs many small statements, each deriving the set twice, and the set
costs a few ms however it is written. The per-pass read that fixes the
unbatched statements makes the SMALL-batch case worse, not better (one
whole-store read costs more than the subqueries a two-id batch pays), so the
fix is a per-batch-scoped read threaded through expandBatchTemplate's
placeholder plumbing — a separate change, and the reason this timing is
committed rather than left in a scratch file.

Three shapes were built and measured before this one, all at the same scale:

  - the review's own: per-row correlated EXISTS with two more inside,
    3.3-3.7x full repair, 5.2x doctor count;
  - the set as a DISTINCT derived table LEFT JOINed on p.id, which is what B2
    recommended: ~30x. dolt plans a join operand as the inner side of a nested
    loop and rebuilds it per outer row — the correlated shape in a derived
    table's clothes. This is the one finding that contradicts the review, and
    it is why the set is subtracted with NOT IN instead;
  - WITH RECURSIVE for the ancestor walk: blew the driver read timeout on the
    full repair. A recursive CTE pays a query's overhead per ITERATION; the
    seeded walk cost 45 ms per evaluation against 6 ms for four levels of
    joins, which is why the walk has a horizon (subtreeWalkDepth = 4, epic ->
    sub-epic -> leg -> task). Past it a reason reads as exogenous, which
    propagates MORE and hides nothing the old code showed.

Seeding: AffectedByDepChange{,ForWisp}InTx now walks UP from a parent-child
edge's target, not just to it. Hanging G under C changes nothing about C and
everything about any ANCESTOR of C that blocks on G, so each such ancestor's
sibling set is reseeded — otherwise the incremental write path and the full
repair disagree, which the new test catches as a nonzero doctor count. The
walk is filtered to ancestors that carry a blocking reason at all: without
that filter a 70-deep chain reseeds every ancestor's subtree on every edge
written into it, which timed out TestGetReadyWork_ParentFilterReturnsDeepDescendants.

CHANGELOG now names the limitation the review ruled acceptable but undocumented
(a sub-epic blocked both by its own children and by an exogenously blocked
ancestor keeps its children visible), marked tracked upstream; bee files the
follow-up issue at PR time.

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

* fix(doctor): rune-safe Detail truncation, Category on the N/A returns (wy-3eb07b, #6506)

The "Parent Close Gates" check joins its inventory with U+2192, three bytes
wide, and then cut the joined string at byte 200. Two of every three offsets
land mid-rune, so `bd doctor --json` could carry invalid UTF-8 in Detail — a
display nuisance in the terminal, but a value a JSON consumer has to decode.
truncateDetail walks back to a rune boundary first; the test drives every
entry count from 1 to 120 so the cut lands at all three offsets within the
arrow and asserts utf8.ValidString on each.

The same byte cut appears twice more in this file (:101, :561) on ASCII-only
details. Left alone here: they are not this bead's, and changing them would
put a behaviour change in two checks a reviewer of #6506 has no reason to be
reading.

The check's two "N/A" early returns also omitted Category, unlike its three
real returns, which drops them out of the categorised report. Both now carry
CategoryMetadata.

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

* perf(storage): read the batched exogeneity set once per batch, not per statement (wy-3eb07b, #6506)

D1, the PR blocker from the round-1 review. The batched mark/unmark templates
spliced parentsExplainedBySubtreeSQL — the "which blocked parents are explained
only by their own subtree" query — into both of their parent-child legs,
batch-scoped. The scope made it look cheap. It was not: dolt pays for a
`p.id NOT IN (subquery)` once per leg per STATEMENT, and a batched pass is a
mark and an unmark, so one 200-id RecomputeIsBlockedForIDsInTx derived the set
four times and measured 6.9x origin/main (53-63 ms -> 400-556 ms). That is the
bulk/import path and the cost shape #6288 removed.

The set is now READ once per batch and BOUND into both statements as ids —
the same trade the unbatched full repair already makes per pass — which is why
markBlockedTemplate/unmarkBlockedTemplate are built per batch now: the number
of bound ids is a property of the batch. In front of the read sits a cheap
indexed guard, batchParentKindsInTx: a parent KIND with no parent-child row in
the batch has an empty candidate set, hence an empty exogeneity set, so its
read is pure overhead, and the read is a ten-join walk under two CTEs that
dolt spends ~8 ms planning whether it returns rows or not. Most batches name
no wisp parent at all; a batch of roots names neither. Without the guard the
2-id case measured 1.9x, with it 0.94x.

expandBatchTemplate now WALKS the template instead of counting "%s": the batch
scope and the bound exogeneity ids alternate inside the union (leg 3's scope,
leg 3's NOT IN, leg 4's scope, leg 4's NOT IN), so only text order says where
each group goes. It returns an error on a ?/bound mismatch rather than handing
the engine an opaque argument-count failure. The %s budget is back to 6 from
8, re-pinned, with two new pins beside it: the ? group is exactly the bound
exogeneity ids (none for an empty set), and the mismatch is refused.

KEPT, on round-1's measurements: the NOT IN subtraction (the derived-table
JOIN measured ~30x in dolt) and the 4-level LEFT JOIN ancestor walk (WITH
RECURSIVE blew the driver read timeout).

MEASURED. n=1000 issues / 2870 deps / 333-604 blocked, embedded dolt 2.2.0,
TestBlockedStateScaleTiming, SIX interleaved origin/main(71c4cd08b)/head pairs,
medians, worst single pair in brackets. The bench now times three batch sizes
instead of one, because the per-statement and per-id costs pull opposite ways:

  metric                     main     head    ratio          bar
  full repair               49 ms    57 ms    1.16x [1.32x]  <= 1.5x  MET
  doctor count (consistent) 48 ms    57 ms    1.18x [1.32x]  <= 1.5x  MET
  write path, per CloseIssue 25 ms   26 ms    1.03x [2.59x]  <= 1.2x  MET
  batched recompute, 200 id 54 ms    69 ms    1.28x [1.57x]  <= 1.5x  MET
  batched recompute,  20 id 17 ms    22 ms    1.29x [1.50x]  (measured)
  batched recompute,   2 id 22 ms    21 ms    0.94x [1.03x]  (measured)

All four stated bars are met on medians. The worst-pair column is at or inside
this box's own noise: over the same six runs origin/main's OWN spread is 2.07x
on the full repair, 2.33x on the write path, 1.92x on the 2-id batch and 1.19x
on the 200-id batch, so a single pair's ratio is not evidence at this
resolution and the medians are what the bars are read off.

DISCLOSED, not a stated bar and not fixed here: the bench FIXTURE BUILD —
2870 AddDependency calls plus 240 CloseIssue through the store — is 75 s ->
102 s, 1.36x [1.61x]. That is the dependency-ADD write path, and the cost is
round 1's incremental seeding (AffectedByDepChangeInTx now walks up to every
reason-carrying ancestor and reseeds its whole sibling set), which is what
buys the incremental/full-repair agreement pinned by the lockstep test in the
next commit. Per-edge it is sub-millisecond; it shows up here because the
fixture writes the hierarchy of a 1000-issue store edge by edge.

GATE: go build ./... ; go vet ./internal/storage/issueops/ ; go test
./internal/storage/issueops/ (ok, includes the rewritten template and sqlmock
pins) ; BEADS_TEST_EMBEDDED_DOLT=1 go test ./internal/storage/dolt/ -run
'ParentChildCascade|RecomputeAllIsBlocked' (ok) ; gofmt -l clean. The full
enumerated gate is on the bead.

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

* test(storage): pin both sides of the subtree-walk horizon, and the incremental/full-repair lockstep (wy-3eb07b, #6506)

D2 and D3 from the round-1 supervisor ruling.

D2 — THE HORIZON IS NOW PINNED, not commented. "Inside my own subtree" is
decided by a fixed 4-level ancestor walk (subtreeWalkDepth), because a
recursive walk cost 7.5x per evaluation and blew the driver read timeout. Two
tests that differ by ONE EDGE straddle it:

  _ReasonAtTheWalkHorizon    P blocks a descendant exactly 4 pc levels down.
                             The walk reaches P, so the reason is
                             subtree-derived and the chain comes bright.
                             RED on origin/main (4 rows dark that the fix
                             brightens) — so it is not vacuous.
  _ReasonPastTheWalkHorizon  one level further. The reason reads as EXOGENOUS,
                             so the whole chain stays dark, which is
                             origin/main's own answer — and that test PASSES
                             UNCHANGED ON origin/main (verified in a temp
                             worktree at 71c4cd08b, since removed). It also
                             asserts no row of the shape appears in
                             GetReadyWork: no new dark rows AND no new visible
                             rows past the horizon, checkable rather than
                             argued. Raising the constant makes it fail and
                             name the row that changed.

Both also repair from a fully inverted plane, which is the leg that needs the
fixpoint rather than the write path's seeding. The CHANGELOG now names the
4-level horizon beside the existing limitation sentence, and the constant's own
doc names the two pins.

CAN THE HORIZON BE RAISED? Measured, and the answer is "not on this evidence".
Same bench, same box, full repair / doctor count / 20-id batch / 200-id batch:

  depth 4   57 ms /  58 ms / 21 ms /  69 ms     (shipping)
  depth 6  126 ms / 118 ms / 52 ms / 101 ms     2.2x, TWICE reproduced
  depth 8   59 ms /  74 ms / 24 ms /  68 ms     ~= depth 4, TWICE reproduced

The curve is NON-MONOTONIC: 6 falls off a cliff and 8 comes back. That is a
dolt planner artifact, not a cost model, and raising a semantics-bearing
constant on the strength of a number nobody can explain is the wrong trade —
depth 8 also makes every past-horizon shape newly bright, which is a behavior
change and not this round's business. Left at 4, with the numbers recorded for
whoever picks the knob up.

D3 — THE LOCKSTEP. _IncrementalMatchesFullRepairAcrossEdits walks one graph
through the mutations that reclassify a blocking reason WITHOUT touching the
row that carries it, and after every one asserts both the exact flags and
assertConvergedAndStable: detection counts 0 AND a full repair changes 0 rows.
An under-seeded incremental path (the AffectedByDepChange{,ForWisp}InTx
ancestor walk round 1 added) fails here as a nonzero repair over a graph the
write path just finished maintaining. The mutations: re-parent the reason's
target INTO the blocker's subtree (which is how the shape arrives — the store
refuses a blocks edge straight onto an existing own descendant, and that
refusal's reason text is what 3a5203979 corrected), close the descendant,
reopen it, re-parent it back OUT, remove the blocks edge. The
into/out-of-subtree steps are the ones that flip rows the edge does not name
(the parent's other children), which is exactly what
appendSiblingsUnderAncestorsInTx exists to seed. RED on origin/main for the
semantic values; origin/main's own incremental/full-repair agreement holds
there, so what this pins is the agreement, not the numbers.

GATE: BEADS_TEST_EMBEDDED_DOLT=1 go test ./internal/storage/dolt/ -run
'ParentChildCascade' -count=1 — 8/8 ok; gofmt -l clean; go vet clean.

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

* fix(doctor): the close-gate inventory walks the same four parent-child levels as the cascade (wy-3eb07b, #6506)

The "Parent Close Gates" check listed only DIRECT parent->child gates, so the
fix's own headline shape (a parent that blocks on its grandchild) never
appeared in the inventory. The check now joins a descendant-pairs set built
to the same four parent-child levels the cascade uses for "inside my own
subtree" (issueops subtreeWalkDepth), as plain joins over the dependency
union rather than a correlated subquery, which dolt declined to plan once
rows were present. Messages say "own-descendant"; the tests add a grandchild
gate (2 listed, the exogenous edge still not) and assert Category.

CHANGELOG cites the nested-gap follow-up, gastownhall/beads#6601.

Tests run: go build ./... 0; go vet ./cmd/bd/doctor/ 0; gofmt -l clean;
env -u BEADS_ACTOR go test ./cmd/bd/doctor/ -run 'ParentBlocksOwnChild|TruncateDetail' -count=1 PASS (3/3).

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

* ci: allowlist TestBlockedStateScaleTiming's -short skip (wy-3eb07b, #6506)

scripts/check-testing-short.sh reserves testing.Short() for runtime, stress
and large-fixture skips and keys them by file::func. The scale-timing test
added in this PR builds a 1000-issue / ~2000-edge dolt fixture and times the
blocked-state paths over it: a large-fixture skip, and PR Core runs with
-short, so it needs the entry. One line, the same shape as the
TestUOW_ConcurrentMergeOps_NoLostUpdate row from #4732.

Local: ./scripts/ci/pr-policy.sh rc 0 (check testing.Short boundaries
succeeded; the other nine legs unchanged).

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

* wy-3eb07b: build(bazel): register blocked_scale_bench_test.go in internal/storage/dolt

The rebase carried the bench test but not its BUILD.bazel entry, so the
Bazel test lane's gazelle sync and Go test equivalence steps failed while
every Go lane was green. This is CI's own bazel-sync patch for 043f9c47b9,
applied unchanged.

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

* fix(blocked): resolve explained parents through their ancestry; walk ancestors on hinted per-table members

Maintainer fixup for #6602 (adopt-pr review iteration 1, quality scorecard
760/1000, request_changes; amended at iteration 2, 906/1000, approve). It
fixes the review's two major findings, the doctor check's message and its
swallowed query failure, the stale core-builder doc, and the stale
test-comment names. At iteration 2 it also takes both nits and corrects a
CHANGELOG sentence this fixup had made false.

- Mixed-arm leak (major). The explained-parent read decides from a
  parent's own reason rows, and the fixpoint carries the recursive clause
  only for a parent with no reason row of its own. With Q blocked on an
  outside X, P a child of Q, and P blocking on its own child C, P read as
  explained and C came bright under an epic still gated by X, on the
  write path and in full repair alike. pruneExplainedByAncestryInTx now
  shrinks every read to the greatest set whose members' blocked parents
  are all members. A full-repair read is complete, so a blocked parent it
  did not return is unexplained. A batch-scoped read climbs instead,
  reading the blocked parents above the batch by id (explainedAmongInTx).
  The suggested one-level NOT EXISTS is not enough: put a second close
  gate between them (R blocked on X, pc Q -> R, Q blocks on P, pc P -> Q,
  P blocks on C) and P's blocked parent Q is in the set, so R's gate
  never reaches C.
- ancestorChainInTx (major) walked the derived UNION of both dependency
  tables that #7224 removed from isAncestorInTx, on every parent-child
  write and merge replay. It now walks reachabilityMembers, the hinted
  per-table recursive members split out of reachabilityQuery, with the
  reason filter kept in the outer SELECT. TestGraphWalkPlansHonorJoinHints
  (embedded) gains an ancestor-chain subtest that pins the lookup plan;
  the old walk fails it.
- New dolt tests: TestParentChildCascade_OwnGateUnderExogenousParent
  (write path, full repair, and X closed and reopened),
  _NestedGatesBothWays (the two-gate chain both ways, then a close of the
  children's own blocker, which re-evaluates them through a batch whose
  read covers nothing above their parents), and
  _WispGateUnderExogenousParent (a wisp gate under an issue epic, an
  issue gate under a wisp epic, then an explained wisp gate the walk must
  read by id above such a batch). Five mutants of the prune were each
  killed: no prune (the PR head), a one-level check, an over-prune, a
  scoped read treated as complete, and a scoped read that trusts every
  parent above it. The eight existing cascade tests pass under all five.
  Iteration 2 killed two more, each by its own section of the wisp test
  alone: dropping the lookup of a wisp parent from blockedParentEdgesInTx,
  and dropping explainedAmongInTx's wisp leg, which had survived all
  eleven cascade tests.
- The doctor check no longer says the children "stay in bd ready", and
  a failed or timed-out inventory query is now a warning carrying the
  error, as in validation.go's other checks, instead of an OK that reads
  as "no gates". TestCheckParentBlocksOwnChildDB_QueryFailureWarns pins
  it with a closed handle, and it fails with the old status. A warning
  does not touch doctor's overall result, and it can be suppressed.
- The core builder's doc no longer describes the spliced design, and
  three test comments name builders that exist.
- explainedAmongInTx says why it does not tolerate a missing table, as
  the file's wisp reads do: the prune runs only on a non-empty read,
  which came from the same core query over all four tables.
- The CHANGELOG entry no longer calls #6601's shape (a sub-epic gated on
  its own children under an exogenously blocked epic) a known limitation
  that keeps the children visible. The prune darkens them, as
  TestParentChildCascade_OwnGateUnderExogenousParent pins.

Left as-is, all non-gating: the refusal hint's "(bd gate)", an API string
pinned by the golden corpus; a parent-child add/remove timing in the
scale bench, whose 1000 issues cannot show the 50k shape (the plan pin
guards it); and hints for the explained-parent subtree walk and the
doctor query. The measured complexity major is runDiagnostics (50/66),
the same at base; the PR adds two lines to it.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(storage): re-pin the classic batch-apply statement count for the parent-child cascade

The B0 statement-count pins predate this PR's parent-child cascade. The
first full run of the storage tiers on the adopted head measured the
40 (classic) shape at 835 statements on both backends, against the
pinned 786 +/- 2.

All 49 extra statements are reads, seven for each of the shape's seven
distinct parent-child dep adds (its eighth repeats a pair and is a
no-op):
- appendSiblingsUnderAncestorsInTx reseeds the parent's other children:
  one ancestorChainInTx walk and four child probes, +5.
- The batched mark/unmark reads its exogeneity set first
  (batchExogeneity): the parent-kind probe and the issue-parent read, +2.

Measured by logging every statement of the classic apply on the CI base
233d151b37 (786) and on b2b93515bf (835), then diffing the two logs by
statement shape. Those seven shapes are the whole difference, each
exactly +7, and no write changed. The 356 and 712 shapes are unchanged
on both backends.

This is the deliberate re-measure and re-pin the pins' doc comment asks
for. The per-change breakdown is in pinnedEmbeddedStatementCounts.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
2026-10-08 08:31:34 +00:00

427 lines
20 KiB
Go

package issueops
import (
"errors"
"fmt"
"strings"
"github.com/steveyegge/beads/beadserrors"
"github.com/steveyegge/beads/internal/types"
)
// ErrAlreadyClaimed is returned when attempting to claim an issue that is already
// claimed by another user. The error message contains the current assignee.
var ErrAlreadyClaimed = errors.New("issue already claimed")
// ErrNotClaimable is returned when attempting to claim an issue that is not in a
// claimable state, such as closed, deferred, or already in progress without the
// same actor owning the claim.
var ErrNotClaimable = errors.New("issue not claimable")
// ClaimConflictError reports the state that refused a claim — the current
// assignee and status, read inside the same transaction that lost the
// compare-and-set. It wraps the refusal rather than replacing it, so the
// sentinel still matches, the refusal's carefully-worded prose survives
// byte-for-byte, and a caller can classify the conflict from typed fields
// instead of parsing that prose.
//
// Err is set by every implementation that returns this type; a Claimer whose
// same-transaction re-read fails returns the bare refusal instead.
type ClaimConflictError struct {
// IssueID names the issue that refused the claim.
IssueID string
// Assignee is the holder observed by the losing transaction. It is empty
// when the refusal was about the status rather than a foreign holder.
Assignee string
// Status is the status observed by the losing transaction.
Status Status
// Err is the wrapped refusal. It matches ErrAlreadyClaimed or
// ErrNotClaimable.
Err error
}
func (e *ClaimConflictError) Error() string { return e.Err.Error() }
// Unwrap makes ClaimConflictError match the refusal it carries.
func (e *ClaimConflictError) Unwrap() error { return e.Err }
// ErrUnsupported reports a capability this backend does not serve. It is an
// alias of beadserrors.ErrUnsupported — the same type, so one errors.As arm
// matches it under either name — and it is re-exported here because a caller
// holding an issueops role should not have to discover a second package to
// classify the refusal.
//
// It is declared there rather than here because the capability shell is not an
// issue concept: a memory role can go unimplemented by a backend exactly as a
// Reader can.
type ErrUnsupported = beadserrors.ErrUnsupported
// ErrAssigneeMismatch is returned by a conditional release or update whose
// ExpectedAssignee does not match the issue's current assignee (including when
// the issue is no longer assigned at all). The caller's view of the claim was
// stale; the issue is left untouched. See Releaser.Release and
// UpdateRequest.ExpectedAssignee.
var ErrAssigneeMismatch = errors.New("assignee mismatch")
// ErrNotesOverwrite is returned when an update's Patch.Notes would replace
// existing non-empty notes with different non-empty content (see
// NotesReplacement) and UpdateRequest.ForceNotesOverwrite is false. It is
// independent of the assignee fence —
// unlike ErrAlreadyClaimed it applies regardless of ExpectedAssignee — because
// there is no compare-and-set that authorizes a notes overwrite the way a
// matching ExpectedAssignee authorizes an assignee transfer. Bypass with
// ForceNotesOverwrite (`bd update --force`); preserve history instead with
// --append-notes.
var ErrNotesOverwrite = errors.New("update would replace existing notes")
// NotesReplacement reports whether proposed would replace existing non-empty
// notes with different non-empty content — the one condition the
// notes-overwrite fence refuses without ForceNotesOverwrite. An explicit
// clear (proposed "") is not a replacement: every sibling text field clears
// the same way, the blind-clobber pattern the fence exists to stop is an
// agent writing its own non-empty content over someone else's, and the
// refusal's advice (force, or append) is meaningless for a clear. The clear
// itself is guarded separately at the CLI flag layer (`--notes ""` is
// refused; `bd update --clear-notes` is the deliberate verb, GH#6021), where
// an accidental empty — a dead command substitution — cannot be told from a
// deliberate one by its bytes; that guard is not this predicate's concern.
func NotesReplacement(existing, proposed string) bool {
return existing != "" && proposed != "" && proposed != existing
}
// ErrNotOwner is returned when an actor tries to release a claim that a
// different actor holds. Releasing another actor's claim requires the force
// escape hatch (ReleaseRequest.Force, `bd unclaim --force`), reserved for
// abandoned claims — or ReleaseRequest.ExpectedAssignee, which authorizes the
// same thing by naming the holder instead of ignoring it.
//
// It is DECLARED here and re-exported by internal/storage rather than the other
// way round, which is the direction the memoryops slice settled: a Go alias
// preserves identity in both directions, so every existing storage.ErrNotOwner
// reference keeps matching this identical value, and a caller holding only the
// public role can now classify the refusal without importing an internal
// package it cannot reach. It is the ownership half of the same vocabulary
// ErrAssigneeMismatch above belongs to, which is why it is here rather than
// beside Releaser: both refusals answer "whose claim is this".
var ErrNotOwner = errors.New("issue claimed by a different actor")
// The namespace-neutral part of this vocabulary is declared by beadserrors and
// re-exported here. These are ALIASES, so they are the same values: every
// existing issueops.ErrX reference and every errors.Is site keeps matching the
// identical error, and a leaf that never imports issueops still matches it too.
//
// They live down there because none of them names an issue: a request can be
// invalid, a row can be missing and a database can be uninitialized on any
// plane. The refusals BELOW that name issue concepts stay here.
var (
// ErrNotFound is returned when a requested entity does not exist in the database.
ErrNotFound = beadserrors.ErrNotFound
// ErrValidation classifies deterministic request-validation failures.
ErrValidation = beadserrors.ErrValidation
// ErrNotInitialized is returned when the database has not been initialized
// (e.g., issue_prefix config is missing).
ErrNotInitialized = beadserrors.ErrNotInitialized
)
// ErrPrefixMismatch is returned when an issue ID does not match the configured prefix.
var ErrPrefixMismatch = errors.New("prefix mismatch")
// ErrCloseBlocked is returned by CloseIssueChecked when an issue cannot be
// closed because it is still blocked (is_blocked=1: an open blocking dependency
// or an open blocking gate). Bypass with CloseIssueOptions.Force.
var ErrCloseBlocked = errors.New("cannot close blocked issue")
// Blocker is one live blocker named by a BlockedError: a local issue id, or an
// `external:<project>:<capability>` reference, with the blocking edge's type
// when the refusal knew it.
type Blocker struct {
// ID is the blocker's issue id or its full `external:` reference.
ID string
// Type is the blocking edge's dependency type. It is empty when the
// refusal did not report it, which is the case for an `external:`
// reference named by the external-dependency guard.
Type types.DependencyType
}
// externalBlockerPrefix marks a blocker that lives in another project and is
// satisfied by a shipped capability rather than by a local close.
const externalBlockerPrefix = "external:"
// External reports whether the blocker is an `external:` reference rather than
// an issue this database holds.
func (b Blocker) External() bool { return strings.HasPrefix(b.ID, externalBlockerPrefix) }
// String spells the blocker the way a blocked-issue refusal always has: the
// bare id for a `blocks` edge or an unreported type, and "id (type)" for the
// other blocking edges. ParseBlocker is its inverse.
func (b Blocker) String() string {
if b.Type == "" || b.Type == types.DepBlocks {
return b.ID
}
return b.ID + " (" + string(b.Type) + ")"
}
// ParseBlocker reads one entry of the []string blocker list a store's IsBlocked
// reports — the spelling Blocker.String writes — back into its typed form. It
// exists for producers that hold only that string contract; a producer with the
// edges in hand builds Blocker values directly. A bare local id is a `blocks`
// edge, and an `external:` reference keeps an unreported type.
//
// The `external:` test comes first because a capability may itself end in a
// parenthesized suffix: `external:remote:pay (beta)` is a legal reference, and
// splitting it would report a truncated ID and a type the external guard never
// names.
func ParseBlocker(s string) Blocker {
if strings.HasPrefix(s, externalBlockerPrefix) {
return Blocker{ID: s}
}
if i := strings.LastIndex(s, " ("); i > 0 && strings.HasSuffix(s, ")") {
return Blocker{ID: s[:i], Type: types.DependencyType(s[i+2 : len(s)-1])}
}
return Blocker{ID: s, Type: types.DepBlocks}
}
// BlockedError reports the live blockers that refused an operation on a blocked
// issue, read by the refusing check itself. It wraps the refusal rather than
// replacing it — the ClaimConflictError arrangement — so the sentinel still
// matches and its message is byte-identical to the historical
// "<sentinel>: <id> is blocked by [<blockers>]", while a caller that reports the
// refusal elsewhere (the HTTP surface's `blockers` member) reads the typed list
// instead of parsing that prose.
//
// Err is ErrCloseBlocked for a close-policy refusal. The type is not
// close-specific: any refusal whose subject is "this issue is blocked by these"
// can carry its own sentinel.
type BlockedError struct {
// IssueID names the issue that was refused.
IssueID string
// Blockers are the live blockers, in the order the check reported them.
Blockers []Blocker
// Err is the wrapped refusal sentinel, e.g. ErrCloseBlocked.
Err error
}
// NewCloseBlockedError builds the close-policy refusal for issueID from the
// []string blocker list a store's IsBlocked reports (see ParseBlocker).
func NewCloseBlockedError(issueID string, blockers []string) *BlockedError {
parsed := make([]Blocker, 0, len(blockers))
for _, blocker := range blockers {
parsed = append(parsed, ParseBlocker(blocker))
}
return &BlockedError{IssueID: issueID, Blockers: parsed, Err: ErrCloseBlocked}
}
func (e *BlockedError) Error() string {
names := make([]string, 0, len(e.Blockers))
for _, blocker := range e.Blockers {
names = append(names, blocker.String())
}
return fmt.Sprintf("%v: %s is blocked by %v", e.Err, e.IssueID, names)
}
// Unwrap makes BlockedError match the refusal it carries.
func (e *BlockedError) Unwrap() error { return e.Err }
// ErrCloseOpenChildren is returned when an unforced close finds open
// parent-child dependents.
var ErrCloseOpenChildren = errors.New("cannot close issue with open children")
// CloseOpenChildrenError reports the issue and open-child count that refused a
// guarded close.
type CloseOpenChildrenError struct {
IssueID string
OpenChildren int
}
func (e *CloseOpenChildrenError) Error() string {
return fmt.Sprintf("cannot close %s: %d open child issue(s); close children first or use --force to override", e.IssueID, e.OpenChildren)
}
// Unwrap makes CloseOpenChildrenError match ErrCloseOpenChildren.
func (e *CloseOpenChildrenError) Unwrap() error {
return ErrCloseOpenChildren
}
// ErrAlreadyExists is returned when a create operation is given an ID that is
// already occupied. The issue and wisp tables share one ID space.
var ErrAlreadyExists = errors.New("issue already exists")
// ErrAlreadyIdentified is returned by Bootstrapper.Bootstrap when the substrate
// already carries a workspace identity. It is its own sentinel rather than
// ErrAlreadyExists because that one is about an occupied ISSUE ID in a shared
// id space, and a caller that classifies the two together would answer a
// re-init with advice about `bd update`.
var ErrAlreadyIdentified = errors.New("workspace already identified")
// AlreadyIdentifiedError reports the identity a substrate was found carrying
// when a bootstrap was refused, read inside the same transaction that would
// have written over it.
//
// It carries the pair rather than formatting it away because the two things a
// caller does next both need the values: adopting the identity needs them, and
// telling a COMPLETE identity apart from a half-written one — the state a
// bootstrap that failed partway leaves on a substrate with no transactions —
// means looking at which of the two is empty.
type AlreadyIdentifiedError struct {
// Prefix is the issue prefix found, or "" when the substrate carried none.
Prefix string
// ProjectID is the project identity found, or "" when the substrate
// carried none.
ProjectID string
}
func (e *AlreadyIdentifiedError) Error() string {
switch {
case e.Prefix != "" && e.ProjectID != "":
return fmt.Sprintf("workspace already identified as prefix %q, project %s", e.Prefix, e.ProjectID)
case e.Prefix != "":
return fmt.Sprintf("workspace already identified as prefix %q with no project id", e.Prefix)
default:
return fmt.Sprintf("workspace already identified as project %s with no issue prefix", e.ProjectID)
}
}
// Unwrap makes AlreadyIdentifiedError match ErrAlreadyIdentified.
func (e *AlreadyIdentifiedError) Unwrap() error { return ErrAlreadyIdentified }
// ErrVersionMismatch is returned by a *Checked op given an ExpectedVersion that
// no longer matches the row's current version (row_lock) — an optimistic
// concurrency failure. Callers errors.Is it to distinguish a lost-update
// precondition from other errors.
var ErrVersionMismatch = errors.New("version mismatch")
// VersionMismatchError reports the expected and current row versions that
// refused a guarded write, read inside the same transaction the guard
// checked. It wraps ErrVersionMismatch rather than replacing it — the
// ClaimConflictError arrangement — so errors.Is(err, ErrVersionMismatch)
// still matches and the message stays byte-identical to the historical
// "version mismatch: expected %d, got %d", while a caller that reports the
// refusal elsewhere (a command's --json envelope, the HTTP surface) reads the
// typed pair instead of parsing that prose.
//
// Both fields are the opaque row_lock token: compared for equality only,
// carrying no order.
type VersionMismatchError struct {
// Expected is the version the caller required.
Expected int64
// Current is the version the guard found instead, read inside the same
// transaction as the check — never a post-rollback re-read.
Current int64
}
func (e *VersionMismatchError) Error() string {
return fmt.Sprintf("%v: expected %d, got %d", ErrVersionMismatch, e.Expected, e.Current)
}
// Unwrap makes VersionMismatchError match ErrVersionMismatch.
func (e *VersionMismatchError) Unwrap() error { return ErrVersionMismatch }
// ErrStatusMismatch is returned by UpdateIssueChecked given an ExpectedStatus
// that no longer matches the issue's current status. The caller's view of the
// issue was stale; the issue is left untouched. The assignee analog is
// ErrAssigneeMismatch, shared with UnclaimIssueIfAssignee.
var ErrStatusMismatch = errors.New("status mismatch")
// ErrSelfDependency is returned when a dependency edge would point an issue at
// itself. It is the static prefix of the formatted message, wrapped so callers
// can errors.Is it while the human-readable text is preserved byte-for-byte.
var ErrSelfDependency = errors.New("cannot add self-dependency")
// ErrDependencyCycle is returned when adding a dependency edge would introduce a
// scheduling cycle. It is scoped to the dependency-add family — the single and
// bulk add paths (add/AddDependencies) and the dolt cross-tier check — so
// callers can errors.Is any dependency-add cycle rejection. The whole-graph
// construction paths (ApplyIssueGraph/ApplyWispGraph) are a separate family and
// deliberately do not carry this sentinel yet.
var ErrDependencyCycle = errors.New("adding dependency would create a cycle")
// DependencyTypeConflictError is returned when an edge already exists between
// the same pair with a DIFFERENT type. Its message is byte-identical to the
// embedded issueops path (internal/storage/issueops/dependencies.go) so
// `bd dep add` surfaces the same user-facing retype error on the domain/db seam
// as on the embedded store. It is a typed error so the use-case can pass it
// through unwrapped instead of burying it under an "add dep: insert:" prefix.
type DependencyTypeConflictError struct {
IssueID string
DependsOnID string
ExistingType string
RequestedType string
}
func (e *DependencyTypeConflictError) Error() string {
return fmt.Sprintf("dependency %s -> %s already exists with type %q (requested %q); remove it first with 'bd dep remove' then re-add",
e.IssueID, e.DependsOnID, e.ExistingType, e.RequestedType)
}
// ErrDependencySourceNotFound is returned when an edge's SOURCE names no row
// this database holds. An edge follows its source, so there is no plane for it
// to land in and no event stream to record it on.
var ErrDependencySourceNotFound = errors.New("dependency source not found")
// ErrDependencyTargetNotFound is returned when an edge's TARGET names no row
// this database holds AND is one whose absence this database can SEE: an id in
// its own namespace, carrying no "external:" marker. An "external:" reference
// and an id belonging to another repository are accepted as external targets,
// so neither raises this.
//
// It is a separate sentinel from the source's because the two are separate
// answers. A ghost source is always a bad id; a target is only refused when
// this database is the one that would have held it, which is a narrower claim
// and the one a caller has to reason about before retrying.
var ErrDependencyTargetNotFound = errors.New("dependency target not found")
// DependencyEndpointNotFoundError reports which endpoint of a refused edge was
// absent, read inside the transaction that refused it. It wraps the refusal
// rather than replacing it, so the sentinel still matches, the message stays
// what it was, and a caller classifies the refusal from typed fields instead of
// parsing prose — the ClaimConflictError arrangement, applied to the graph.
//
// It carries the whole edge rather than only the missing id because the request
// is all-or-nothing: the refusal is the REQUEST's, so a caller reporting which
// of its own edges was rejected has to find it by both endpoints.
type DependencyEndpointNotFoundError struct {
// IssueID and DependsOnID name the refused edge.
IssueID string
DependsOnID string
// MissingID is the endpoint that named no row: IssueID for a ghost source,
// DependsOnID for a missing target.
MissingID string
// Err is the wrapped refusal. It matches ErrDependencySourceNotFound or
// ErrDependencyTargetNotFound.
Err error
}
func (e *DependencyEndpointNotFoundError) Error() string {
return fmt.Sprintf("issue %s not found", e.MissingID)
}
// Unwrap makes DependencyEndpointNotFoundError match the refusal it carries.
func (e *DependencyEndpointNotFoundError) Unwrap() error { return e.Err }
// DependencyHierarchyConflictError is returned when a blocking dependency
// would gate an issue on one of its own ancestors or descendants. Neither
// shape is how the hierarchy expresses "wait for what is under me".
type DependencyHierarchyConflictError struct {
IssueID string
BlockerID string
BlockerIsAncestor bool
}
// Error states the DESCENDANT refusal as a modeling refusal, not a
// consequence of the cascade.
//
// It used to read "blocked status cascades to descendants, so <blocker> would
// inherit the block and never close". That was true until
// gastownhall/beads#6506: a parent-child edge now propagates only the parent's
// EXOGENOUS blockedness, so a parent that blocks on something in its own
// subtree no longer darkens it, and the sentence described a deadlock that no
// longer happens. The refusal itself stands — a blocks edge is not the way to
// say "I close after my children" — so the reason has to say what is.
func (e *DependencyHierarchyConflictError) Error() string {
if e.BlockerIsAncestor {
return fmt.Sprintf("%s cannot be blocked by its ancestor %s: %s cannot close until its descendants finish, so the gate would never clear",
e.IssueID, e.BlockerID, e.BlockerID)
}
return fmt.Sprintf("%s cannot be blocked by its descendant %s: waiting on your own subtree is a close gate, not a blocks edge — use a waits-for gate over the children (bd gate)",
e.IssueID, e.BlockerID)
}