beads/backend/conformance
Stephanie Jarmak 12b19a6df7
feat(dep): detect cycles through tracks edges (#6148)
* feat(dep): teach bd dep cycles to traverse tracks edges (gc-818bx)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---------

Co-authored-by: sjarmak <t@t.co>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-30 20:20:17 -07:00
..
audit.go feat(storage): public backend contract + conformance suite for out-of-tree backends (bd-h3dib.2) (#5321) 2026-08-03 16:03:11 -07:00
audit_config_metadata_slots_repomtime.go Retire 19 audit cases the role contracts dominate, and say why 9 stay (#5453) 2026-08-08 21:36:14 -07:00
audit_dependencies_readiness.go fix(list): honor --status when combined with --ready (#5924) 2026-09-02 18:12:07 -07:00
audit_issue-lifecycle.go Retire 19 audit cases the role contracts dominate, and say why 9 stay (#5453) 2026-08-08 21:36:14 -07:00
audit_labels-comments-events.go fix(storage): count a wisp's comments in wisp_comments (#5565) (#6709) 2026-09-26 05:49:51 -07:00
audit_molecule_wisp_batch_iter.go wy-a648lq: import wires in-batch regular<->wisp edges instead of dropping them 2026-09-01 06:43:07 -07:00
audit_search-counts-stats.go refactor: delete the dead orphan-handling capability (bd-gwryr) (#5497) 2026-08-09 12:03:18 -07:00
batch_apply_contract.go Add issueops.BatchApplier: one plan, one transaction (#5480) 2026-08-09 06:59:34 -07:00
batch_closer_contract.go Make the conformance obligation true: rewire the dolt_log probes, fix the doc that lied (#5449) 2026-08-08 19:55:20 -07:00
batch_creator_contract.go fix(contracts): JSON contract fixes before 1.3.0 freezes them — string revision tokens, --set-metadata scalar typing, create --json nano timestamps (#6053) 2026-08-29 05:20:27 +00:00
blocked_state.go Pin the is_blocked invariant as a postcondition of the roles that maintain it (#5436) 2026-08-08 11:23:34 -07:00
blocking_annotator_contract.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
bootstrapper_contract.go Assert exactly-one history for a comment, and state the bootstrap split per leg (#5455) 2026-08-08 22:43:13 -07:00
BUILD.bazel test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828) 2026-09-27 08:24:08 -07:00
claim.go Retire 19 audit cases the role contracts dominate, and say why 9 stay (#5453) 2026-08-08 21:36:14 -07:00
claimer_contract.go fix(bd): canonicalize remaining actor==assignee comparisons in claim/heartbeat CAS (ga-v2k49) (#5479) 2026-08-09 17:19:00 -07:00
commenter_contract.go chore: retire a zombie test, drop a dead field, true up two leaf docs (#5492) 2026-08-09 10:42:34 -07:00
conformance.go fix(storage/dolt): stop Transaction.SearchIssues dropping the keyset cursor and eight other filter fields (#5891) 2026-08-21 00:22:46 -07:00
counter_contract.go Retire 19 audit cases the role contracts dominate, and say why 9 stay (#5453) 2026-08-08 21:36:14 -07:00
cross_record_invariant_contract.go Four-leg no-op conformance case for #5898: duplicate dep add and absent dep remove mint no version on any leg (#6650) 2026-09-26 14:48:30 -07:00
cycle_detector_contract.go feat(dep): detect cycles through tracks edges (#6148) 2026-09-30 20:20:17 -07:00
deleter_contract.go Add DeleteRequest.ExpectedVersion: a compare-and-delete on the named row (#5481) 2026-08-09 07:17:54 -07:00
dependency_editor_contract.go Four-leg no-op conformance case for #5898: duplicate dep add and absent dep remove mint no version on any leg (#6650) 2026-09-26 14:48:30 -07:00
dualwrite_history_contract.go Four-leg no-op conformance case for #5898: duplicate dep add and absent dep remove mint no version on any leg (#6650) 2026-09-26 14:48:30 -07:00
edge_reader_contract.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
expected_revision_contract.go Four-leg no-op conformance case for #5898: duplicate dep add and absent dep remove mint no version on any leg (#6650) 2026-09-26 14:48:30 -07:00
graph_counter_contract.go Add issueops.GraphCounter: how many edges, in one named direction (ga-itny5) (#5485) 2026-08-09 11:29:32 -07:00
history_matching.go Make the conformance obligation true: rewire the dolt_log probes, fix the doc that lied (#5449) 2026-08-08 19:55:20 -07:00
importer_contract.go test(conformance): pin the PLANE of the importer's cross-plane edge assertions (#6218) 2026-09-12 06:04:46 -07:00
issue_operations_contract.go test(conformance): de-stage the hard Lifecycle contracts onto the role seam (#5474) 2026-08-09 04:44:29 -07:00
issue_operations_staging.go test(conformance): de-stage the hard Lifecycle contracts onto the role seam (#5474) 2026-08-09 04:44:29 -07:00
journal_contract.go feat(journalops): the mutation journal becomes the third facade namespace (#5552) 2026-08-10 10:58:05 -07:00
lifecycle_close_reopen_contract.go Migrate the lifecycle and issue-operations audit cases onto fixtures that can see the difference (#5472) 2026-08-09 02:13:44 -07:00
lifecycle_create_contract.go fix(contracts): JSON contract fixes before 1.3.0 freezes them — string revision tokens, --set-metadata scalar typing, create --json nano timestamps (#6053) 2026-08-29 05:20:27 +00:00
lifecycle_update_contract.go fix(bd): canonicalize actor==assignee comparisons in unclaim.go and AuthorizeAssigneeTransferWithPools (#5439) 2026-08-09 11:35:01 -07:00
memories_contract.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
metadata_cas_contract.go Add issueops.MetadataCAS: compare-and-set over one metadata key (#5473) 2026-08-09 04:15:34 -07:00
portable.go test(conformance): pin the missing-parent child-counter skip on a real backend (bd-k4bcj) (#5505) 2026-08-09 13:44:54 -07:00
querier_contract.go Migrate the query-family audit cases into role contracts, with fixtures that can see what the old ones could not (#5448) 2026-08-08 19:13:22 -07:00
reader_contract.go feat(httpapi): serve bd list's order with sort on listIssues (#5666) 2026-08-27 09:21:12 -07:00
ready_claimer_contract.go feat(workapi,storage): opt-in Brief projection for the list and ready pages (#5554) 2026-08-10 10:45:23 -07:00
ready_counter_contract.go Migrate the claim-family audit cases into role contracts, including a lease nobody pinned (#5447) 2026-08-08 19:12:48 -07:00
reclaim_scope.go Make the conformance obligation true: rewire the dolt_log probes, fix the doc that lied (#5449) 2026-08-08 19:55:20 -07:00
relations_contract.go feat(issueops): put every issue capability behind one library surface 2026-08-04 12:27:56 -07:00
releaser_contract.go fix: canonicalActor collapses the --/__ axes correctly; claim-verify uses ActorMatches (be-p7dzx, bundled be-vc51) (#5856) 2026-08-19 13:23:35 -07:00
retention_epoch_contract.go Four-leg no-op conformance case for #5898: duplicate dep add and absent dep remove mint no version on any leg (#6650) 2026-09-26 14:48:30 -07:00
role_bundle.go Four-leg no-op conformance case for #5898: duplicate dep add and absent dep remove mint no version on any leg (#6650) 2026-09-26 14:48:30 -07:00
role_bundle_cases.go feat(dep): detect cycles through tracks edges (#6148) 2026-09-30 20:20:17 -07:00
role_bundle_test.go test(bazel): fully green //..., tag taxonomy + docker lane, sharding, test sandbox ceiling (#6871) 2026-09-27 20:19:38 -07:00
role_coverage_gate_test.go Migrate the batch and comment audit cases, and give Importer the contract its report justifies (#5469) 2026-08-09 02:34:17 -07:00
role_coverage_scan_test.go test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828) 2026-09-27 08:24:08 -07:00
search_paging.go Retire 19 audit cases the role contracts dominate, and say why 9 stay (#5453) 2026-08-08 21:36:14 -07:00
stats_reporter_contract.go fix(status): disclose the counted rows bd list will not show (#5763) 2026-09-30 15:44:40 -07:00
sweeper_contract.go feat(purge): live-dependent protection, --wisps-plane selector, hour-precision --older-than, --limit (#6883) 2026-09-28 00:57:24 -07:00
transaction_parity.go fix(storage/dolt): address review follow-ups on Transaction.SearchIssues (#5912) 2026-08-21 06:10:47 -07:00
tree_walker_contract.go Prune each half of a both walk before merging them 2026-08-06 21:46:53 +00:00
version_reconciler_contract.go feat(issueops): put the startup version reconciler behind the VersionReconciler role (bd-gkmft) 2026-08-05 16:35:01 +00:00
versioned_history_wiring_test.go Four-leg no-op conformance case for #5898: duplicate dep add and absent dep remove mint no version on any leg (#6650) 2026-09-26 14:48:30 -07:00
workspaceconfig_contract.go docs: the ext-api-store documentation tranche — post-#5516 auth sweep, wave doc coherence, role checklist refresh (#5545) 2026-08-10 08:05:07 -07:00