feat(doctor): detect and heal FKs severed on clone-local tables by hard resets (bd-7bpkd) (#5173)

CALL DOLT_RESET('--hard') silently drops EVERY foreign key on every
dolt_ignored table — including FKs whose referenced table is itself
clone-local and untouched by the reset. Enforcement stops, the loss
survives server restarts, and nothing re-links it (all three properties
verified by probe on dolt 2.2.2). Every production hard-reset site
inherits this: flatten/compact squash, merge abort recovery, and the
migration-lock error path — so from the first squash window onward,
orphan rows accumulate indefinitely.

New doctor check "Clone-Local FKs" scans information_schema for the
eight FKs the schema puts on clone-local tables (events + the wisp
auxiliary tables; static spec in fix.CloneLocalFKs) and warns with
orphan counts when any are missing. bd doctor --fix deletes the
orphaned rows (ADD CONSTRAINT validates existing rows, so they go
first) and re-adds each constraint in place — no table rebuild, no
transient tracked-plane table.

The cgo test drives the severance the way production hits it (reset
across a commit that touched issues), asserts all eight FKs drop, heals,
and verifies enforcement returns; a drift guard asserts the static spec
exactly matches a freshly migrated store, so a new clone-local FK added
without a spec entry fails the test instead of silently never healing.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge 2026-07-30 18:04:24 -07:00 • committed by GitHub
commit dffcfcecdc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 420 additions and 0 deletions

View file

@ -859,6 +859,11 @@ func runDiagnostics(path string) doctorResult {
result.Checks = append(result.Checks, orphanedDepsCheck)
// Don't fail overall check for orphaned deps, just warn
// Check 21b: Clone-local FKs severed by hard resets (bd-7bpkd)
cloneLocalFKCheck := convertDoctorCheck(doctor.CheckCloneLocalFKs(path))
result.Checks = append(result.Checks, cloneLocalFKCheck)
// Don't fail overall check for severed clone-local FKs, just warn
// Check 22a: Child→parent dependencies (anti-pattern)
childParentDepsCheck := convertDoctorCheck(doctor.CheckChildParentDependencies(path))
result.Checks = append(result.Checks, childParentDepsCheck)

View file

@ -117,6 +117,7 @@ var agentEnrichers = map[string]enricher{
"Duplicate Issues": enrichDuplicateIssues,
"Test Pollution": enrichTestPollution,
"Orphaned Dependencies": enrichOrphanedDeps,
"Clone-Local FKs": enrichCloneLocalFKs,
"Child-Parent Dependencies": enrichChildParentDeps,
"Classic Artifacts": enrichClassicArtifacts,
"Pending Migrations": enrichPendingMigrations,
@ -459,6 +460,17 @@ func enrichOrphanedDeps(dc DoctorCheck) agentEnrichment {
}
}
func enrichCloneLocalFKs(dc DoctorCheck) agentEnrichment {
return agentEnrichment{
severity: "advisory",
explanation: fmt.Sprintf("Severed clone-local FK(s): %s. A hard reset (flatten/compact squash, merge abort, migration error recovery) silently drops foreign keys from dolt_ignored tables onto the tracked plane; enforcement stays off across server restarts and orphaned rows accumulate until the constraint is re-added.", dc.Message),
observed: dc.Message + "\n" + dc.Detail,
expected: "Every FK on clone-local tables (events, wisp_dependencies, wisp_labels, wisp_comments, wisp_events, wisp_child_counters) present and enforcing",
commands: []string{"bd doctor --fix"},
sourceFiles: []string{"cmd/bd/doctor/clone_local_fks.go:CheckCloneLocalFKs"},
}
}
func enrichChildParentDeps(dc DoctorCheck) agentEnrichment {
return agentEnrichment{
severity: "advisory",

View file

@ -0,0 +1,50 @@
package doctor
import (
"fmt"
"strings"
"github.com/steveyegge/beads/cmd/bd/doctor/fix"
)
// CheckCloneLocalFKs detects clone-local (dolt_ignored) tables whose foreign
// keys into the tracked plane have been severed by a hard reset (bd-7bpkd):
// DOLT_RESET('--hard') swaps the tracked table's backing object and silently
// drops the untracked table's constraint — enforcement stops, the loss
// survives server restarts, and orphan rows accumulate from the first squash
// window onward. The fix deletes the orphans and re-adds each constraint in
// place.
//
// This check does not require CGO: it queries via MySQL wire protocol using
// the same dolt-server connection as the fix package.
func CheckCloneLocalFKs(path string) DoctorCheck {
severed, err := fix.ScanSeveredCloneLocalFKs(path)
if err != nil {
return DoctorCheck{
Name: "Clone-Local FKs",
Status: StatusOK,
Message: "N/A (no database)",
}
}
if len(severed) == 0 {
return DoctorCheck{
Name: "Clone-Local FKs",
Status: StatusOK,
Message: "All clone-local FKs enforcing",
}
}
parts := make([]string, 0, len(severed))
orphans := 0
for _, fk := range severed {
parts = append(parts, fmt.Sprintf("%s.%s (%d orphan(s))", fk.Table, fk.Constraint, fk.Orphans))
orphans += fk.Orphans
}
return DoctorCheck{
Name: "Clone-Local FKs",
Status: StatusWarning,
Message: fmt.Sprintf("%d severed FK(s) on clone-local tables: %s", len(severed), strings.Join(parts, ", ")),
Detail: fmt.Sprintf("A hard reset (squash, merge abort) drops FKs from dolt_ignored tables; %d orphaned row(s) accumulated while enforcement was off", orphans),
Fix: "Run 'bd doctor --fix' to remove orphaned rows and re-link the constraint(s) in place",
}
}

View file

@ -0,0 +1,175 @@
package fix
import (
"database/sql"
"fmt"
)
// CloneLocalFK describes a foreign key held by a clone-local (dolt_ignored,
// working-set-only) table.
//
// bd-7bpkd: CALL DOLT_RESET('--hard') silently DROPS every FK on every
// dolt_ignored table — including FKs whose referenced table is itself
// clone-local and was never touched by the reset (verified on dolt-sql-server
// 2.2.0 and 2.2.2). Enforcement stops, the loss survives server restarts, and
// nothing re-links it. Every production hard-reset site inherits this:
// flatten/compact squash, merge abort recovery, and the migration-lock error
// path. Orphan rows then accumulate until the constraint is re-added.
type CloneLocalFK struct {
Table string
Constraint string
Column string
RefTable string
RefColumn string
}
// CloneLocalFKs lists every foreign key on a clone-local table (all use
// ON DELETE CASCADE ON UPDATE CASCADE). Keep in sync with the migrations that
// define them — main 0005/0042/0062 (events), 0021/0047/0058 (wisp aux), and
// their ignored-plane twins (ignored/0002, ignored/0004, ignored/0019).
// leases, local_metadata, repo_mtimes, and wisps carry no FKs;
// child_counters is tracked-plane (its FK survives resets).
// The cgo test's drift guard asserts this list matches a freshly migrated
// store exactly.
var CloneLocalFKs = []CloneLocalFK{
{Table: "events", Constraint: "fk_events_issue", Column: "issue_id", RefTable: "issues", RefColumn: "id"},
{Table: "wisp_dependencies", Constraint: "fk_wisp_dep_issue", Column: "issue_id", RefTable: "wisps", RefColumn: "id"},
{Table: "wisp_dependencies", Constraint: "fk_wisp_dep_wisp_target", Column: "depends_on_wisp_id", RefTable: "wisps", RefColumn: "id"},
{Table: "wisp_dependencies", Constraint: "fk_wisp_dep_issue_target", Column: "depends_on_issue_id", RefTable: "issues", RefColumn: "id"},
{Table: "wisp_labels", Constraint: "fk_wisp_labels_issue", Column: "issue_id", RefTable: "wisps", RefColumn: "id"},
{Table: "wisp_comments", Constraint: "fk_wisp_comments_issue", Column: "issue_id", RefTable: "wisps", RefColumn: "id"},
{Table: "wisp_events", Constraint: "fk_wisp_events_issue", Column: "issue_id", RefTable: "wisps", RefColumn: "id"},
{Table: "wisp_child_counters", Constraint: "fk_wisp_child_counters_parent", Column: "parent_id", RefTable: "wisps", RefColumn: "id"},
}
// SeveredCloneLocalFK is one severed constraint found by the scan, with the
// number of orphaned rows that accumulated while enforcement was off.
type SeveredCloneLocalFK struct {
CloneLocalFK
Orphans int
}
// ScanSeveredCloneLocalFKs reports which clone-local FKs are missing from the
// live schema. Used by CheckCloneLocalFKs in the doctor package.
func ScanSeveredCloneLocalFKs(path string) ([]SeveredCloneLocalFK, error) {
beadsDir, err := resolvedWorkspaceBeadsDir(path)
if err != nil {
return nil, err
}
db, _, err := openDoltDB(beadsDir)
if err != nil {
return nil, err
}
defer db.Close()
return scanSeveredCloneLocalFKs(db)
}
func scanSeveredCloneLocalFKs(db *sql.DB) ([]SeveredCloneLocalFK, error) {
var severed []SeveredCloneLocalFK
for _, fk := range CloneLocalFKs {
var tables int
if err := db.QueryRow(
`SELECT COUNT(*) FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?`,
fk.Table,
).Scan(&tables); err != nil {
return nil, fmt.Errorf("check %s exists: %w", fk.Table, err)
}
if tables == 0 {
continue
}
var constraints int
if err := db.QueryRow(
`SELECT COUNT(*) FROM information_schema.TABLE_CONSTRAINTS
WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND CONSTRAINT_NAME = ? AND CONSTRAINT_TYPE = 'FOREIGN KEY'`,
fk.Table, fk.Constraint,
).Scan(&constraints); err != nil {
return nil, fmt.Errorf("check %s.%s: %w", fk.Table, fk.Constraint, err)
}
if constraints > 0 {
continue
}
var orphans int
//nolint:gosec // G201: identifiers come from the fixed CloneLocalFKs spec above, not user input.
orphanCount := fmt.Sprintf(
`SELECT COUNT(*) FROM %s t WHERE t.%s IS NOT NULL AND NOT EXISTS (SELECT 1 FROM %s r WHERE r.%s = t.%s)`,
fk.Table, fk.Column, fk.RefTable, fk.RefColumn, fk.Column,
)
if err := db.QueryRow(orphanCount).Scan(&orphans); err != nil {
return nil, fmt.Errorf("count %s orphans: %w", fk.Table, err)
}
severed = append(severed, SeveredCloneLocalFK{CloneLocalFK: fk, Orphans: orphans})
}
return severed, nil
}
// CloneLocalFKEnforcement re-links severed clone-local FKs: for each missing
// constraint it deletes the orphaned rows that accumulated while enforcement
// was off (ADD CONSTRAINT validates existing rows, so they must go first),
// then re-adds the constraint in place. Verified on dolt 2.2.2: the re-added
// FK resolves against the current tracked root and enforces again.
func CloneLocalFKEnforcement(path string, verbose bool) error {
beadsDir, err := resolvedWorkspaceBeadsDir(path)
if err != nil {
return err
}
db, cfg, err := openDoltDB(beadsDir)
if err != nil {
fmt.Printf(" Clone-local FK fix skipped (%v)\n", err)
return nil
}
defer db.Close()
if skip, err := guardFixTarget("Clone-local FK fix", db, beadsDir, cfg); skip {
return err
}
return relinkSeveredCloneLocalFKs(db, verbose)
}
// relinkSeveredCloneLocalFKs is the core of CloneLocalFKEnforcement, split out
// so tests can drive it against a database handle directly.
func relinkSeveredCloneLocalFKs(db *sql.DB, verbose bool) error {
severed, err := scanSeveredCloneLocalFKs(db)
if err != nil {
return err
}
if len(severed) == 0 {
fmt.Println(" ✓ All clone-local FKs present")
return nil
}
for _, fk := range severed {
if fk.Orphans > 0 {
//nolint:gosec // G201: identifiers come from the fixed CloneLocalFKs spec, not user input.
deleteOrphans := fmt.Sprintf(
`DELETE FROM %s WHERE %s IS NOT NULL AND NOT EXISTS (SELECT 1 FROM %s r WHERE r.%s = %s.%s)`,
fk.Table, fk.Column, fk.RefTable, fk.RefColumn, fk.Table, fk.Column,
)
result, err := db.Exec(deleteOrphans)
if err != nil {
return fmt.Errorf("delete %s orphans: %w", fk.Table, err)
}
if verbose {
removed, _ := result.RowsAffected()
fmt.Printf(" Removed %d orphaned row(s) from %s\n", removed, fk.Table)
}
}
//nolint:gosec // G201: identifiers come from the fixed CloneLocalFKs spec, not user input.
addConstraint := fmt.Sprintf(
`ALTER TABLE %s ADD CONSTRAINT %s FOREIGN KEY (%s) REFERENCES %s (%s) ON DELETE CASCADE ON UPDATE CASCADE`,
fk.Table, fk.Constraint, fk.Column, fk.RefTable, fk.RefColumn,
)
if _, err := db.Exec(addConstraint); err != nil {
return fmt.Errorf("re-add %s.%s: %w", fk.Table, fk.Constraint, err)
}
fmt.Printf(" ✓ Re-linked %s.%s (%d orphaned row(s) removed)\n", fk.Table, fk.Constraint, fk.Orphans)
}
return nil
}

View file

@ -0,0 +1,176 @@
//go:build cgo
package fix
import (
"context"
"crypto/sha256"
"encoding/hex"
"fmt"
"os"
"path/filepath"
"strings"
"testing"
"time"
"github.com/steveyegge/beads/internal/storage/dolt"
"github.com/steveyegge/beads/internal/types"
)
// bd-7bpkd: DOLT_RESET('--hard') swaps the tracked issues table's backing
// object and silently drops the FKs that clone-local (dolt_ignored) tables
// hold on it — enforcement stops, orphans accumulate, and nothing re-links
// the constraint (a server restart does not). This drives the severance the
// way production hits it (reset across a commit that touched issues) and
// verifies scan → heal → enforcement restored.
func TestRelinkSeveredCloneLocalFKs_AfterHardReset(t *testing.T) {
port := fixTestServerPort()
if port == 0 {
t.Skip("Dolt test server not available, skipping")
}
tmpDir := t.TempDir()
ctx := context.Background()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatalf("failed to create .beads: %v", err)
}
h := sha256.Sum256([]byte(t.Name() + fmt.Sprintf("%d", time.Now().UnixNano())))
dbName := "fixtest_" + hex.EncodeToString(h[:6])
store, err := dolt.New(ctx, &dolt.Config{
Path: filepath.Join(beadsDir, "beads.db"),
ServerHost: "127.0.0.1",
ServerPort: port,
Database: dbName,
CreateIfMissing: true,
})
if err != nil {
t.Skipf("skipping: Dolt not available: %v", err)
}
t.Cleanup(func() {
store.Close()
dropFixTestDatabase(dbName, port)
})
if err := store.SetConfig(ctx, "issue_prefix", "bd"); err != nil {
t.Fatalf("failed to set issue_prefix: %v", err)
}
issue := &types.Issue{Title: "anchor", Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask}
if err := store.CreateIssue(ctx, issue, "test"); err != nil {
t.Fatalf("failed to create issue: %v", err)
}
db := store.UnderlyingDB()
exec := func(query string, args ...any) {
t.Helper()
if _, err := db.ExecContext(ctx, query, args...); err != nil {
t.Fatalf("exec %q: %v", query, err)
}
}
exec("CALL DOLT_ADD('-A')")
exec("CALL DOLT_COMMIT('-m', 'baseline', '--allow-empty')")
var baseline string
if err := db.QueryRowContext(ctx, "SELECT HASHOF('HEAD')").Scan(&baseline); err != nil {
t.Fatalf("capture baseline: %v", err)
}
// A second commit that touches issues, so the reset below swaps its
// backing object (a no-op reset does not sever anything).
second := &types.Issue{Title: "swapped away", Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask}
if err := store.CreateIssue(ctx, second, "test"); err != nil {
t.Fatalf("failed to create second issue: %v", err)
}
// The store may have auto-committed the write already; --allow-empty keeps
// this from failing either way. What matters is that HEAD's issues content
// differs from baseline so the reset below swaps the table's backing object.
exec("CALL DOLT_ADD('-A')")
exec("CALL DOLT_COMMIT('-m', 'second', '--allow-empty')")
if severed, err := scanSeveredCloneLocalFKs(db); err != nil {
t.Fatalf("pre-reset scan: %v", err)
} else if len(severed) != 0 {
t.Fatalf("pre-reset scan = %v, want none severed", severed)
}
// Drift guard: the static CloneLocalFKs spec must cover exactly the FKs a
// freshly migrated store puts on clone-local tables. A new FK added by a
// migration without a spec entry would silently never be healed.
rows, err := db.QueryContext(ctx, `
SELECT tc.TABLE_NAME, tc.CONSTRAINT_NAME
FROM information_schema.TABLE_CONSTRAINTS tc
WHERE tc.TABLE_SCHEMA = DATABASE()
AND tc.CONSTRAINT_TYPE = 'FOREIGN KEY'
AND (tc.TABLE_NAME = 'events' OR tc.TABLE_NAME = 'leases' OR tc.TABLE_NAME = 'local_metadata'
OR tc.TABLE_NAME = 'repo_mtimes' OR tc.TABLE_NAME = 'wisps' OR tc.TABLE_NAME LIKE 'wisp\_%')`)
if err != nil {
t.Fatalf("enumerate clone-local FKs: %v", err)
}
defer rows.Close()
live := map[string]bool{}
for rows.Next() {
var table, constraint string
if err := rows.Scan(&table, &constraint); err != nil {
t.Fatalf("scan constraint row: %v", err)
}
live[table+"."+constraint] = true
}
if err := rows.Err(); err != nil {
t.Fatalf("constraint rows: %v", err)
}
spec := map[string]bool{}
for _, fk := range CloneLocalFKs {
spec[fk.Table+"."+fk.Constraint] = true
if !live[fk.Table+"."+fk.Constraint] {
t.Errorf("spec FK %s.%s not present on a freshly migrated store", fk.Table, fk.Constraint)
}
}
for key := range live {
if !spec[key] {
t.Errorf("clone-local FK %s exists in a fresh store but is missing from CloneLocalFKs — it would never be healed", key)
}
}
if t.Failed() {
t.FailNow()
}
exec("CALL DOLT_RESET('--hard', ?)", baseline)
severed, err := scanSeveredCloneLocalFKs(db)
if err != nil {
t.Fatalf("post-reset scan: %v", err)
}
if len(severed) != len(CloneLocalFKs) {
t.Fatalf("post-reset scan found %d severed FK(s) (%v), want all %d", len(severed), severed, len(CloneLocalFKs))
}
// Enforcement is off: an orphan audit row goes straight in.
exec("INSERT INTO events (id, issue_id, event_type, actor) VALUES ('11111111-1111-1111-1111-111111111111', 'bd-no-such-issue', 'created', 'test')")
if err := relinkSeveredCloneLocalFKs(db, true); err != nil {
t.Fatalf("relink: %v", err)
}
if severed, err := scanSeveredCloneLocalFKs(db); err != nil {
t.Fatalf("post-heal scan: %v", err)
} else if len(severed) != 0 {
t.Fatalf("post-heal scan = %v, want none severed", severed)
}
var orphans int
if err := db.QueryRowContext(ctx,
"SELECT COUNT(*) FROM events WHERE issue_id = 'bd-no-such-issue'").Scan(&orphans); err != nil {
t.Fatalf("count orphans: %v", err)
}
if orphans != 0 {
t.Fatalf("orphan rows after heal = %d, want 0", orphans)
}
// The re-added FK resolves against the current root and enforces again.
_, err = db.ExecContext(ctx,
"INSERT INTO events (id, issue_id, event_type, actor) VALUES ('22222222-2222-2222-2222-222222222222', 'bd-still-no-issue', 'created', 'test')")
if err == nil || !strings.Contains(strings.ToLower(err.Error()), "foreign key") {
t.Fatalf("bogus insert after heal: err = %v, want foreign key violation", err)
}
}

View file

@ -324,6 +324,8 @@ func applyFixList(path string, fixes []doctorCheck) {
err = fix.CrossTableDuplicates(path, doctorVerbose)
case "Orphaned Dependencies":
err = fix.OrphanedDependencies(path, doctorVerbose)
case "Clone-Local FKs":
err = fix.CloneLocalFKEnforcement(path, doctorVerbose)
case "Dependency Keys":
err = fix.DependencyKeys(path, doctorVerbose)
case "Blocked State":