beads/internal/storage/issueops/dependencies.go
Julian Knutsen 34b9a132f8
feat(storage): events + dependents reads, batched blocked, public claim surface (#4926)
* feat(storage): engine reads — EventsSince, GetDependentRecords, EventClaimed

`bd activity`/`bd show` render event history, and the library's own callers
need a durable, resumable feed of what changed — but the storage surface had
only the time-granular GetAllEventsSince, no keyset cursor, and no raw
target-keyed dependents read. Add both as additive extension interfaces plus
backend methods; no wire, schema, CLI, or existing-signature changes. Each new
read delegates its SQL to the shared issueops helpers the backends already use.

- Extract the raw "claimed" event literal into a typed EventClaimed constant
  (types) and use it at the single write site (issueops/claim.go). The on-disk
  value is byte-identical.
- EventsSince(cursor{created_at,id}, limit) — a durable-only keyset read over
  the events table, for a change feed that pages forward without dropping or
  duplicating same-second ties. New EventQueryStore extension interface +
  EventCursor, composed into DoltStorage and implemented on the Dolt backends.
- GetDependentRecords(targetID, depType, limit, afterID) on
  DependencyQueryStore — a raw target-keyed dependents read (the inbound edges)
  that returns edges from dangling/cross-project/wisp sources rather than
  dropping them, so `bd dep list`-style dependents views see the whole set.

Real-Dolt tests cover direction correctness, type filter, keyset paging,
same-second id tie-break, cursor exclusivity, durable-only scope, and the
claimed-constant write path.

(cherry picked from commit 35ae4d186047d99bef6d492132f5767ef2db5d7d)

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

* fix(storage): make EventsSince sargable + add a per-bead scope

The EventsSince cursor predicate `(created_at > ?) OR (created_at = ? AND id > ?)`
full-scans on Dolt (EXPLAIN: Filter over a bare Table + TopN). Rewrite it to the
logically-equivalent, SARGABLE form

	created_at >= ? AND ((created_at > ?) OR (id > ?))

The redundant `created_at >= ?` lower bound flips the plan to
IndexedTableAccess(events) on [events.created_at] (verified by a new
EXPLAIN FORMAT=TREE regression test). The composite (created_at, id) row-value
form is deliberately NOT used: the events table has only single-column
idx_events_created_at (no composite index) on every backend, so the >= lower
bound is the seeking form; the shared issueops query serves each backend.

Also give EventsSince an optional issueID filter ("" = all) implemented off the
same keyset with `issue_id = ?`, so `bd show`'s per-bead event history is one
scoped read of the same primitive rather than a second one. The signature is
changed while unmerged across the interface + dolt/embeddeddolt backends.

Coverage/docs: dolt suite gains issue-filter, limit-clamp (default 100 / cap
500), and the EXPLAIN sargability guard; embeddeddolt gains a mirrored feed
test; the interface doc names idx_events_created_at and states the
commit-visibility-lag caveat (a resuming consumer overlaps a ~45s slack window
and de-duplicates by id).

(cherry picked from commit 3b7903290fad76e15ece171dcf6bdfd5f0f584b8)

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

* test(storage): single-source the EventsSince sargability guard from production SQL

The EXPLAIN sargability guard asserted a hand-copied literal of the EventsSince
query, so it could pass while the production predicate silently drifted.
Single-source it: export issueops.EventsSinceQuery(issueID, limit) — the exact
SQL EventsSinceInTx runs — and have the durable-events plan guard EXPLAIN that
string (placeholders literalized) instead of a copy. A change to the SARGABLE
predicate now breaks the guard.

Adds a literalizeParams test helper that binds ? placeholders to literals in
order and panics on arity drift, so a drifted placeholder count fails loudly
rather than EXPLAINing malformed SQL.

(cherry picked from commit dda19e737ac17ae4387c6abc4a1acca287b85494)

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

* fix(storage): dependents reads — total id cursor, sargable target, + CountDependentRecords

Three coupled fixes to the target-keyed dependents read behind `bd dep list`'s
dependents views and the library's own callers:

TOTAL KEYSET. The old cursor paged on source issue_id, which is not a total key
for a fixed target: a source can appear across the durable and wisp dependency
tables, so paging on it could drop or duplicate rows (the Type tie-break was
dead code and the "issue_id is unique" comment was false). Cursor instead on the
dependency row's own primary id (depid.New(issue_id, target), a UUIDv5 that is
stable and globally unique across both tables): ORDER BY id ASC, afterID = last
row's id. types.Dependency gains an additive ID field, scanned by a dedicated
scanDependentRow (the shared scanDependencyRow is left untouched so no
source-keyed read has to select id). The two per-table pages merge by id and
truncate — total, no drop, no dup, proven by a page-size-1 walk across a
boundary that spans both tables (durable + wisp sources).

SARGABLE TARGET. Replace COALESCE(target...)=? (an expression no index can
match) with an explicit per-column OR, depTargetEqualsOr. On an index-merging
planner it plans as a BitmapOr index-merge over the three idx_dep_*_target
indexes where COALESCE was a full scan; on Dolt it is at worst no worse than
COALESCE, and the type-filtered path seeks the (type, target) composite on both.

CountDependentRecords(ctx, targetID, depType): the same sargable predicate,
COUNT only, summed across both tables — callers need a true total membership
count without paging to exhaustion. Implemented once in issueops and wired onto
the DependencyQueryStore interface + the dolt/embeddeddolt backends.

Coverage: dolt + embeddeddolt tests for both reads (two-table span, type filter,
keyset boundary, limit clamp default 100). Method docs name the cursor key and
the two-table raw-read / policy-at-hydration contract.

(cherry picked from commit 16db364d94f8525b9800483dc5ddcdccf94593f8)

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

* fix(storage): de-dup cross-table depid collisions in dependents reads

depid.New keys a dependency row's id on (issue_id, target) and omits the table,
so the SAME edge present in BOTH dependencies and wisp_dependencies — a wisp
promoted to durable, or two Dolt clones merged — carries one id in both tables.

GetDependentRecordsInTx appended both per-table pages and sorted by id, so a
colliding edge produced a duplicate id in a merged page (and, at a page
boundary, a dropped row on the next `id > afterID`). CountDependentRecordsInTx
summed two raw COUNT(*)s, over-counting the collision beyond the distinct keyset
row count.

De-dup the paged read by id, iterating durable first and keeping the durable
(authoritative, non-ephemeral) row. Make the count agree with that de-dup:
durable rows plus wisp rows whose depid is not already a durable row for the same
target/type (an uncorrelated, bounded NOT IN over the sargable per-column OR
target predicate), so the total is distinct-by-id.

Adds a dolt regression test that seeds the same edge in both tables (FK checks
relaxed to reproduce the post-merge state) and asserts one row per id in pages,
Count == distinct total (3, not the sum 4), and stable keyset paging across the
collision. Fails before this change (id appears twice), passes after.

(cherry picked from commit c6825f8513cd38967fb73856253bd99a5eb65fc2)

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

* feat(storage): batched target-keyed dependents read (GetDependentRecordsForIssues)

Adds GetDependentRecordsForIssues(ctx, targetIDs) → map[targetID][]*Dependency:
for a SET of target ids in ONE batched read, each id's INCOMING dependency rows
(its dependents), spanning BOTH the durable and wisp dependency tables, ALL dep
types (the caller filters), de-duped by row id. It is the target-keyed mirror of
the source-keyed GetDependencyRecordsForIssues — the whole-page read that lets
`bd dep list`-style dependents views and the library's own callers render every
id's inbound blocking edges without a per-id fan-out, and unlike
GetBlockingInfoForIssues's blocksMap it keeps the full type set (waits-for /
conditional-blocks are not dropped) and each row's real dep_type.

Cross-table de-dup matches GetDependentRecordsInTx: a wisp promoted to durable
carries one depid in both tables, so the durable table is scanned first and a
repeat id is skipped. The target is matched by the coalesced target expression
(depTargetIn), the same predicate the batched blocks/counts reads use.

Wired through issueops + the DependencyQueryStore interface + the dolt /
embeddeddolt backends. (The public-root re-export via beads.DependentQuerier
lands with the narrow public query-interface work.)

Tests: dolt + embeddeddolt batched-read regressions (multi-target keying, both
tables, full type set incl conditional-blocks/waits-for, decoy exclusion, absent
leaf, empty input).

(cherry picked from commit 1f69cedf282471d474ac5b1be633c7a9b18990c8)

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

* feat(storage): batch transitive is_blocked read on DependencyQueryStore

`bd`'s discovery/ready-list views and the library's own callers need the
denormalized transitive is_blocked value for a PAGE of up to ~200 issues; the
surface only had the single IsBlocked(ctx, id), so a page cost N per-row calls.
Add IsBlockedBatch(ctx, ids) (map[string]bool) to the DependencyQueryStore
interface and implement it once in issueops.IsBlockedBatchInTx: a batched
SELECT id, is_blocked FROM {issues,wisps} WHERE id IN (...) at queryBatchSize=200
— the same denormalized column IsBlocked reads, NOT a recompute — so it returns
the identical transitive value per id, reflecting inherited/ancestor blockedness
(a child of a blocked parent is blocked with no direct blocking edge). ids
present in neither table are absent from the map; cross-table dups prefer the
wisps row, matching loadStatusByIDInTx and the search wisp-merge.

