From dffcfcecdc2916bf5c7f5737fb8d27b9d6b2cbbf Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Thu, 30 Jul 2026 18:04:24 -0700 Subject: [PATCH] feat(doctor): detect and heal FKs severed on clone-local tables by hard resets (bd-7bpkd) (#5173) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- cmd/bd/doctor.go | 5 + cmd/bd/doctor/agent.go | 12 ++ cmd/bd/doctor/clone_local_fks.go | 50 +++++ cmd/bd/doctor/fix/clone_local_fks.go | 175 +++++++++++++++++ cmd/bd/doctor/fix/clone_local_fks_cgo_test.go | 176 ++++++++++++++++++ cmd/bd/doctor_fix.go | 2 + 6 files changed, 420 insertions(+) create mode 100644 cmd/bd/doctor/clone_local_fks.go create mode 100644 cmd/bd/doctor/fix/clone_local_fks.go create mode 100644 cmd/bd/doctor/fix/clone_local_fks_cgo_test.go diff --git a/cmd/bd/doctor.go b/cmd/bd/doctor.go index c7421f3b6..113066cdd 100644 --- a/cmd/bd/doctor.go +++ b/cmd/bd/doctor.go @@ -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) diff --git a/cmd/bd/doctor/agent.go b/cmd/bd/doctor/agent.go index 099761ad2..a80058c8f 100644 --- a/cmd/bd/doctor/agent.go +++ b/cmd/bd/doctor/agent.go @@ -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", diff --git a/cmd/bd/doctor/clone_local_fks.go b/cmd/bd/doctor/clone_local_fks.go new file mode 100644 index 000000000..6b2872f56 --- /dev/null +++ b/cmd/bd/doctor/clone_local_fks.go @@ -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", + } +} diff --git a/cmd/bd/doctor/fix/clone_local_fks.go b/cmd/bd/doctor/fix/clone_local_fks.go new file mode 100644 index 000000000..467ec36c3 --- /dev/null +++ b/cmd/bd/doctor/fix/clone_local_fks.go @@ -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 +} diff --git a/cmd/bd/doctor/fix/clone_local_fks_cgo_test.go b/cmd/bd/doctor/fix/clone_local_fks_cgo_test.go new file mode 100644 index 000000000..49a2c8c11 --- /dev/null +++ b/cmd/bd/doctor/fix/clone_local_fks_cgo_test.go @@ -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) + } +} diff --git a/cmd/bd/doctor_fix.go b/cmd/bd/doctor_fix.go index 195997e70..80b74020f 100644 --- a/cmd/bd/doctor_fix.go +++ b/cmd/bd/doctor_fix.go @@ -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":