Wired onto the dolt and embeddeddolt backends via the same pattern as
CountDependentRecords (each delegates through its read tx).

Test: a dolt parity suite seeding a direct blocker, an inherited parent-child
block (transitive is_blocked with an EMPTY direct-blocker set), and an unblocked
control, asserting IsBlockedBatch agrees with per-row IsBlocked for every id and
that a missing id is absent from the map.

(cherry picked from commit 1cd441231e2c5a2b45064db01a03bb06de9009b9)

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

* fix(issueops): IsBlockedBatch issues-wins on cross-table id collision, matching IsBlocked

IsBlockedInTx (per-row) scans issues→wisps and breaks on the first table that
has the id, so ISSUES wins the shared denormalized is_blocked field on a
cross-table (issues vs wisps) id collision. IsBlockedBatchInTx preferred the
wisps row, so the two reads disagreed on the same stored flag for an id present
in BOTH tables.

Make the batch keep the first-seen (issues) value and skip any later (wisps)
duplicate, mirroring the single read's precedence exactly. Both the dolt and
embeddeddolt backends delegate to this shared function, so they stay consistent.

Add a dolt regression seeding the same id in issues (is_blocked=1) and wisps
(is_blocked=0) and asserting IsBlocked(id) == IsBlockedBatch([id])[id] == the
issues value. Verified it fails before the fix (true vs false).

(cherry picked from commit 7dbd4f849d589acb15f8168532fcf8874aa87c99)

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

* test(embeddeddolt): IsBlockedBatch parity regression on the embedded backend

Mirror the dolt IsBlockedBatch coverage on the embedded Dolt backend: assert the
batched transitive is_blocked read agrees with per-row IsBlocked for every id and
reflects an inherited parent-child block (is_blocked true with an empty
direct-blocker set). Complements the already-present embedded keyset regression.

(cherry picked from commit 414e7eaf8de43eb1786088c2851c18763f6724ba)

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

* feat(beads): re-export claim surface, error taxonomy, and query interfaces on public root

Public root-package surface for the claim/error/query reads consumers reach by
type-assertion. Pure re-export + a string-coupled conflict shim; no engine
behavior changes.

- IssueClaimer interface (ClaimIssue/ClaimReadyIssue, which live on the
  storage.BulkIssueStore extension, not the base Storage) + AsIssueClaimer
  type-assertion helper. Callers assert once at startup and fail loud, per the
  decorator note.
- Re-export ErrCircuitOpen (storage/dolt) as an aliased root sentinel so
  errors.Is works across the boundary (the claim sentinels ErrAlreadyClaimed /
  ErrNotClaimable are already re-exported with the other sentinels); a
  wrap-preservation test pins this against errors wrapped the way the engine
  wraps them.
- Typed conflict detail: the conditional-UPDATE claim path returns no typed
  result on conflict — the current assignee/status remains embedded in the
  error string. Rather than change that internal signature, expose
  ClaimConflict + ParseClaimConflict (with its own test) to recover it.
- Re-export DependencyQueryStore, EventQueryStore, EventCursor aliases and the
  EventClaimed constant so consumers reach the new reads by type-assertion.

(cherry picked from commit 70f443ad941117a74f3143f8570f91a0f721ece4)

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

* fix(beads): derive claim-conflict markers from a storage source of truth

ParseClaimConflict hardcoded the message literals "issue already claimed by "
and "issue not claimable: status ", coupling the root parser to the engine's
fmt.Errorf format three layers away with nothing to catch drift.

- Export the two format fragments next to the sentinels: storage.ClaimedByFragment
  (" by ") and storage.NotClaimableStatusFragment (": status "). issueops/claim.go
  now wraps with "%w%s%s" using them (on-disk/message bytes unchanged), and
  ParseClaimConflict reconstructs its markers as ErrAlreadyClaimed.Error()+fragment
  rather than hardcoding — producer and parser can no longer drift independently.
- Harden tailAfter: recover the assignee/status only as the trailing run; if the
  tail still contains a known marker (an appended wrap corrupted it) return "".
  Documents the repo convention that claim-error wraps PREPEND context.
- Producer-tied tripwires: a dolt-suite round-trip (real ClaimIssue → both
  conflict branches, recovered via the storage fragments) and a root external
  round-trip (real Dolt store via beads.Open → AsIssueClaimer → ParseClaimConflict
  recovers assignee/status). The latter also exercises AsIssueClaimer against a
  live Storage.

(cherry picked from commit aced93f3d93c3fb779702df0549fab58369af997)

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

* fix(beads): bound the claim-conflict token so an appended wrap can't leak garbage

tailAfter took the entire trailing run after the fragment, guarding only against
a further embedded full marker. A plain appended wrap — fmt.Errorf("%w (ctx)",
claimErr) — sailed past that guard and returned "alice (ctx)" as the assignee.

Bound the token to a single whitespace-free run: a status never contains
whitespace and an assignee is a whitespace-free actor id by convention, so if the
tail carries trailing content (whitespace or an appended "(...)" wrap) we return
"" — the documented best-effort empty-field outcome, with ParseClaimConflict
still reporting ok=true on the errors.Is match. A prepended wrap (the repo
convention) and a clean conflict are unaffected.

Tests: a direct tailAfter table (clean, prepended, appended-paren, appended-space,
absent, empty) and a ParseClaimConflict appended-wrap case asserting empty field
with ok=true.

(cherry picked from commit 181f47c7b7b4bb397c5f16992d1e33b75982eb04)

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

* refactor(beads): narrow public query interfaces + claim-surface drift guards

Public-surface hardening for the library's consumers, done while unmerged
(cheap now, expensive later).

Stop aliasing whole internal engine interfaces on the root. Replace the
`DependencyQueryStore = storage.DependencyQueryStore` / `EventQueryStore =
storage.EventQueryStore` aliases with NARROW, hand-declared root interfaces that
expose exactly what consumers use:
  - EventQuerier { EventsSince(...) }
  - DependentQuerier { GetDependentRecords(...); CountDependentRecords(...) }
plus AsEventQuerier / AsDependentQuerier helpers mirroring AsIssueClaimer. Every
As* helper now first tries the direct assertion, then storage.UnwrapStore, so a
HookFiringStore-decorated store keeps its capability (AsIssueClaimer gains the
same unwrap; previously it would return false for a decorated store).

Drift guards: compile-time assertions tie each narrow interface to the full
engine interface storage.DoltStorage (in beads.go) AND to both concrete stores —
*dolt.DoltStore and *embeddeddolt.EmbeddedDoltStore (in tests) — so a signature
change to the claim/event/dependents surface breaks the build instead of
silently making As* return false. A live-Dolt test exercises AsEventQuerier /
AsDependentQuerier and their methods end to end.

(cherry picked from commit ddf7b2ab8a2fa41e36f13ccf701983d0bcd01faa)

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

* refactor(beads): drop the dead UnwrapStore fallback from the As* accessors

The storage.UnwrapStore fallback in AsIssueClaimer/AsEventQuerier/
AsDependentQuerier was provably unreachable. ClaimIssue/ClaimReadyIssue,
EventsSince, and the dependents reads all live on the engine interface
storage.DoltStorage (via BulkIssueStore / EventQueryStore /
DependencyQueryStore), and the compile-time drift guards prove
storage.DoltStorage satisfies each narrow surface. So whenever the fallback's
`s.(storage.DoltStorage)` succeeds, `s` already satisfies the narrow surface and
the leading direct assertion has already returned — branch 2 can only run when
branch 1 failed, and branch 1 failing implies s is not a DoltStorage, so branch 2
fails too. The only decorator, HookFiringStore, embeds storage.DoltStorage and
overrides none of these methods, so it forwards them by promotion and resolves on
the direct assertion.

Reduce the three accessors to a single direct type-assertion and document the
decorator contract (a decorator MUST embed storage.DoltStorage — unlike the
cmd/bd optional interfaces such as StoreLocator/BackupStore, which are not part
of DoltStorage and so genuinely need UnwrapStore, which is unchanged and still
used there). Adds a test that a HookFiringStore-decorated live store resolves
through all three accessors — the guard that would catch a future decorator that
stops forwarding.

(cherry picked from commit 0d9d0500edd3c165f101bbb590dcea7147f3530b)

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

* feat(beads): re-export the batch transitive-blocked surface on the public root

Add BlockedQuerier (IsBlocked + IsBlockedBatch) and AsBlockedQuerier to the public
beads package, following the established narrow-interface + As* accessor style
(EventQuerier/DependentQuerier): a hand-declared root interface exposing only the
transitive-blocked reads consumers use, reachable via a single direct type
assertion, with a compile-time drift guard (var _ BlockedQuerier =
(storage.DoltStorage)(nil)) so a signature change on the engine breaks the build
here instead of silently making the accessor return false.

The (created_at, id) keyset needs no new re-export: it is additive fields on the
already-re-exported beads.IssueFilter, honored by the already-exported
Storage.SearchIssues / SearchIssuesWithCounts.

query_interfaces tests gain the concrete-store conformance assertions (server +
embedded Dolt), a live-Dolt exercise of AsBlockedQuerier proving IsBlockedBatch
agrees with per-row IsBlocked through the public surface, and the decorator-
contract check that AsBlockedQuerier resolves through a HookFiringStore.

(cherry picked from commit e8b87b6acf601bc2b323d92fbe863c4be7a99386)

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

* feat(beads): re-export GetDependentRecordsForIssues on the public DependentQuerier

Surface the batched target-keyed dependents read (GetDependentRecordsForIssues,
landed at the storage layer earlier in the dependents-reads work) on the public
root DependentQuerier interface, so a consumer reaching the dependents surface
via AsDependentQuerier can fetch a whole page of inbound edges for a SET of
target ids in one call — the batched mirror of GetDependencyRecordsForIssues —
without a per-id fan-out. A live-Dolt query_interfaces assertion exercises it
through the public surface.

(cherry picked from commit 1f69cedf282471d474ac5b1be633c7a9b18990c8)

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

* feat(storage): transactional snapshot reads on storage.Transaction

Composite views (bd show-style assemblies of counts, relations, comments, and
history) previously issued each read as its own store call with no shared
snapshot, so related numbers could disagree. Widen storage.Transaction with
the read subset those views need — CountIssuesByGroup, GetIssueCommentsPage,
GetDependentRecords/GetDependentRecordsForIssues/CountDependentRecords,
IsBlocked/IsBlockedBatch, EventsSince — so a caller can assemble the whole
view inside one transaction. Pure surface addition: every method delegates to
the existing InTx implementation; no new SQL, no semantics changes.

On the server backend the transaction spans two sessions (durable + clone-
local). Single-tier reads route by wispness and see this transaction's own
uncommitted writes on both tiers (comments page, blocked checks — including
mixed batches via tier partitioning). Reads that union both tables in one
query (dependents family, grouped counts) run on the durable session and see
uncommitted durable writes plus committed clone-local state; that limitation
is documented per method on the interface and asserted per backend in the
tests. The embedded backend is single-handle and fully read-your-writes.

Conformance adds a snapshot test that mutates inside the transaction and
asserts exact deltas across all the new reads (a non-transactional delegation
fails it), a read-your-writes test covering every method, and wisp-bearing
fixtures; the server backend adds a clone-local-tier read-your-writes test
pinning both the routed reads and the documented spanning-read behavior.

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

* fix(issueops): drop depTargetEqualsOr's dead alias parameter

Every caller on this branch passes "" — the aliased form's only consumer
lived in a backend package that does not exist here — so golangci-lint's
unparam check rejects the parameter. Inline the bare-column form.

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

* fix(storage): wrap ErrAlreadyClaimed for open foreign-assignee; split tx conformance tests

Maintainer review fixes for PR #4926 (iteration 1).

Contract (major): issueops.ClaimIssueInTx's open-but-assigned refusal branch
returned a plain error, so the public IssueClaimer contract (wrapped conflict
sentinels, classified by errors.Is / ParseClaimConflict) was false for the
common "open issue pre-assigned to another actor" case. Wrap
storage.ErrAlreadyClaimed while preserving the holder-focused wording, matching
the already-correct domain-stack twin. Adds a conformance test
(ClaimOpenForeignAssignee) and a ParseClaimConflict subtest for the wrapped
open-assigned form.

Complexity (major): split testTransactionSnapshotReads and
testTransactionReadYourWrites into named read + assertion helpers
(readSnapView/assertSnapBaseline/assertSnapDelta and
seedReadYourWritesGraph/assertInTxDependentReads/assertInTxCountsAndEvents) with
equivalent coverage, dropping the worst changed function out of the major
cyclomatic/cognitive band (39/73 -> 11/17 and 23/38 -> 4/5).

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

* fix(issueops): extract per-table read to cut IsBlockedBatchInTx complexity

Review fix for #4926. IsBlockedBatchInTx inlined the whole two-table batched
scan (gocognit 29, gocyclo 12), which the quality scorecard flagged as a major
readability finding. Extract the per-table batched read into
readIsBlockedIntoFromTable, mirroring the sibling
GetDependentRecordsForIssuesInTx / getDependentRecordsIntoFromTable split, so the
outer function only dispatches the issues+wisps read and nesting resets at the
function boundary.

Behavior-preserving: the issues-win cross-table de-dup and the optional-wisps
table-not-exist skip are unchanged -- same helper-wraps / outer-classifies idiom
as the sibling, and isTableNotExistError unwraps the %w wrap. The embedded
TestIsBlockedBatchEmbedded parity test still passes against a real Dolt backend.
gocognit 29 -> helper 15; gocyclo 12 -> 6.

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

---------

Co-authored-by: Test User <test@test.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: CI Bot <ci@beads.test>
2026-07-22 07:41:47 -07:00

1245 lines
47 KiB
Go

package issueops
import (
"context"
"database/sql"
"errors"
"fmt"
"strings"
"github.com/steveyegge/beads/internal/storage/depid"
"github.com/steveyegge/beads/internal/storage/domain"
"github.com/steveyegge/beads/internal/storage/sqlbuild"
"github.com/steveyegge/beads/internal/types"
)
type DepTargetKind int
const (
DepTargetIssue DepTargetKind = iota
DepTargetWisp
DepTargetExternal
)
func (k DepTargetKind) Column() string {
switch k {
case DepTargetWisp:
return "depends_on_wisp_id"
case DepTargetExternal:
return "depends_on_external"
default:
return "depends_on_issue_id"
}
}
// DepTargetExpr is the SQL expression that resolves a dependency row's target
// id from its three typed columns. Use this in SELECT projections (aliased as
// depends_on_id) and in WHERE clauses when the caller doesn't know the target
// kind ahead of time.
const DepTargetExpr = sqlbuild.DepTargetExpr
func depTargetExpr(alias string) string {
if alias == "" {
return DepTargetExpr
}
return fmt.Sprintf("COALESCE(%s.depends_on_issue_id, %s.depends_on_wisp_id, %s.depends_on_external)", alias, alias, alias)
}
func depTargetEquals(alias string) string {
return depTargetExpr(alias) + " = ?"
}
// depTargetEqualsOr returns a SARGABLE target-equality predicate as an explicit
// per-column OR — `(depends_on_issue_id = ? OR depends_on_wisp_id = ? OR
// depends_on_external = ?)` — binding the target id once per typed column (three
// args, in that column order). Unlike depTargetEquals's COALESCE wrapper (which
// wraps the columns in an expression no index can match), each disjunct is a
// bare indexed column.
//
// On an index-merging planner (e.g. Postgres) this plans as a BitmapOr
// index-merge over idx_dep_{issue,wisp,external}_target (a Bitmap Heap Scan,
// cost ~36 on a 5k-row table) where the COALESCE form is a Seq Scan (cost
// ~104). On Dolt
// (go-mysql-server) the optimizer does not index-merge an OR of distinct columns,
// so the un-ordered COUNT still scans, but the COALESCE form never had any index
// path either; the type-filtered path seeks the (type, target) composite on both.
// Use it for target-keyed reads of a single fixed target.
func depTargetEqualsOr() string {
return "(depends_on_issue_id = ? OR depends_on_wisp_id = ? OR depends_on_external = ?)"
}
func depTargetIn(alias, placeholders string) string {
return depTargetExpr(alias) + " IN (" + placeholders + ")"
}
func ClassifyDepTarget(ctx context.Context, tx *sql.Tx, dep *types.Dependency, isCrossPrefix bool) DepTargetKind {
if isCrossPrefix || strings.HasPrefix(dep.DependsOnID, "external:") {
return DepTargetExternal
}
if IsActiveWispInTx(ctx, tx, dep.DependsOnID) {
return DepTargetWisp
}
return DepTargetIssue
}
// AddDependencyOpts configures AddDependencyInTx behavior.
// When fields are left empty, AddDependencyInTx performs wisp routing
// automatically via IsActiveWispInTx. Callers that have already determined
// routing (e.g., DoltStore with its pre-tx wisp cache) can set fields
// explicitly to skip the redundant DB check.
type AddDependencyOpts struct {
// SourceTable is the table to validate the source issue exists in.
// Auto-detected via wisp routing if empty.
SourceTable string
// TargetTable is the table to validate the target issue exists in.
// Auto-detected via wisp routing if empty. Ignored when target validation is skipped.
TargetTable string
// WriteTable is the dependency table to insert/update/check existing deps in.
// Auto-detected from source wisp routing if empty.
WriteTable string
// DepTables are the tables to scan for cycle detection. Defaults to both
// dependency tables; edge storage is source-routed, so same-class endpoints
// can still have mixed-table interior paths.
DepTables []string
// IsCrossPrefix is true when source and target have different prefixes,
// meaning the target lives in another rig's database.
IsCrossPrefix bool
// SkipCycleCheck skips the recursive pre-insert cycle check for callers
// that intentionally trade validation cost for bulk graph wiring speed.
SkipCycleCheck bool
TargetKind *DepTargetKind
// PrecheckedTarget, when non-nil, replaces the in-tx target read: the
// target is known to exist with this type and status. Callers that set
// it must also set TargetKind, since target classification otherwise
// queries tx too.
PrecheckedTarget *DepTargetPrecheck
// EmitEvent records a dependency_added event on the source's event table
// for a genuine new edge. Only the explicit dependency verbs (bd dep add /
// bd link and their bulk twin) set it; create-with-deps and structural
// callers leave it unset so an implicit parent-child / --deps / waits-for
// edge produces no event. This mirrors the proxied repository's
// DepInsertOpts.EmitEvent gate so both backends record identical history.
EmitEvent bool
}
// DepTargetPrecheck carries a target-issue row the caller has already read
// from the transaction that can see it. Dolt server mode splits one logical
// transaction across two SQL sessions (versioned tables vs dolt-ignored wisp
// tables); when the dependency write table lives on one session and the
// target issue on the other, a target read on tx misses rows created earlier
// in the same logical transaction. The caller reads the target on its own
// session and passes the row here; existence validation, cross-type blocking
// validation, and the direct is_blocked mark then use these values instead
// of querying the target table on tx.
type DepTargetPrecheck struct {
IssueType string
Status string
}
// AddDependencyInTx validates and inserts a dependency within an existing
// transaction. It handles:
// - Wisp routing (auto-detected or caller-provided)
// - Source/target existence validation
// - Hierarchy deadlock validation for blocking deps (GH#1495, bd-wg7ve)
// - Cycle detection via recursive CTE across both dependency tables
// - Idempotent same-type updates (metadata only)
// - Type conflict detection
//
// The caller is responsible for transaction lifecycle, dolt commits, and
// any cache invalidation.
//
// It returns whether a dependency_added event was actually written — true only
// on the genuine new-edge path with opts.EmitEvent set, false for an idempotent
// same-type re-add or a silent structural add. Callers that stage tables for a
// Dolt commit stage the events table only when an event row exists, so a
// no-event add cannot sweep unrelated pending rows into the commit (GH#2455).
func AddDependencyInTx(ctx context.Context, tx *sql.Tx, dep *types.Dependency, actor string, opts AddDependencyOpts) (bool, error) {
// Auto-detect source routing if not provided.
sourceTable := opts.SourceTable
writeTable := opts.WriteTable
if sourceTable == "" || writeTable == "" {
sourceIsWisp := IsActiveWispInTx(ctx, tx, dep.IssueID)
st, _, _, dt := WispTableRouting(sourceIsWisp)
if sourceTable == "" {
sourceTable = st
}
if writeTable == "" {
writeTable = dt
}
}
// Auto-detect target routing if not provided (skip for external/cross-prefix).
targetTable := opts.TargetTable
if targetTable == "" && !strings.HasPrefix(dep.DependsOnID, "external:") && !opts.IsCrossPrefix {
targetIsWisp := IsActiveWispInTx(ctx, tx, dep.DependsOnID)
targetTable, _, _, _ = WispTableRouting(targetIsWisp)
}
if targetTable == "" {
targetTable = "issues"
}
depTables := opts.DepTables
if len(depTables) == 0 {
depTables = cycleDetectionTables()
}
metadata := dep.Metadata
if metadata == "" {
metadata = "{}"
}
// Validate source issue exists and get its type.
var sourceType string
//nolint:gosec // G201: sourceTable is from WispTableRouting ("issues" or "wisps")
if err := tx.QueryRowContext(ctx, fmt.Sprintf(`SELECT issue_type FROM %s WHERE id = ?`, sourceTable), dep.IssueID).Scan(&sourceType); err != nil {
if errors.Is(err, sql.ErrNoRows) {
return false, fmt.Errorf("issue %s not found", dep.IssueID)
}
return false, fmt.Errorf("failed to check issue existence: %w", err)
}
// Validate target issue exists (skip for external and cross-prefix refs,
// and for targets the caller already read on their own transaction).
var targetType string
switch {
case opts.PrecheckedTarget != nil:
targetType = opts.PrecheckedTarget.IssueType
case !strings.HasPrefix(dep.DependsOnID, "external:") && !opts.IsCrossPrefix:
//nolint:gosec // G201: targetTable is from WispTableRouting ("issues" or "wisps")
if err := tx.QueryRowContext(ctx, fmt.Sprintf(`SELECT issue_type FROM %s WHERE id = ?`, targetTable), dep.DependsOnID).Scan(&targetType); err != nil {
if errors.Is(err, sql.ErrNoRows) {
return false, fmt.Errorf("issue %s not found", dep.DependsOnID)
}
return false, fmt.Errorf("failed to check target issue existence: %w", err)
}
}
if targetType != "" {
if err := CheckBlockingHierarchyInTx(ctx, tx, dep, depTables); err != nil {
return false, err
}
}
if !opts.SkipCycleCheck {
if err := CheckDependencyCycleInTx(ctx, tx, dep, depTables); err != nil {
return false, err
}
}
var kind DepTargetKind
if opts.TargetKind != nil {
kind = *opts.TargetKind
} else {
kind = ClassifyDepTarget(ctx, tx, dep, opts.IsCrossPrefix)
}
targetCol := kind.Column()
// Check for existing dependency between the same pair. Use the resolved
// target expression defensively so stale/reclassified rows in another typed
// target column cannot bypass the idempotency/conflict check.
var existingType string
//nolint:gosec // G201: writeTable from WispTableRouting; depTargetEquals has no user input.
err := tx.QueryRowContext(ctx, fmt.Sprintf(`SELECT type FROM %s WHERE issue_id = ? AND %s`, writeTable, depTargetEquals("")),
dep.IssueID, dep.DependsOnID).Scan(&existingType)
if err == nil {
if existingType == string(dep.Type) {
// Same type — idempotent; update metadata. No event is written, so the
// caller must not stage the events table for this re-add.
//nolint:gosec // G201: writeTable from WispTableRouting; depTargetEquals has no user input.
if _, err := tx.ExecContext(ctx, fmt.Sprintf(`UPDATE %s SET metadata = ? WHERE issue_id = ? AND %s`, writeTable, depTargetEquals("")),
metadata, dep.IssueID, dep.DependsOnID); err != nil {
return false, fmt.Errorf("failed to update dependency metadata: %w", err)
}
return false, nil
}
return false, &domain.DependencyTypeConflictError{
IssueID: dep.IssueID,
DependsOnID: dep.DependsOnID,
ExistingType: existingType,
RequestedType: string(dep.Type),
}
} else if !errors.Is(err, sql.ErrNoRows) {
return false, fmt.Errorf("failed to check existing dependency: %w", err)
}
// id is derived deterministically from the natural edge key (issue_id,
// target) so the same edge gets the same primary key on every clone and the
// dependencies table merges cleanly across Dolt clones (#4259). DependsOnID
// is the resolved target written into targetCol.
//nolint:gosec // G201: writeTable from WispTableRouting; targetCol from DepTargetKind.Column()
if _, err := tx.ExecContext(ctx, fmt.Sprintf(`
INSERT INTO %s (id, issue_id, %s, type, created_at, created_by, metadata, thread_id)
VALUES (?, ?, ?, ?, NOW(), ?, ?, ?)
`, writeTable, targetCol), depid.New(dep.IssueID, dep.DependsOnID), dep.IssueID, dep.DependsOnID, dep.Type, actor, metadata, dep.ThreadID); err != nil {
return false, fmt.Errorf("failed to add dependency: %w", err)
}
srcIsWisp := writeTable == "wisp_dependencies"
// Record the dependency_added event on the source issue's event table so the
// bd CLI and library callers observing an issue's history see the new edge.
// The source's event table routes the same way as its dependency write table
// (wisp_dependencies -> wisp_events). This runs only on the genuine new-edge
// path: the idempotent same-type re-add returned earlier without emitting.
// Gated on EmitEvent so only explicit dep verbs emit; create-with-deps and
// structural callers wire the edge silently (parity with the proxied repo).
eventWritten := false
if opts.EmitEvent {
_, _, eventTable, _ := WispTableRouting(srcIsWisp)
if err := RecordEventInTable(ctx, tx, eventTable, dep.IssueID, types.EventDependencyAdded, actor,
fmt.Sprintf("Added dependency: %s %s %s", dep.IssueID, dep.Type, dep.DependsOnID)); err != nil {
return false, fmt.Errorf("record dependency_added event: %w", err)
}
eventWritten = true
}
var affectedIssues, affectedWisps []string
var aerr error
if srcIsWisp {
affectedIssues, affectedWisps, aerr = AffectedByDepChangeForWispInTx(ctx, tx, dep.IssueID, dep.DependsOnID, dep.Type)
} else {
affectedIssues, affectedWisps, aerr = AffectedByDepChangeInTx(ctx, tx, dep.IssueID, dep.DependsOnID, dep.Type)
}
if aerr != nil {
return false, fmt.Errorf("affected by add dependency %s -> %s: %w", dep.IssueID, dep.DependsOnID, aerr)
}
if dep.Type == types.DepBlocks || dep.Type == types.DepConditionalBlocks {
if err := markDirectBlockingDependencySourceInTx(ctx, tx, dep.IssueID, srcIsWisp, dep.DependsOnID, kind, opts.PrecheckedTarget); err != nil {
return false, fmt.Errorf("mark direct is_blocked after add dependency %s -> %s: %w", dep.IssueID, dep.DependsOnID, err)
}
affectedIssues, affectedWisps = RemoveSourceFromAffected(dep.IssueID, srcIsWisp, affectedIssues, affectedWisps)
}
if dep.Type == types.DepParentChild {
// Parent-child adds are not monotonic: adding an already-closed child can
// satisfy an any-children waits-for gate and unblock the waiter.
if err := RecomputeIsBlockedInTx(ctx, tx, affectedIssues, affectedWisps); err != nil {
return false, fmt.Errorf("recompute is_blocked after add dependency %s -> %s: %w", dep.IssueID, dep.DependsOnID, err)
}
return eventWritten, nil
}
if err := MarkIsBlockedInTx(ctx, tx, affectedIssues, affectedWisps); err != nil {
return false, fmt.Errorf("mark is_blocked after add dependency %s -> %s: %w", dep.IssueID, dep.DependsOnID, err)
}
return eventWritten, nil
}
// RemoveSourceFromAffected drops the dep source from the affected-ID sets
// after a direct is_blocked mark, so the follow-up Mark/Recompute pass does
// not redo it. Shared with the domain/db dependency repository.
func RemoveSourceFromAffected(source string, srcIsWisp bool, issueIDs, wispIDs []string) ([]string, []string) {
if srcIsWisp {
return issueIDs, removeID(wispIDs, source)
}
return removeID(issueIDs, source), wispIDs
}
func removeID(ids []string, remove string) []string {
if len(ids) == 0 {
return ids
}
out := ids[:0]
for _, id := range ids {
if id != remove {
out = append(out, id)
}
}
return out
}
//nolint:gosec // G201: table names are selected from fixed issue/wisp tables.
func markDirectBlockingDependencySourceInTx(ctx context.Context, tx *sql.Tx, source string, srcIsWisp bool, target string, targetKind DepTargetKind, precheckedTarget *DepTargetPrecheck) error {
sourceTable := "issues"
if srcIsWisp {
sourceTable = "wisps"
}
targetTable := ""
switch targetKind {
case DepTargetIssue:
targetTable = "issues"
case DepTargetWisp:
targetTable = "wisps"
default:
return nil
}
if precheckedTarget != nil {
// The target row lives on another session; the EXISTS gate below
// would miss it there. Its openness is already known, so gate in Go
// and mark the source (whose table always matches tx) directly.
if types.Status(precheckedTarget.Status) == types.StatusClosed || types.Status(precheckedTarget.Status) == types.StatusPinned {
return nil
}
_, err := tx.ExecContext(ctx, fmt.Sprintf(`
UPDATE %s s SET s.is_blocked = 1, s.updated_at = s.updated_at
WHERE s.id = ?
AND s.is_blocked = 0
AND s.status <> 'closed' AND s.status <> 'pinned'
`, sourceTable), source)
return err
}
// MySQL 8.0+ rejects UPDATE <T> ... WHERE EXISTS (SELECT FROM <T> ...)
// even with distinct aliases (Error 1093: can't specify target table
// for update in FROM clause), which fires here whenever sourceTable ==
// targetTable. Wrapping the inner SELECT in a derived table makes MySQL
// treat it as an independent rowset, satisfying the restriction. Dolt
// accepts both forms, so this is a no-op there.
_, err := tx.ExecContext(ctx, fmt.Sprintf(`
UPDATE %s s SET s.is_blocked = 1, s.updated_at = s.updated_at
WHERE s.id = ?
AND s.is_blocked = 0
AND s.status <> 'closed' AND s.status <> 'pinned'
AND EXISTS (
SELECT 1 FROM (
SELECT id, status FROM %s WHERE id = ?
) AS t
WHERE t.status <> 'closed' AND t.status <> 'pinned'
)
`, sourceTable, targetTable), source, target)
return err
}
// CheckDependencyCycleInTx rejects self-dependencies and cycles across the
// combined blocks, conditional-blocks, and parent-child graph before insert.
// The caller may pass a restricted depTables list for a known storage bucket;
// nil uses all dependency tables.
func CheckDependencyCycleInTx(ctx context.Context, tx DBTX, dep *types.Dependency, depTables []string) error {
if dep.IssueID == dep.DependsOnID {
return fmt.Errorf("%w: %s cannot depend on itself", domain.ErrSelfDependency, dep.IssueID)
}
if !isSchedulingEdge(dep.Type) {
return nil
}
wouldCycle, err := WouldCreateSchedulingCycleInTx(ctx, tx, dep.IssueID, dep.DependsOnID, depTables)
if err != nil {
return fmt.Errorf("failed to check for dependency cycle: %w", err)
}
if wouldCycle {
return domain.ErrDependencyCycle
}
return nil
}
// WouldCreateSchedulingCycleInTx reports whether adding issueID -> dependsOnID
// would close a cycle in the combined scheduling graph. It is shared by the
// classic and domain storage stacks so both traverse the same dependency types
// and typed target columns.
func WouldCreateSchedulingCycleInTx(ctx context.Context, tx DBTX, issueID, dependsOnID string, depTables []string) (bool, error) {
if len(depTables) == 0 {
depTables = cycleDetectionTables()
}
var reachable int
query := cycleReachabilityQuery(depTables)
if err := tx.QueryRowContext(ctx, query, dependsOnID, issueID).Scan(&reachable); err != nil {
return false, err
}
return reachable > 0, nil
}
// cycleReachabilityQuery uses UNION distinct recursion so cyclic and diamond
// graphs terminate by unique reachable node instead of enumerating paths.
//
// The walked edge set is the union of scheduling-relevant edges: blocks,
// conditional-blocks, and parent-child. Parent-child is included because a
// blocked parent propagates its blocked state to its children in the
// ready-work computation, so a chain mixing blocks and parent-child edges
// can form a logical livelock that prevents anything from being ready.
func cycleReachabilityQuery(depTables []string) string {
if len(depTables) == 1 {
return fmt.Sprintf(`
WITH RECURSIVE reachable(node) AS (
SELECT ?
UNION
SELECT %s
FROM reachable r
JOIN %s d ON d.issue_id = r.node AND d.type IN ('blocks', 'conditional-blocks', 'parent-child')
)
SELECT COUNT(*) FROM reachable WHERE node = ?
`, DepTargetExpr, depTables[0])
}
var unions []string
for _, t := range depTables {
unions = append(unions, fmt.Sprintf("SELECT issue_id, %s AS depends_on_id FROM %s WHERE type IN ('blocks', 'conditional-blocks', 'parent-child')", DepTargetExpr, t))
}
unionQuery := strings.Join(unions, " UNION ")
return fmt.Sprintf(`
WITH RECURSIVE reachable(node) AS (
SELECT ?
UNION
SELECT d.depends_on_id
FROM reachable r
JOIN (%s) d ON d.issue_id = r.node
)
SELECT COUNT(*) FROM reachable WHERE node = ?
`, unionQuery)
}
func cycleDetectionTables() []string {
return []string{"dependencies", "wisp_dependencies"}
}
// isSchedulingEdge reports whether a dependency type belongs to the static
// combined-cycle set: blocks, conditional-blocks, and parent-child. Waits-for
// also affects readiness but is intentionally outside this validation rule.
func isSchedulingEdge(t types.DependencyType) bool {
switch t {
case types.DepBlocks, types.DepConditionalBlocks, types.DepParentChild:
return true
default:
return false
}
}
// CheckBlockingHierarchyInTx rejects blocking dependencies between an issue
// and its own ancestor or descendant. Cross-prefix/external targets must be
// filtered by the caller because no local hierarchy can connect them.
func CheckBlockingHierarchyInTx(ctx context.Context, tx DBTX, dep *types.Dependency, depTables []string) error {
if dep.Type != types.DepBlocks && dep.Type != types.DepConditionalBlocks {
return nil
}
if dep.IssueID == dep.DependsOnID {
return nil // The dedicated self-dependency check owns this error.
}
if len(depTables) == 0 {
depTables = cycleDetectionTables()
}
blockerIsAncestor, err := isAncestorInTx(ctx, tx, dep.IssueID, dep.DependsOnID, depTables)
if err != nil {
return fmt.Errorf("failed to check blocker ancestry: %w", err)
}
if blockerIsAncestor {
return &domain.DependencyHierarchyConflictError{
IssueID: dep.IssueID, BlockerID: dep.DependsOnID, BlockerIsAncestor: true,
}
}
blockerIsDescendant, err := isAncestorInTx(ctx, tx, dep.DependsOnID, dep.IssueID, depTables)
if err != nil {
return fmt.Errorf("failed to check blocker ancestry: %w", err)
}
if blockerIsDescendant {
return &domain.DependencyHierarchyConflictError{
IssueID: dep.IssueID, BlockerID: dep.DependsOnID,
}
}
return nil
}
// isAncestorInTx reports whether candidate is an ancestor of node along
// parent-child dependency edges (walking child -> parent only, so siblings
// and cousins in the same hierarchy do not match). Uses UNION distinct
// recursion so diamond/cyclic parentage terminates by unique reachable node.
func isAncestorInTx(ctx context.Context, tx DBTX, node, candidate string, depTables []string) (bool, error) {
var unions []string
for _, t := range depTables {
unions = append(unions, fmt.Sprintf("SELECT issue_id, %s AS parent_id FROM %s WHERE type = 'parent-child'", DepTargetExpr, t))
}
//nolint:gosec // G201: depTables are fixed dependency table names from cycleDetectionTables/opts.
query := fmt.Sprintf(`
WITH RECURSIVE ancestors(node) AS (
SELECT ?
UNION
SELECT d.parent_id
FROM ancestors a
JOIN (%s) d ON d.issue_id = a.node
)
SELECT COUNT(*) FROM ancestors WHERE node = ?
`, strings.Join(unions, " UNION "))
var n int
if err := tx.QueryRowContext(ctx, query, node, candidate).Scan(&n); err != nil {
return false, err
}
return n > 0, nil
}
func DeleteWispFromDependenciesInTx(ctx context.Context, tx *sql.Tx, wispID string) error {
if _, err := tx.ExecContext(ctx,
"DELETE FROM dependencies WHERE depends_on_wisp_id = ?", wispID); err != nil {
return fmt.Errorf("delete wisp %s from dependencies: %w", wispID, err)
}
return nil
}
//nolint:gosec // G201: inClause contains only ? placeholders
func DeleteWispsFromDependenciesInTx(ctx context.Context, tx *sql.Tx, wispIDs []string) error {
if len(wispIDs) == 0 {
return nil
}
inClause, args := buildSQLInClause(wispIDs)
if _, err := tx.ExecContext(ctx,
fmt.Sprintf("DELETE FROM dependencies WHERE depends_on_wisp_id IN (%s)", inClause),
args...); err != nil {
return fmt.Errorf("delete wisps from dependencies: %w", err)
}
return nil
}
// Dependency target rewrites reinsert matching rows because Dolt can leave the
// stored generated depends_on_id column stale after a split target column is
// updated by FK cascade.
func UpdateWispIDInDependenciesInTx(ctx context.Context, tx *sql.Tx, oldID, newID string) error {
for _, table := range []string{"dependencies", "wisp_dependencies"} {
if err := replaceDependencyTargetInTx(ctx, tx, table, "depends_on_wisp_id", oldID, newID); err != nil {
return fmt.Errorf("update wisp %s -> %s in %s: %w", oldID, newID, table, err)
}
}
return nil
}
func UpdateIssueIDInDependenciesInTx(ctx context.Context, tx *sql.Tx, oldID, newID string) error {
for _, table := range []string{"dependencies", "wisp_dependencies"} {
if err := replaceDependencyTargetInTx(ctx, tx, table, "depends_on_issue_id", oldID, newID); err != nil {
return fmt.Errorf("update issue target %s -> %s in %s: %w", oldID, newID, table, err)
}
}
// Re-derive the deterministic primary key for rows whose SOURCE issue was
// renamed. dependencies.issue_id carries fk_dep_issue ... ON UPDATE CASCADE, so
// renaming the issues row (updateIssueIDInTx updates issues.id first) cascades
// issue_id from oldID to newID before we get here — but the cascade leaves the
// surrogate id at depid.New(oldID, target). A stale id re-forks the primary key
// across clones (#4259) and breaks the same-PK => same-edge invariant the pull
// conflict resolver relies on, so recompute it from the post-rename (newID, target).
if err := rekeyDependencySourceInTx(ctx, tx, oldID, newID); err != nil {
return fmt.Errorf("rekey dependency sources %s -> %s: %w", oldID, newID, err)
}
return nil
}
// rekeyDependencySourceInTx rewrites dependencies.id for every edge whose source
// issue was renamed to newID so the stored id equals depid.New(newID, target). It
// matches rows by both newID (the normal post-FK-cascade state) and oldID (defensive,
// in case a caller reaches here before the cascade) and re-asserts issue_id = newID
// so the row converges either way. Only rows whose id is actually stale are touched.
func rekeyDependencySourceInTx(ctx context.Context, tx *sql.Tx, oldID, newID string) error {
queryRows, err := tx.QueryContext(ctx, `
SELECT id, depends_on_issue_id, depends_on_wisp_id, depends_on_external
FROM dependencies
WHERE issue_id = ? OR issue_id = ?
`, newID, oldID)
if err != nil {
return fmt.Errorf("query dependency sources: %w", err)
}
type rekey struct{ oldRowID, newRowID string }
var rekeys []rekey
for queryRows.Next() {
var id string
var issueTarget, wispTarget, external sql.NullString
if err := queryRows.Scan(&id, &issueTarget, &wispTarget, &external); err != nil {
_ = queryRows.Close()
return fmt.Errorf("scan dependency source: %w", err)
}
target, ok := resolveDependencyTarget(issueTarget, wispTarget, external)
if !ok {
continue // ck_dep_one_target guarantees one target; skip defensively
}
if want := depid.New(newID, target); want != id {
rekeys = append(rekeys, rekey{oldRowID: id, newRowID: want})
}
}
_ = queryRows.Close()
if err := queryRows.Err(); err != nil {
return fmt.Errorf("iterate dependency sources: %w", err)
}
for _, rk := range rekeys {
if _, err := tx.ExecContext(ctx,
"UPDATE dependencies SET id = ?, issue_id = ? WHERE id = ?",
rk.newRowID, newID, rk.oldRowID); err != nil {
return fmt.Errorf("rekey dependency source id %s -> %s: %w", rk.oldRowID, rk.newRowID, err)
}
}
return nil
}
// resolveDependencyTarget returns the single non-null dependency target — the value
// depid.New and the uk_dep_* unique keys treat as the edge's target — following the
// same precedence as DepTargetExpr (issue, then wisp, then external).
func resolveDependencyTarget(issueTarget, wispTarget, external sql.NullString) (string, bool) {
switch {
case issueTarget.Valid:
return issueTarget.String, true
case wispTarget.Valid:
return wispTarget.String, true
case external.Valid:
return external.String, true
default:
return "", false
}
}
func replaceDependencyTargetInTx(ctx context.Context, tx *sql.Tx, table, column, oldID, newID string) error {
// Dolt does not reliably recompute the stored generated depends_on_id when
// only the split target column changes. Reinsert rows so the generated key
// is calculated from the new target value.
if err := checkRenameTargetCollision(ctx, tx, table, column, newID); err != nil {
return err
}
type depRow struct {
issueID string
issueTarget sql.NullString
wispTarget sql.NullString
external sql.NullString
depType string
createdAt sql.NullTime
createdBy sql.NullString
metadata sql.NullString
threadID sql.NullString
}
rows := make([]depRow, 0)
//nolint:gosec // table and column are hardcoded by callers.
queryRows, err := tx.QueryContext(ctx, fmt.Sprintf(`
SELECT issue_id, depends_on_issue_id, depends_on_wisp_id, depends_on_external, type, created_at, created_by, metadata, thread_id
FROM %s
WHERE %s = ? OR (%s = ? AND depends_on_external IS NULL)
`, table, column, DepTargetExpr), oldID, oldID)
if err != nil {
return fmt.Errorf("query dependency targets: %w", err)
}
for queryRows.Next() {
var row depRow
if err := queryRows.Scan(&row.issueID, &row.issueTarget, &row.wispTarget, &row.external, &row.depType, &row.createdAt, &row.createdBy, &row.metadata, &row.threadID); err != nil {
_ = queryRows.Close()
return fmt.Errorf("scan dependency target: %w", err)
}
switch column {
case "depends_on_issue_id":
row.issueTarget = sql.NullString{String: newID, Valid: true}
row.wispTarget = sql.NullString{}
row.external = sql.NullString{}
case "depends_on_wisp_id":
row.issueTarget = sql.NullString{}
row.wispTarget = sql.NullString{String: newID, Valid: true}
row.external = sql.NullString{}
default:
_ = queryRows.Close()
return fmt.Errorf("replace dependency target: unsupported typed column %q", column)
}
rows = append(rows, row)
}
_ = queryRows.Close()
if err := queryRows.Err(); err != nil {
return fmt.Errorf("iterate dependency targets: %w", err)
}
//nolint:gosec // table and column are hardcoded by callers.
if _, err := tx.ExecContext(ctx, fmt.Sprintf(`DELETE FROM %s WHERE %s = ? OR (%s = ? AND depends_on_external IS NULL)`, table, column, DepTargetExpr), oldID, oldID); err != nil {
return fmt.Errorf("delete old dependency target: %w", err)
}
for _, row := range rows {
// The retargeted edge's natural key is (issue_id, newID): the switch above
// set exactly one typed target column to newID. Re-derive id from it so the
// rewritten row stays merge-safe and keeps a clone-stable primary key (#4259).
//nolint:gosec // table is hardcoded by callers.
if _, err := tx.ExecContext(ctx, fmt.Sprintf(`
INSERT INTO %s (id, issue_id, depends_on_issue_id, depends_on_wisp_id, depends_on_external, type, created_at, created_by, metadata, thread_id)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
`, table), depid.New(row.issueID, newID), row.issueID, nullStringValue(row.issueTarget), nullStringValue(row.wispTarget), nullStringValue(row.external), row.depType, nullTimeValue(row.createdAt), nullStringValue(row.createdBy), nullStringValue(row.metadata), nullStringValue(row.threadID)); err != nil {
return fmt.Errorf("insert replacement dependency target: %w", err)
}
}
return nil
}
func nullStringValue(value sql.NullString) any {
if !value.Valid {
return nil
}
return value.String
}
func nullTimeValue(value sql.NullTime) any {
if !value.Valid {
return nil
}
return value.Time
}
func RetargetInboundDependenciesToWispInTx(ctx context.Context, tx *sql.Tx, id string) error {
for _, table := range []string{"dependencies", "wisp_dependencies"} {
if err := checkRetargetTargetCollision(ctx, tx, table, "depends_on_issue_id", "depends_on_wisp_id", id); err != nil {
return err
}
if err := checkRenameTargetCollision(ctx, tx, table, "depends_on_wisp_id", id); err != nil {
return err
}
if _, err := tx.ExecContext(ctx, fmt.Sprintf(`
UPDATE %s
SET depends_on_wisp_id = ?, depends_on_issue_id = NULL
WHERE depends_on_issue_id = ?
`, table), id, id); err != nil {
return fmt.Errorf("retarget inbound dependencies to wisp in %s for %s: %w", table, id, err)
}
}
return nil
}
func RetargetInboundDependenciesToIssueInTx(ctx context.Context, tx *sql.Tx, id string) error {
for _, table := range []string{"dependencies", "wisp_dependencies"} {
if err := checkRetargetTargetCollision(ctx, tx, table, "depends_on_wisp_id", "depends_on_issue_id", id); err != nil {
return err
}
if err := checkRenameTargetCollision(ctx, tx, table, "depends_on_issue_id", id); err != nil {
return err
}
if _, err := tx.ExecContext(ctx, fmt.Sprintf(`
UPDATE %s
SET depends_on_issue_id = ?, depends_on_wisp_id = NULL
WHERE depends_on_wisp_id = ?
`, table), id, id); err != nil {
return fmt.Errorf("retarget inbound dependencies to issue in %s for %s: %w", table, id, err)
}
}
return nil
}
// UpdateIssueIDInDependencyTargetsInTx is called after the issues PK is updated
// from oldID to newID. FK ON UPDATE CASCADE has already propagated
// depends_on_issue_id from oldID to newID across dependencies and
// wisp_dependencies, so no rewrite is needed.
func UpdateIssueIDInDependencyTargetsInTx(ctx context.Context, tx *sql.Tx, _, newID string) error {
for _, table := range []string{"dependencies", "wisp_dependencies"} {
if err := checkRenameTargetCollision(ctx, tx, table, "depends_on_issue_id", newID); err != nil {
return err
}
}
return nil
}
//nolint:gosec // G201: table and typed columns are hardcoded constants.
func checkRetargetTargetCollision(ctx context.Context, tx *sql.Tx, table, sourceCol, destCol, id string) error {
var conflictCols []string
switch destCol {
case "depends_on_issue_id":
conflictCols = []string{"depends_on_issue_id", "depends_on_external"}
case "depends_on_wisp_id":
conflictCols = []string{"depends_on_wisp_id", "depends_on_external"}
default:
return fmt.Errorf("checkRetargetTargetCollision: unsupported destination column %q", destCol)
}
if sourceCol != "depends_on_issue_id" && sourceCol != "depends_on_wisp_id" {
return fmt.Errorf("checkRetargetTargetCollision: unsupported source column %q", sourceCol)
}
query := fmt.Sprintf(`
SELECT 1 FROM %s moving
JOIN %s existing ON moving.issue_id = existing.issue_id
WHERE moving.%s = ?
AND (existing.%s = ? OR existing.%s = ?)
LIMIT 1
`, table, table, sourceCol, conflictCols[0], conflictCols[1])
var found int
err := tx.QueryRowContext(ctx, query, id, id, id).Scan(&found)
if err == sql.ErrNoRows {
return nil
}
if err != nil {
if isTableNotExistError(err) {
return nil
}
return fmt.Errorf("check retarget collision in %s: %w", table, err)
}
return fmt.Errorf("retarget to %s collides with existing dependency target in %s", id, table)
}
//nolint:gosec // G201: table and typedCol are hardcoded constants.
func checkRenameTargetCollision(ctx context.Context, tx *sql.Tx, table, typedCol, newID string) error {
var otherCols []string
switch typedCol {
case "depends_on_issue_id":
otherCols = []string{"depends_on_wisp_id", "depends_on_external"}
case "depends_on_wisp_id":
otherCols = []string{"depends_on_issue_id", "depends_on_external"}
default:
return fmt.Errorf("checkRenameTargetCollision: unsupported typed column %q", typedCol)
}
query := fmt.Sprintf(`
SELECT 1 FROM %s a
JOIN %s b ON a.issue_id = b.issue_id
WHERE a.%s = ?
AND (b.%s = ? OR b.%s = ?)
LIMIT 1
`, table, table, typedCol, otherCols[0], otherCols[1])
var found int
err := tx.QueryRowContext(ctx, query, newID, newID, newID).Scan(&found)
if err == sql.ErrNoRows {
return nil
}
if err != nil {
if isTableNotExistError(err) {
return nil
}
return fmt.Errorf("check rename collision in %s: %w", table, err)
}
return fmt.Errorf("rename to %s collides with existing dependency target in %s", newID, table)
}
// RemoveDependencyInTx removes a dependency between two issues within an
// existing transaction. Automatically routes to wisp_dependencies if the
// source issue is an active wisp. When emitEvent is set and a row is actually
// removed it records a dependency_removed event (attributed to actor) on the
// source's event table; a no-op remove of a missing edge, or a structural remove
// with emitEvent unset, records nothing. Only the explicit bd dep remove verb
// sets emitEvent; structural removals (issue delete, reparent, batch, duplicate
// cleanup) leave it unset so they wire edges away silently, mirroring the
// proxied repository's DepInsertOpts.EmitEvent gate so both backends record
// identical history.
//
// It returns whether a dependency_removed event was actually written, so callers
// that stage tables for a Dolt commit stage the events table only when an event
// row exists (avoiding the sweep-unrelated-rows hazard doltAddAndCommit guards
// against, GH#2455).
//
//nolint:gosec // G201: depTable from WispTableRouting (hardcoded constants)
func RemoveDependencyInTx(ctx context.Context, tx *sql.Tx, issueID, dependsOnID, actor string, emitEvent bool) (bool, error) {
isWisp := IsActiveWispInTx(ctx, tx, issueID)
_, _, eventTable, depTable := WispTableRouting(isWisp)
// Capture the row's type before deleting so we can dispatch the right
// affected-set helper. If no row matches, treat as a no-op.
var depType string
row := tx.QueryRowContext(ctx, fmt.Sprintf(
`SELECT type FROM %s WHERE issue_id = ? AND %s = ?`, depTable, DepTargetExpr),
issueID, dependsOnID)
if err := row.Scan(&depType); err != nil {
if errors.Is(err, sql.ErrNoRows) {
return false, nil
}
return false, fmt.Errorf("lookup dependency type for %s -> %s: %w", issueID, dependsOnID, err)
}
if _, err := tx.ExecContext(ctx, fmt.Sprintf(
`DELETE FROM %s WHERE issue_id = ? AND %s = ?`, depTable, DepTargetExpr),
issueID, dependsOnID); err != nil {
return false, fmt.Errorf("remove dependency: %w", err)
}
// The lookup above returned early when no row matched, so reaching here means
// an edge was actually deleted. Record the dependency_removed event on the
// source issue's event table for bd CLI / library history observers — but only
// when emitEvent is set, so structural removes stay silent (parity with the
// proxied repo and with the symmetric AddDependencyInTx EmitEvent gate).
eventWritten := false
if emitEvent {
if err := RecordEventInTable(ctx, tx, eventTable, issueID, types.EventDependencyRemoved, actor,
fmt.Sprintf("Removed dependency on %s", dependsOnID)); err != nil {
return false, fmt.Errorf("record dependency_removed event: %w", err)
}
eventWritten = true
}
var affectedIssues, affectedWisps []string
var aerr error
if isWisp {
affectedIssues, affectedWisps, aerr = AffectedByDepChangeForWispInTx(ctx, tx, issueID, dependsOnID, types.DependencyType(depType))
} else {
affectedIssues, affectedWisps, aerr = AffectedByDepChangeInTx(ctx, tx, issueID, dependsOnID, types.DependencyType(depType))
}
if aerr != nil {
return false, fmt.Errorf("affected by remove dependency %s -> %s: %w", issueID, dependsOnID, aerr)
}
if err := RecomputeIsBlockedInTx(ctx, tx, affectedIssues, affectedWisps); err != nil {
return false, fmt.Errorf("recompute is_blocked after remove dependency %s -> %s: %w", issueID, dependsOnID, err)
}
return eventWritten, nil
}
// GetIssuesByIDsInTx retrieves multiple issues by ID within an existing
// transaction, including labels. Automatically routes each ID to the correct
// table (issues/wisps). Uses batched IN clauses.
//
// wispSet is an optional pre-built set of active wisp IDs scoped to
// cover ids (see WispIDSetInTx). Pass nil to have the helper build
// a scoped set internally; callers hydrating multiple batches inside
// one tx can build the set once over the union of their IDs and
// reuse it across calls.
//
//nolint:gosec // G201: table names come from WispTableRouting (hardcoded constants)
func GetIssuesByIDsInTx(ctx context.Context, tx DBTX, ids []string, wispSet map[string]struct{}) ([]*types.Issue, error) {
if len(ids) == 0 {
return nil, nil
}
if wispSet == nil {
var err error
wispSet, err = WispIDSetInTx(ctx, tx, ids)
if err != nil {
return nil, fmt.Errorf("get issues by IDs: build wisp set: %w", err)
}
}
// Partition IDs by wisp status.
wispIDs, permIDs := partitionByWispSet(ids, wispSet)
var allIssues []*types.Issue
for _, pair := range []struct {
table string
labelTbl string
ids []string
}{
{"issues", "labels", permIDs},
{"wisps", "wisp_labels", wispIDs},
} {
if len(pair.ids) == 0 {
continue
}
for start := 0; start < len(pair.ids); start += queryBatchSize {
end := start + queryBatchSize
if end > len(pair.ids) {
end = len(pair.ids)
}
batch := pair.ids[start:end]
placeholders := make([]string, len(batch))
args := make([]any, len(batch))
for i, id := range batch {
placeholders[i] = "?"
args[i] = id
}
inClause := strings.Join(placeholders, ",")
rows, err := tx.QueryContext(ctx, fmt.Sprintf(
`SELECT %s FROM %s %s WHERE id IN (%s)`,
IssueSelectColumns, pair.table, sqlbuild.LeaseJoin(pair.table), inClause), args...)
if err != nil {
return nil, fmt.Errorf("get issues by IDs from %s: %w", pair.table, err)
}
issueMap := make(map[string]*types.Issue)
for rows.Next() {
issue, scanErr := ScanIssueFrom(rows)
if scanErr != nil {
_ = rows.Close()
return nil, fmt.Errorf("get issues by IDs: scan: %w", scanErr)
}
allIssues = append(allIssues, issue)
issueMap[issue.ID] = issue
}
_ = rows.Close()
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("get issues by IDs: rows: %w", err)
}
// Hydrate labels.
if len(issueMap) > 0 {
labelRows, err := tx.QueryContext(ctx, fmt.Sprintf(
`SELECT issue_id, label FROM %s WHERE issue_id IN (%s) ORDER BY issue_id, label`,
pair.labelTbl, inClause), args...)
if err != nil {
return nil, fmt.Errorf("get issues by IDs: labels from %s: %w", pair.labelTbl, err)
}
for labelRows.Next() {
var issueID, label string
if scanErr := labelRows.Scan(&issueID, &label); scanErr != nil {
_ = labelRows.Close()
return nil, fmt.Errorf("get issues by IDs: scan label: %w", scanErr)
}
if issue, ok := issueMap[issueID]; ok {
issue.Labels = append(issue.Labels, label)
}
}
_ = labelRows.Close()
if err := labelRows.Err(); err != nil {
return nil, fmt.Errorf("get issues by IDs: label rows: %w", err)
}
}
}
}
return allIssues, nil
}
// GetDependenciesWithMetadataInTx returns issues that the given issueID depends on,
// along with the dependency type. Works within an existing transaction.
// Queries both dependency tables to handle cross-table dependencies.
//
//nolint:gosec // G201: table names come from hardcoded constants
func GetDependenciesWithMetadataInTx(ctx context.Context, tx DBTX, issueID string) ([]*types.IssueWithDependencyMetadata, error) {
type depMeta struct {
depID, depType string
}
// Query both dependency tables to find all dependencies.
var deps []depMeta
for _, depTable := range []string{"dependencies", "wisp_dependencies"} {
rows, err := tx.QueryContext(ctx, fmt.Sprintf(
`SELECT %s AS depends_on_id, type FROM %s WHERE issue_id = ?`, DepTargetExpr, depTable), issueID)
if err != nil {
return nil, fmt.Errorf("get dependencies from %s: %w", depTable, err)
}
for rows.Next() {
var d depMeta
if scanErr := rows.Scan(&d.depID, &d.depType); scanErr != nil {
_ = rows.Close()
return nil, fmt.Errorf("get dependencies: scan: %w", scanErr)
}
deps = append(deps, d)
}
_ = rows.Close()
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("get dependencies: rows from %s: %w", depTable, err)
}
}
if len(deps) == 0 {
return nil, nil
}
// Fetch all dependency target issues.
ids := make([]string, len(deps))
for i, d := range deps {
ids[i] = d.depID
}
issues, err := GetIssuesByIDsInTx(ctx, tx, ids, nil)
if err != nil {
return nil, fmt.Errorf("get dependencies: fetch issues: %w", err)
}
issueMap := make(map[string]*types.Issue, len(issues))
for _, iss := range issues {
issueMap[iss.ID] = iss
}
var results []*types.IssueWithDependencyMetadata
for _, d := range deps {
issue, ok := issueMap[d.depID]
if !ok {
continue
}
results = append(results, &types.IssueWithDependencyMetadata{
Issue: *issue,
DependencyType: types.DependencyType(d.depType),
})
}
return results, nil
}
// GetDependentsWithMetadataInTx returns issues that depend on the given issueID
// along with the dependency type. Works within an existing transaction.
//
//nolint:gosec // G201: table names come from WispTableRouting (hardcoded constants)
func GetDependentsWithMetadataInTx(ctx context.Context, tx DBTX, issueID string) ([]*types.IssueWithDependencyMetadata, error) {
type depMeta struct {
depID, depType string
}
// Query both dependency tables to find all dependents.
var deps []depMeta
for _, depTable := range []string{"dependencies", "wisp_dependencies"} {
rows, err := tx.QueryContext(ctx, fmt.Sprintf(
`SELECT issue_id, type FROM %s WHERE %s = ?`, depTable, DepTargetExpr), issueID)
if err != nil {
return nil, fmt.Errorf("get dependents from %s: %w", depTable, err)
}
for rows.Next() {
var d depMeta
if scanErr := rows.Scan(&d.depID, &d.depType); scanErr != nil {
_ = rows.Close()
return nil, fmt.Errorf("get dependents: scan: %w", scanErr)
}
deps = append(deps, d)
}
_ = rows.Close()
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("get dependents: rows from %s: %w", depTable, err)
}
}
if len(deps) == 0 {
return nil, nil
}
// Fetch all dependent issues.
ids := make([]string, len(deps))
for i, d := range deps {
ids[i] = d.depID
}
issues, err := GetIssuesByIDsInTx(ctx, tx, ids, nil)
if err != nil {
return nil, fmt.Errorf("get dependents: fetch issues: %w", err)
}
issueMap := make(map[string]*types.Issue, len(issues))
for _, iss := range issues {
issueMap[iss.ID] = iss
}
var results []*types.IssueWithDependencyMetadata
for _, d := range deps {
issue, ok := issueMap[d.depID]
if !ok {
continue
}
results = append(results, &types.IssueWithDependencyMetadata{
Issue: *issue,
DependencyType: types.DependencyType(d.depType),
})
}
return results, nil
}
// GetDependenciesInTx returns issues that the given issueID depends on.
// Queries both dependencies and wisp_dependencies tables.
//
//nolint:gosec // G201: table names come from hardcoded constants
func GetDependenciesInTx(ctx context.Context, tx *sql.Tx, issueID string) ([]*types.Issue, error) {
var ids []string
for _, depTable := range []string{"dependencies", "wisp_dependencies"} {
rows, err := tx.QueryContext(ctx, fmt.Sprintf(
`SELECT %s AS depends_on_id FROM %s WHERE issue_id = ?`, DepTargetExpr, depTable), issueID)
if err != nil {
return nil, fmt.Errorf("get dependencies from %s: %w", depTable, err)
}
for rows.Next() {
var id string
if scanErr := rows.Scan(&id); scanErr != nil {
_ = rows.Close()
return nil, fmt.Errorf("get dependencies: scan: %w", scanErr)
}
ids = append(ids, id)
}
_ = rows.Close()
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("get dependencies: rows from %s: %w", depTable, err)
}
}
if len(ids) == 0 {
return nil, nil
}
return GetIssuesByIDsInTx(ctx, tx, ids, nil)
}
// GetDependentsInTx returns issues that depend on the given issueID.
// Queries both dependencies and wisp_dependencies tables.
//
//nolint:gosec // G201: table names come from hardcoded constants
func GetDependentsInTx(ctx context.Context, tx *sql.Tx, issueID string) ([]*types.Issue, error) {
var ids []string
for _, depTable := range []string{"dependencies", "wisp_dependencies"} {
rows, err := tx.QueryContext(ctx, fmt.Sprintf(
`SELECT issue_id FROM %s WHERE %s = ?`, depTable, DepTargetExpr), issueID)
if err != nil {
return nil, fmt.Errorf("get dependents from %s: %w", depTable, err)
}
for rows.Next() {
var id string
if scanErr := rows.Scan(&id); scanErr != nil {
_ = rows.Close()
return nil, fmt.Errorf("get dependents: scan: %w", scanErr)
}
ids = append(ids, id)
}
_ = rows.Close()
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("get dependents: rows from %s: %w", depTable, err)
}
}
if len(ids) == 0 {
return nil, nil
}
return GetIssuesByIDsInTx(ctx, tx, ids, nil)
}