diff --git a/CHANGELOG.md b/CHANGELOG.md index fe4afbbd0..2957ab1b4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- **`bd sync` — one verb for the federation loop** (wy-jpd3.4). Every + multi-machine beads deployment hand-rolls the same sequence in shell; this + ships it. `bd sync [--remote ] [--attempts N]` pulls, checks for merge + conflicts, runs the full `is_blocked` recompute, and pushes — retrying a + bounded number of times (default 3) when another replica wins the push race. + Two properties are the point of the verb. Conflicts are detected + **positively**, from the merge's own captured conflict rows and from + `dolt_conflicts`, never inferred from the pull's exit status: a pull fails for + plenty of reasons that are not conflicts, and a settled merge that *is* + conflicted aborts and leaves `dolt_conflicts` empty, so an exit-status guess + invents phantom conflicts and misses real ones. And a conflict sync cannot + settle is **never** resolved by picking a side: it halts before recomputing or + pushing and exits 2, with no `--strategy`-style override to make it do + otherwise. (The pull underneath still auto-settles the convergent classes it + always has — machine-local metadata, audit-only dependency rows, LWW on issue + cells; anything past those halts.) The halt message reports which state the + halt left behind, read from which detection source fired rather than assumed: + the SQL pull route aborts the merge and restores the working set, while the + CLI/git-protocol route deliberately leaves the conflict rows live. The + recompute between pull and push is not bookkeeping either: `is_blocked` is + denormalized, so a merge that brings in a dependency edge from another replica + leaves `bd ready` stale until it runs. It runs unconditionally, on every + attempt — `RecomputeAllBlocked` is precisely the repair that does not depend + on a merge advancing HEAD, so gating it on "did anything merge" would mean a + column left stale by a hand-resolved conflict (a state `bd sync` creates by + exiting 2) is never repaired again while every tick reports success. + Exit codes are the machine contract, so a sync timer can branch without + parsing output: `0` synced, `1` error, `2` merge conflict (halted, nothing + pushed), `3` push-race retries exhausted (transient — retry next tick). + `--json` reports the outcome as `{"status", "attempts", "conflicts", + "conflicts_live", "rows_corrected", "pushed"}` on every non-error exit; exit 1 + emits bd's standard `{"error": ...}` envelope. A confirmed-no-remote rig exits + 0 with the same guidance `bd dolt push` prints; `dolt.local-only` and + `no-push` are honored. + - **`bd reclaim` scope filters** (wy-jpd3.3). `bd reclaim` gained `--label` / `--label-any` / `--exclude-label` / `--assignee` / `--id`, mirroring the claim-side label surface (`bd ready --claim`), so a supervisor diff --git a/cmd/bd/dolt.go b/cmd/bd/dolt.go index 294c782fa..5beaaaec8 100644 --- a/cmd/bd/dolt.go +++ b/cmd/bd/dolt.go @@ -192,6 +192,16 @@ func isConfirmedNoRemote(ctx context.Context, st remoteLister, err error) bool { if !isRemoteNotFoundErr(err) { return false } + return hasNoRemoteConfigured(ctx, st) +} + +// hasNoRemoteConfigured is the structural half of isConfirmedNoRemote: the +// positive proof that this rig really has no remote, independent of how the +// failure worded itself. It is what actually makes an exit-0 skip safe, so a +// caller with a different (broader) error classification — `bd sync`, which +// runs on a timer and must not fail every tick on a solo rig — can reuse the +// proof without loosening it. +func hasNoRemoteConfigured(ctx context.Context, st remoteLister) bool { remotes, listErr := st.ListRemotes(ctx) if listErr != nil || len(remotes) > 0 { return false diff --git a/cmd/bd/sync.go b/cmd/bd/sync.go new file mode 100644 index 000000000..171344e16 --- /dev/null +++ b/cmd/bd/sync.go @@ -0,0 +1,628 @@ +package main + +import ( + "context" + "errors" + "fmt" + "os" + "regexp" + "sort" + + "github.com/spf13/cobra" + "github.com/steveyegge/beads/internal/config" + "github.com/steveyegge/beads/internal/metrics" + "github.com/steveyegge/beads/internal/storage" + "github.com/steveyegge/beads/internal/storage/versioncontrolops" +) + +// Exit codes for `bd sync`, chosen so a sync timer can branch on the outcome +// without parsing output (wy-jpd3.4). The reference deployment this verb +// generalizes — a two-machine beads federation on a 60-second timer — needs +// exactly three distinctions: it worked, a human must resolve a merge conflict, +// or another replica kept winning the push race and the next tick should just +// try again. +// +// 0 synced (or nothing to do) +// 1 error (transport, auth, storage — the usual bd failure code) +// 2 merge conflict; the sync halted and nothing was pushed. NOT auto-resolved. +// 3 push-race retries exhausted; transient, retry on the next tick. +const ( + ExitSyncConflict = 2 + ExitSyncRetriesExhausted = 3 +) + +// defaultSyncAttempts bounds the pull->push cycle. Three is the production +// default of the reference implementation: a push race resolves on the first +// retry in practice, and an unbounded loop under a busy fleet never converges. +const defaultSyncAttempts = 3 + +// Sync outcome statuses, also the "status" value in --json output. +const ( + syncStatusOK = "ok" + syncStatusConflict = "conflict" + syncStatusRetriesExhausted = "retries-exhausted" + syncStatusDisabled = "disabled" + syncStatusNoRemote = "no-remote" +) + +// syncOutcome is one run of the sync loop. +type syncOutcome struct { + Status string `json:"status"` + Attempts int `json:"attempts"` + Conflicts []string `json:"conflicts,omitempty"` + // ConflictsPreexisting distinguishes conflicts that were already live in + // the working set when sync started (an earlier halted sync or a hand-run + // merge) from ones this run's pull surfaced. + ConflictsPreexisting bool `json:"conflicts_preexisting,omitempty"` + // ConflictsLive reports whether the conflicts are sitting in the working + // set right now rather than having been aborted away. It is read from + // which detection source fired, never assumed: the SQL pull route aborts a + // conflicted merge and restores the working set, while the CLI/git-protocol + // route deliberately leaves the conflict rows live for the operator. + ConflictsLive bool `json:"conflicts_live,omitempty"` + RowsCorrected int `json:"rows_corrected"` + // Pulled reports whether an earlier attempt in this run already completed a + // pull and is_blocked repair, which makes "this run touched nothing" untrue + // on a later attempt's conflict. + Pulled bool `json:"pulled,omitempty"` + Pushed bool `json:"pushed"` + PushSkipped bool `json:"push_skipped,omitempty"` + LastPushError string `json:"last_push_error,omitempty"` +} + +// syncOps is the store surface the loop drives, injected as functions so the +// loop's control flow (the part with the interesting failure modes) is testable +// without a live Dolt remote. +type syncOps struct { + // pull merges the remote into the local branch. It returns the conflicted + // table names the merge captured, if any — see runSyncLoop's property (1). + pull func(context.Context) ([]string, error) + // conflicts positively reports live merge conflicts (dolt_conflicts). + conflicts func(context.Context) ([]string, error) + // recompute runs the full is_blocked recompute and returns rows corrected. + recompute func(context.Context) (int, error) + // push publishes local commits to the remote. + push func(context.Context) error + // progress reports a step to the operator; may be nil. + progress func(format string, args ...interface{}) +} + +func (o syncOps) report(format string, args ...interface{}) { + if o.progress != nil { + o.progress(format, args...) + } +} + +// runSyncLoop is the whole federation loop: pull -> positive conflict check -> +// recompute-blocked -> push, retrying a bounded number of times when another +// replica wins the push race. +// +// Two properties are load-bearing and are why this is not just three shell +// lines: +// +// 1. Conflicts are detected POSITIVELY — from structured conflict data, never +// inferred from the pull's exit status. A pull fails for plenty of reasons +// that are not conflicts, and it can also leave conflicts behind without +// failing, so an exit-status guess both invents phantom conflicts and +// misses real ones. Two structured sources are consulted per attempt, and +// either one firing means conflict: +// +// a. the conflicts the merge itself captured — the settle pass aborts a +// merge it cannot auto-resolve and hands back a MergeConflictsError +// holding the conflict rows it read BEFORE the abort; +// b. live rows in dolt_conflicts, which is what a conflict left behind by +// some earlier operation (a hand-run merge, a halted sync) looks like. +// +// Source (a) is why the check cannot just be a dolt_conflicts query: by +// the time a conflicted pull returns, its merge has been aborted and the +// working set restored, so dolt_conflicts is empty again. +// +// 2. Conflicts are NEVER auto-resolved here. The loop halts before recomputing +// or pushing and reports the conflict as a distinct exit code, leaving the +// divergence for an operator. A sync timer that silently picks a side loses +// work on a schedule. +// +// The recompute between pull and push is not optional bookkeeping: is_blocked +// is denormalized, and a merge that brings in a dependency edge from another +// replica leaves it stale, so `bd ready` silently hides or surfaces the wrong +// work until someone repairs it. +// +// It runs UNCONDITIONALLY, on every attempt. That is deliberate, and it is the +// second thing about this loop that looks like it wants an optimization and +// must not get one. RecomputeAllBlocked is specifically the repair that does +// NOT depend on a merge advancing HEAD (bd-6dnrw.37): it is what recovers an +// is_blocked column left stale by a post-merge recompute that failed after its +// merge committed, or by a conflicted pull an operator resolved BY HAND. Gating +// it on "did this pull merge anything" re-imposes the exact condition it exists +// to escape, and sync manufactures that state itself — it exits 2 on a +// conflict, the operator resolves by hand, and from then on no tick merges +// anything, so a gated repair would never run again while every tick reports +// success. HEAD is also the wrong instrument for the question even when the +// question is right: the pull's own pre-merge auto-commit (GH#2474) moves HEAD +// for purely local dirty state, and an auto-resolved or cascade-repaired merge +// can land in the working set without moving it at all (bd-6dnrw.39). Anyone +// revisiting the cost of this pass must start from storage.StateHasher and the +// pending-recompute marker, not from HEAD. +// +// Returns (outcome, nil) for every outcome the caller maps to an exit code, and +// (outcome, err) only for genuine failures (exit 1). +func runSyncLoop(ctx context.Context, ops syncOps, maxAttempts int) (*syncOutcome, error) { + if maxAttempts < 1 { + maxAttempts = 1 + } + out := &syncOutcome{Status: syncStatusOK} + + // Pre-flight. A previous halted sync leaves its conflicts live, and Dolt + // refuses to merge over them — without this check that shows up as an + // opaque pull failure (exit 1) instead of the conflict it actually is. + preConflicts, err := ops.conflicts(ctx) + if err != nil { + return out, fmt.Errorf("conflict check: %w", err) + } + if len(preConflicts) > 0 { + out.Status = syncStatusConflict + out.Conflicts = preConflicts + out.ConflictsPreexisting = true + // These came from the live conflict rows by definition, so a consumer + // asking "is this database conflicted right now" gets a straight yes. + out.ConflictsLive = true + return out, nil + } + + for attempt := 1; attempt <= maxAttempts; attempt++ { + // A push race re-enters the loop; honor cancellation between attempts + // so ^C or a timer's deadline is not swallowed by the retry budget. + if err := ctx.Err(); err != nil { + return out, err + } + out.Attempts = attempt + ops.report("pull (attempt %d/%d)", attempt, maxAttempts) + + merged, pullErr := ops.pull(ctx) + + // Positive conflict check, run whether or not the pull reported an + // error, and unioned with what the merge itself captured — see + // property (1) above. + live, conflictErr := ops.conflicts(ctx) + if conflicts := unionTables(merged, live); len(conflicts) > 0 { + out.Status = syncStatusConflict + out.Conflicts = conflicts + // Which source fired decides what the operator is told about the + // state of the database, and the two answers are opposites. Live + // rows mean the conflict is sitting in the working set right now: + // that is what the CLI/git-protocol pull route leaves behind, since + // it deliberately does not abort for the operator (see + // finishCLIPull). Captured-only means the settle pass aborted the + // merge and restored the working set. Guessing either way sends the + // operator looking in the wrong place. + out.ConflictsLive = len(live) > 0 + return out, nil + } + if pullErr != nil { + return out, fmt.Errorf("pull: %w", pullErr) + } + if conflictErr != nil { + return out, fmt.Errorf("conflict check: %w", conflictErr) + } + + ops.report("recompute-blocked") + corrected, err := ops.recompute(ctx) + if err != nil { + return out, fmt.Errorf("recompute-blocked: %w", err) + } + out.RowsCorrected += corrected + + // From here on this run has completed a pull and an is_blocked repair, + // so a conflict on a LATER attempt cannot describe itself as a run that + // touched nothing. + out.Pulled = true + + ops.report("push") + pushErr := ops.push(ctx) + if pushErr == nil { + out.Status = syncStatusOK + out.Pushed = true + out.LastPushError = "" + return out, nil + } + if !isPushRaceErr(pushErr) { + return out, fmt.Errorf("push: %w", pushErr) + } + // Another replica pushed between our merge and our push, so the remote + // genuinely moved: loop back to pull and pick up its commits. Anything + // that is not a fast-forward race cannot converge by retrying and was + // returned above. + out.LastPushError = pushErr.Error() + ops.report("push race (non-fast-forward) — re-pulling and retrying") + } + + out.Status = syncStatusRetriesExhausted + return out, nil +} + +// pushRacePattern matches the ways a push fails because the remote moved. Kept +// as a message match because the rejection arrives as an untyped error, and +// deliberately narrow: it matches *race signatures* rather than the word +// "rejected". All three routes a real race travels are covered: +// +// - the SQL procedure says the branch "is behind its remote counterpart"; +// - the CLI route folds git's `! [rejected] ... (non-fast-forward)` in; +// - the git-blobstore layer behind `git+*` remotes pushes with +// --force-with-lease, and a lost lease reads as `(stale info)`, +// `(fetch first)`, or "the remote contains work that you do not have". +// +// A bare "rejected" is NOT enough. A protected branch or a declining +// pre-receive hook also rejects, permanently; treating that as a race means a +// sync timer burns its whole attempt budget every tick and reports exit 3 +// ("transient, retry next tick") forever, never surfacing the failure as the +// error it is. +var pushRacePattern = regexp.MustCompile( + `(?i)behind|fast.?forward|not\s+(an\s+)?ancestor|stale\s+info|fetch\s+first|contains\s+work\s+that\s+you\s+do\s+not\s+have`) + +// isPushRaceErr reports whether a push failed because the remote moved under us +// — the one push failure that retrying can fix. +// +// Hard divergence (no common ancestor, or an ancestor primary-key mismatch) is +// explicitly NOT a race: those messages can contain "fast-forward"-adjacent +// wording, and retrying them burns the whole attempt budget on an operation +// that can never converge. They fall through to the generic error path, which +// prints the existing recovery guidance. +func isPushRaceErr(err error) bool { + if err == nil { + return false + } + if isDivergedHistoryErr(err) || isAncestorPKMismatchErr(err) { + return false + } + return pushRacePattern.MatchString(err.Error()) +} + +// bareNoRemotePattern matches Dolt's bare "no remote" wording. `bd dolt push` +// and `bd dolt pull` classify only the "remote ... not found" phrasing, but a +// default-remote fetch on a rig that never configured one fails with +// `Error 1105: no remote` instead, which that phrasing misses. +var bareNoRemotePattern = regexp.MustCompile(`(?i)\bno remote\b`) + +// isNoRemoteConfiguredErr reports whether a sync failure *sounds* like the +// benign "no remote configured" case. It is a strict superset of +// isRemoteNotFoundErr because sync is a timer verb: a solo rig that ran +// `bd init` and never added a remote would otherwise fail on every tick with a +// raw Dolt error code, where `bd dolt push` exits 0. The widening is safe only +// because it is a hint, never the decision — hasNoRemoteConfigured must +// independently prove the remotes are empty before anything exits 0, so a +// deleted remote-side repo or a typoed remote name (both of which have a +// remote configured) still fails loudly. +func isNoRemoteConfiguredErr(err error) bool { + if err == nil { + return false + } + return isRemoteNotFoundErr(err) || bareNoRemotePattern.MatchString(err.Error()) +} + +// classifyPullError splits a pull failure into the conflicts the merge itself +// captured and the residual error. +// +// The settle pass aborts a merge it will not auto-resolve and restores the +// working set, so dolt_conflicts is empty again by the time anyone could query +// it; the conflict rows it read pre-abort ride back inside the error instead +// (bd-578h9.15). Reading them here is what makes the sync loop's conflict +// detection positive rather than an exit-status guess, and it is the same +// contract PullFrom implements. +func classifyPullError(err error) ([]string, error) { + var mce *versioncontrolops.MergeConflictsError + if errors.As(err, &mce) { + // A conflict error carrying no conflict rows would otherwise vanish + // here and let the loop recompute and push on top of a failed merge. + // Both construction sites guard against it today; this keeps the + // invariant enforced at the consuming end too. + if tables := conflictTables(mce.Conflicts); len(tables) > 0 { + return tables, nil + } + return nil, err + } + return nil, err +} + +// unionTables merges two conflicted-table lists, de-duplicated and sorted. +func unionTables(a, b []string) []string { + if len(a) == 0 && len(b) == 0 { + return nil + } + seen := make(map[string]bool, len(a)+len(b)) + var out []string + for _, list := range [][]string{a, b} { + for _, name := range list { + if seen[name] { + continue + } + seen[name] = true + out = append(out, name) + } + } + sort.Strings(out) + return out +} + +// conflictTables reports the distinct table names with live conflicts, sorted +// for stable output. +func conflictTables(conflicts []storage.Conflict) []string { + seen := make(map[string]bool, len(conflicts)) + var tables []string + for _, c := range conflicts { + name := c.Field + if name == "" { + name = "(unknown)" + } + if seen[name] { + continue + } + seen[name] = true + tables = append(tables, name) + } + sort.Strings(tables) + return tables +} + +var syncCmd = &cobra.Command{ + Use: "sync", + GroupID: "sync", + Short: "Pull, check for conflicts, repair is_blocked, and push (the federation loop)", + Long: `Run one full synchronization cycle against the Dolt remote. + +This is the loop every multi-machine beads deployment otherwise hand-rolls in +shell: + + 1. pull from the remote + 2. check for merge conflicts POSITIVELY, from the merge's own conflict rows + and from Dolt's conflict tables — never inferred from the pull's exit + status, which is not a trustworthy conflict signal in either direction + 3. recompute the denormalized is_blocked flag, so dependency edges merged in + from another replica do not leave 'bd ready' stale + 4. push, retrying a bounded number of times when another replica wins the + push race + +Conflicts sync cannot resolve safely are NEVER auto-resolved: it halts before +recomputing or pushing and exits 2, and repeated runs keep halting the same way +until an operator resolves the divergence. (The pull underneath does auto-settle +the conflict classes it can settle convergently — machine-local metadata, +audit-only dependency rows, and last-write-wins on issue cells. Anything beyond +those halts here.) Whether the halted merge was aborted or left live in the +working set depends on the pull route, so the halt message reports which. + +Exit codes (a sync timer can branch on these without parsing output): + + 0 synced, or nothing to do + 1 error (transport, auth, storage) + 2 merge conflict — halted, nothing pushed, resolve it by hand + 3 push-race retries exhausted — transient, retry on the next tick + +This is not 'bd federation sync', which syncs with named peer towns and takes a +--strategy ours|theirs to resolve whatever conflicts it meets. 'bd sync' targets +the configured remote and has no such switch: what it cannot settle, it halts on. + +Examples: + bd sync # sync with the default remote + bd sync --remote mini # sync with a specific remote + bd sync --attempts 5 # allow more push-race retries + bd sync --json # machine-parseable outcome`, + SilenceUsage: true, + SilenceErrors: true, + RunE: runSyncCommand, +} + +func init() { + syncCmd.Flags().String("remote", "", "Sync with a specific named remote instead of the default") + syncCmd.Flags().Int("attempts", defaultSyncAttempts, "Maximum pull/push attempts before reporting a push race (exit 3)") + rootCmd.AddCommand(syncCmd) +} + +func runSyncCommand(cmd *cobra.Command, _ []string) error { + if usesProxiedServer() { + return HandleErrorRespectJSON("sync is not supported in proxied-server mode") + } + CheckReadonly("sync") + + evt := metrics.NewCommandEvent("sync") + defer func() { + if c := metrics.Global(); c != nil { + c.CloseEventAndAdd(evt) + } + }() + + if isDoltLocalOnly() { + if jsonOutput { + return outputJSON(&syncOutcome{Status: syncStatusDisabled}) + } + fmt.Println("Remote sync is disabled for this project (dolt.local-only=true).") + fmt.Println("To re-enable remote sync: bd config unset dolt.local-only") + return nil + } + + attempts, _ := cmd.Flags().GetInt("attempts") + if attempts < 1 { + return HandleErrorRespectJSON("--attempts must be at least 1 (got %d)", attempts) + } + remote, _ := cmd.Flags().GetString("remote") + + st := getStore() + if st == nil { + return HandleErrorRespectJSON("no store available") + } + recomputer, ok := storage.UnwrapStore(st).(storage.BlockedRecomputer) + if !ok { + return HandleErrorRespectJSON("storage backend does not support is_blocked recompute") + } + + // A no-push rig still wants the pull and the recompute; only the publish + // step is off. Reporting that as a push failure would make every tick of a + // local-only mirror look broken. + noPush := config.GetBool("no-push") + + ops := syncOps{ + pull: func(ctx context.Context) ([]string, error) { + var err error + if remote != "" { + err = st.PullRemote(ctx, remote) + } else { + err = st.Pull(ctx) + } + return classifyPullError(err) + }, + conflicts: func(ctx context.Context) ([]string, error) { + cs, err := st.GetConflicts(ctx) + if err != nil { + return nil, err + } + return conflictTables(cs), nil + }, + recompute: func(ctx context.Context) (int, error) { + return recomputer.RecomputeAllBlocked(ctx) + }, + push: func(ctx context.Context) error { + if noPush { + return nil + } + if remote != "" { + return st.PushRemote(ctx, remote, false) + } + return st.Push(ctx) + }, + } + // Per-step progress is the non-essential output -q exists to silence: this + // verb's whole point is running on a short timer. + if !jsonOutput && !isQuiet() { + ops.progress = func(format string, args ...interface{}) { + fmt.Printf("sync: "+format+"\n", args...) + } + } + + out, err := runSyncLoop(rootCtx, ops, attempts) + if noPush && out.Status == syncStatusOK { + out.Pushed = false + out.PushSkipped = true + } + if err != nil { + // A rig with no remote at all is the benign solo case the dolt verbs + // already exit 0 on — only when the emptiness is *confirmed*, and only + // on the default-remote path: an explicitly named remote that does not + // exist is a misconfiguration and stays an error. + if remote == "" && isNoRemoteConfiguredErr(err) && hasNoRemoteConfigured(rootCtx, st) { + if jsonOutput { + return outputJSON(&syncOutcome{Status: syncStatusNoRemote}) + } + printNoRemoteGuidance() + return nil + } + exitErr := HandleErrorRespectJSON("sync failed: %v", err) + if !jsonOutput { + printSyncErrorGuidance(remote, err) + } + return exitErr + } + + if jsonOutput { + if jerr := outputJSON(out); jerr != nil { + return HandleError("%v", jerr) + } + } else { + printSyncOutcome(out, noPush) + } + + switch out.Status { + case syncStatusConflict: + return &exitError{Code: ExitSyncConflict} + case syncStatusRetriesExhausted: + return &exitError{Code: ExitSyncRetriesExhausted} + default: + return nil + } +} + +// printSyncErrorGuidance reuses the recovery guidance the dolt push/pull verbs +// print, so a failed sync is as actionable as the hand-rolled loop it replaces. +// The classifiers match on the message, so they still fire through the step +// wrapping runSyncLoop adds. +func printSyncErrorGuidance(remote string, err error) { + switch { + case isAncestorPKMismatchErr(err): + printAncestorPKMismatchGuidance(err) + case isDivergedHistoryErr(err): + printDivergedHistoryGuidance("sync") + case remote != "" && isRemoteNotFoundErr(err): + fmt.Fprintf(os.Stderr, "\nRemote %q is not configured.\n", remote) + fmt.Fprintln(os.Stderr, "Use 'bd dolt remote add ' to add it.") + fmt.Fprintln(os.Stderr, "Use 'bd dolt remote list' to see configured remotes.") + } +} + +// syncConflictMessage renders the operator-facing halt report for a conflicted +// sync. It is a pure function of the outcome because the three cases it +// distinguishes are easy to describe wrongly, and a wrong description here is +// worse than none: an operator who is told "nothing was merged" will not go +// looking for the merge commit that is in fact sitting in the local history, +// and one who is told the working set was restored will not go looking for the +// live conflict rows that are in fact blocking every subsequent merge. +func syncConflictMessage(out *syncOutcome) []string { + lines := []string{"Error: merge conflict — sync halted, nothing pushed."} + for _, table := range out.Conflicts { + lines = append(lines, fmt.Sprintf(" conflicted table: %s", table)) + } + lines = append(lines, "Conflicts sync cannot resolve safely are never auto-resolved.") + + // First: is the database conflicted RIGHT NOW, or was the conflicted merge + // aborted away? This is the part an operator acts on, and both answers are + // real — which one applies depends on the pull route, not on luck. + switch { + case out.ConflictsPreexisting: + lines = append(lines, + "This replica was ALREADY in a conflicted state before this run: the conflict rows", + "above are live in the working set, left by an earlier halted sync or a hand-run", + "merge. Nothing was pulled, merged, or pushed this run. Resolve the live conflict", + "before sync can make progress — Dolt refuses to merge over an unresolved one.") + case out.ConflictsLive: + lines = append(lines, + "The conflict rows above are LIVE in the working set — this pull route leaves them", + "in place for you rather than aborting. The database is conflicted right now, and", + "Dolt will refuse to merge over it, so every later sync halts here until you resolve", + "it. Nothing was pushed.") + default: + lines = append(lines, + "The conflicted merge was aborted and the working set restored, so no local work was", + "lost — and sync will keep halting here, unchanged, until an operator resolves the", + "divergence between this replica and the remote. Nothing is lost by waiting.") + } + + // Second: did anything at all happen before the halt? Only reported when + // it did, so the common single-attempt case stays short. + if out.Pulled { + lines = append(lines, + "Note: an earlier attempt in this run completed its pull and is_blocked repair before", + "losing the push race; the retry is what conflicted. That earlier work remains in the", + "local database and has NOT been published.") + } + return lines +} + +func printSyncOutcome(out *syncOutcome, noPush bool) { + switch out.Status { + case syncStatusConflict: + for _, line := range syncConflictMessage(out) { + fmt.Fprintln(os.Stderr, line) + } + case syncStatusRetriesExhausted: + fmt.Fprintf(os.Stderr, "Error: push-race retries exhausted after %d attempt(s).\n", out.Attempts) + if out.LastPushError != "" { + fmt.Fprintf(os.Stderr, " last push error: %s\n", out.LastPushError) + } + fmt.Fprintln(os.Stderr, "This is transient — another replica kept winning the race. Retry on the next tick, or raise --attempts.") + default: + if out.RowsCorrected > 0 { + fmt.Printf("Recomputed is_blocked: %d row(s) corrected.\n", out.RowsCorrected) + } + if noPush { + fmt.Println("Sync complete (push skipped: rig is local-only, no-push: true).") + return + } + fmt.Println("Sync complete.") + } +} diff --git a/cmd/bd/sync_test.go b/cmd/bd/sync_test.go new file mode 100644 index 000000000..77e9c4997 --- /dev/null +++ b/cmd/bd/sync_test.go @@ -0,0 +1,764 @@ +package main + +import ( + "context" + "errors" + "fmt" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/storage" + "github.com/steveyegge/beads/internal/storage/versioncontrolops" +) + +// syncOpsRecorder builds a syncOps whose steps are scripted per attempt and +// which records how many times each step ran. Scripts are indexed by call +// number; a call past the end of a script reuses the script's last entry, so a +// nil script means "always succeed". +type syncOpsRecorder struct { + pullErrs []error + pullConflicts [][]string + conflictsSeq [][]string + conflictsErrs []error + recomputeVals []int + recomputeErrs []error + pushErrs []error + + pulls int + conflicts int + recomputes int + pushes int +} + +func scriptedErr(script []error, call int) error { + if len(script) == 0 { + return nil + } + if call >= len(script) { + return script[len(script)-1] + } + return script[call] +} + +func (r *syncOpsRecorder) ops() syncOps { + return syncOps{ + pull: func(context.Context) ([]string, error) { + call := r.pulls + r.pulls++ + var conflicts []string + if len(r.pullConflicts) > 0 { + if call >= len(r.pullConflicts) { + conflicts = r.pullConflicts[len(r.pullConflicts)-1] + } else { + conflicts = r.pullConflicts[call] + } + } + return conflicts, scriptedErr(r.pullErrs, call) + }, + conflicts: func(context.Context) ([]string, error) { + call := r.conflicts + r.conflicts++ + if err := scriptedErr(r.conflictsErrs, call); err != nil { + return nil, err + } + if len(r.conflictsSeq) == 0 { + return nil, nil + } + if call >= len(r.conflictsSeq) { + return r.conflictsSeq[len(r.conflictsSeq)-1], nil + } + return r.conflictsSeq[call], nil + }, + recompute: func(context.Context) (int, error) { + call := r.recomputes + r.recomputes++ + if err := scriptedErr(r.recomputeErrs, call); err != nil { + return 0, err + } + if len(r.recomputeVals) == 0 { + return 0, nil + } + if call >= len(r.recomputeVals) { + return r.recomputeVals[len(r.recomputeVals)-1], nil + } + return r.recomputeVals[call], nil + }, + push: func(context.Context) error { + defer func() { r.pushes++ }() + return scriptedErr(r.pushErrs, r.pushes) + }, + } +} + +func raceErr() error { return errors.New("push rejected: remote is ahead (non-fast-forward)") } + +func TestRunSyncLoopHappyPath(t *testing.T) { + r := &syncOpsRecorder{recomputeVals: []int{4}} + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if out.Status != syncStatusOK { + t.Fatalf("status = %q, want %q", out.Status, syncStatusOK) + } + if !out.Pushed { + t.Error("Pushed = false, want true") + } + if out.Attempts != 1 { + t.Errorf("Attempts = %d, want 1", out.Attempts) + } + if out.RowsCorrected != 4 { + t.Errorf("RowsCorrected = %d, want 4", out.RowsCorrected) + } + if r.pulls != 1 || r.recomputes != 1 || r.pushes != 1 { + t.Errorf("pulls/recomputes/pushes = %d/%d/%d, want 1/1/1", r.pulls, r.recomputes, r.pushes) + } + // Pre-flight check plus the post-pull check. + if r.conflicts != 2 { + t.Errorf("conflict checks = %d, want 2 (pre-flight + post-pull)", r.conflicts) + } +} + +// A conflict left live by an earlier halted sync must be reported as a conflict +// before anything is attempted — Dolt refuses to merge over it, so without the +// pre-flight the operator sees an opaque transport failure instead. +func TestRunSyncLoopPreflightConflictHaltsBeforePull(t *testing.T) { + r := &syncOpsRecorder{conflictsSeq: [][]string{{"issues"}}} + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if out.Status != syncStatusConflict { + t.Fatalf("status = %q, want %q", out.Status, syncStatusConflict) + } + if r.pulls != 0 || r.pushes != 0 || r.recomputes != 0 { + t.Errorf("pulls/recomputes/pushes = %d/%d/%d, want 0/0/0", r.pulls, r.recomputes, r.pushes) + } + if len(out.Conflicts) != 1 || out.Conflicts[0] != "issues" { + t.Errorf("Conflicts = %v, want [issues]", out.Conflicts) + } +} + +// The load-bearing property: a pull that reports SUCCESS can still have left +// conflicts behind. The loop must detect them positively from the conflict +// tables and halt without pushing. +func TestRunSyncLoopConflictDespiteSuccessfulPull(t *testing.T) { + r := &syncOpsRecorder{ + pullErrs: nil, // pull succeeds + conflictsSeq: [][]string{nil, {"issues", "dependencies"}}, + } + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if out.Status != syncStatusConflict { + t.Fatalf("status = %q, want %q", out.Status, syncStatusConflict) + } + if r.pushes != 0 { + t.Errorf("pushes = %d, want 0 (a conflicted merge must never be pushed)", r.pushes) + } + if r.recomputes != 0 { + t.Errorf("recomputes = %d, want 0 (halt before touching the graph)", r.recomputes) + } + if out.Pushed { + t.Error("Pushed = true, want false") + } + if len(out.Conflicts) != 2 { + t.Errorf("Conflicts = %v, want two tables", out.Conflicts) + } +} + +// The conflict source that dolt_conflicts alone cannot see: the settle pass +// aborts the conflicted merge and restores the working set, so by the time the +// pull returns, dolt_conflicts is empty again and the conflicts exist only in +// the error the merge handed back. +func TestRunSyncLoopMergeCapturedConflicts(t *testing.T) { + r := &syncOpsRecorder{pullConflicts: [][]string{{"issues"}}} + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if out.Status != syncStatusConflict { + t.Fatalf("status = %q, want %q", out.Status, syncStatusConflict) + } + if len(out.Conflicts) != 1 || out.Conflicts[0] != "issues" { + t.Errorf("Conflicts = %v, want [issues]", out.Conflicts) + } + if r.pushes != 0 || r.recomputes != 0 { + t.Errorf("recomputes/pushes = %d/%d, want 0/0", r.recomputes, r.pushes) + } +} + +func TestRunSyncLoopUnionsCapturedAndLiveConflicts(t *testing.T) { + r := &syncOpsRecorder{ + pullConflicts: [][]string{{"issues"}}, + conflictsSeq: [][]string{nil, {"dependencies", "issues"}}, + } + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if out.Status != syncStatusConflict { + t.Fatalf("status = %q, want %q", out.Status, syncStatusConflict) + } + want := []string{"dependencies", "issues"} + if len(out.Conflicts) != len(want) { + t.Fatalf("Conflicts = %v, want %v", out.Conflicts, want) + } + for i := range want { + if out.Conflicts[i] != want[i] { + t.Fatalf("Conflicts = %v, want %v", out.Conflicts, want) + } + } +} + +// The mirror image: a pull that reports FAILURE where the conflict tables are +// populated is a conflict (exit 2), not a generic transport error (exit 1). +func TestRunSyncLoopConflictWinsOverPullError(t *testing.T) { + r := &syncOpsRecorder{ + pullErrs: []error{errors.New("merge aborted")}, + conflictsSeq: [][]string{nil, {"issues"}}, + } + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if out.Status != syncStatusConflict { + t.Fatalf("status = %q, want %q", out.Status, syncStatusConflict) + } + if r.pushes != 0 { + t.Errorf("pushes = %d, want 0", r.pushes) + } +} + +// A pull failure with no conflicts is a plain error (exit 1) and must not be +// retried into the push-race budget. +func TestRunSyncLoopPullErrorWithoutConflicts(t *testing.T) { + r := &syncOpsRecorder{pullErrs: []error{errors.New("dial tcp: connection refused")}} + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err == nil { + t.Fatal("expected an error") + } + if !strings.Contains(err.Error(), "pull:") { + t.Errorf("error = %v, want it to name the pull step", err) + } + if out.Status == syncStatusConflict { + t.Error("a transport failure must not be reported as a conflict") + } + if r.pulls != 1 { + t.Errorf("pulls = %d, want 1 (no retry on a non-race failure)", r.pulls) + } +} + +// A conflict-check failure on a successful pull must surface as an error rather +// than being read as "no conflicts" and pushing anyway. +func TestRunSyncLoopConflictCheckErrorIsFatal(t *testing.T) { + r := &syncOpsRecorder{conflictsErrs: []error{nil, errors.New("dolt_conflicts unavailable")}} + _, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err == nil { + t.Fatal("expected an error") + } + if r.pushes != 0 { + t.Errorf("pushes = %d, want 0 (never push on an unknown conflict state)", r.pushes) + } +} + +func TestRunSyncLoopPreflightConflictCheckErrorIsFatal(t *testing.T) { + r := &syncOpsRecorder{conflictsErrs: []error{errors.New("dolt_conflicts unavailable")}} + _, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err == nil { + t.Fatal("expected an error") + } + if r.pulls != 0 { + t.Errorf("pulls = %d, want 0", r.pulls) + } +} + +func TestRunSyncLoopRecomputeErrorHaltsBeforePush(t *testing.T) { + r := &syncOpsRecorder{recomputeErrs: []error{errors.New("recompute failed")}} + _, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err == nil { + t.Fatal("expected an error") + } + if !strings.Contains(err.Error(), "recompute-blocked") { + t.Errorf("error = %v, want it to name the recompute step", err) + } + if r.pushes != 0 { + t.Errorf("pushes = %d, want 0 (a stale is_blocked must not be published)", r.pushes) + } +} + +// A push race re-enters the loop at the pull so the retry merges the commits +// that beat us, and converges. +func TestRunSyncLoopPushRaceRetriesAndSucceeds(t *testing.T) { + r := &syncOpsRecorder{ + pushErrs: []error{raceErr(), raceErr(), nil}, + recomputeVals: []int{1, 2, 0}, + } + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if out.Status != syncStatusOK { + t.Fatalf("status = %q, want %q", out.Status, syncStatusOK) + } + if out.Attempts != 3 { + t.Errorf("Attempts = %d, want 3", out.Attempts) + } + if r.pulls != 3 { + t.Errorf("pulls = %d, want 3 (each retry must re-pull)", r.pulls) + } + if r.recomputes != 3 { + t.Errorf("recomputes = %d, want 3", r.recomputes) + } + if out.RowsCorrected != 3 { + t.Errorf("RowsCorrected = %d, want 3 (accumulated across attempts)", out.RowsCorrected) + } + if out.LastPushError != "" { + t.Errorf("LastPushError = %q, want empty on success", out.LastPushError) + } +} + +func TestRunSyncLoopRetriesExhausted(t *testing.T) { + r := &syncOpsRecorder{pushErrs: []error{raceErr()}} + out, err := runSyncLoop(context.Background(), r.ops(), 2) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if out.Status != syncStatusRetriesExhausted { + t.Fatalf("status = %q, want %q", out.Status, syncStatusRetriesExhausted) + } + if out.Attempts != 2 { + t.Errorf("Attempts = %d, want 2", out.Attempts) + } + if r.pushes != 2 { + t.Errorf("pushes = %d, want 2 (bounded by --attempts)", r.pushes) + } + if out.Pushed { + t.Error("Pushed = true, want false") + } + if out.LastPushError == "" { + t.Error("LastPushError is empty, want the last race error recorded") + } +} + +// A push failure that is not a race can never converge by retrying, so it must +// exit immediately rather than burning the attempt budget. +func TestRunSyncLoopNonRacePushErrorDoesNotRetry(t *testing.T) { + r := &syncOpsRecorder{pushErrs: []error{errors.New("permission denied")}} + _, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err == nil { + t.Fatal("expected an error") + } + if !strings.Contains(err.Error(), "push:") { + t.Errorf("error = %v, want it to name the push step", err) + } + if r.pushes != 1 { + t.Errorf("pushes = %d, want 1", r.pushes) + } +} + +func TestRunSyncLoopMaxAttemptsFloor(t *testing.T) { + r := &syncOpsRecorder{pushErrs: []error{raceErr()}} + out, err := runSyncLoop(context.Background(), r.ops(), 0) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if out.Attempts != 1 || r.pushes != 1 { + t.Errorf("attempts/pushes = %d/%d, want 1/1 (a non-positive bound floors at one attempt)", out.Attempts, r.pushes) + } + if out.Status != syncStatusRetriesExhausted { + t.Errorf("status = %q, want %q", out.Status, syncStatusRetriesExhausted) + } +} + +func TestIsPushRaceErr(t *testing.T) { + tests := []struct { + name string + err error + want bool + }{ + {"nil", nil, false}, + // The two routes a real Dolt push race travels. The SQL procedure says + // the branch is behind its remote counterpart; the CLI route folds + // git's non-fast-forward rejection into the error text. + {"behind", errors.New("local branch is behind remote"), true}, + {"behind its remote counterpart", errors.New("hint: Updates were rejected because the tip of your current branch is behind its remote counterpart"), true}, + {"hyphenated fast-forward", errors.New("push failed: non-fast-forward update"), true}, + {"spaced fast forward", errors.New("updates were not fast forward"), true}, + {"fastforward", errors.New("not a fastforward push"), true}, + {"uppercase", errors.New("PUSH FAILED: NON-FAST-FORWARD"), true}, + // The git-blobstore layer behind git+* remotes pushes with + // --force-with-lease; a lost lease reads as none of the above. + {"stale info", errors.New("! [rejected] main -> main (stale info)"), true}, + {"fetch first", errors.New("! [rejected] main -> main (fetch first)"), true}, + {"remote contains work", errors.New("the remote contains work that you do not have locally"), true}, + // A bare "rejected" is deliberately NOT a race. A protected branch or a + // declining pre-receive hook rejects permanently: classifying that as + // retryable makes a sync timer burn its whole attempt budget every tick + // and report exit 3 ("transient, retry next tick") forever, so the + // failure never surfaces as the error it is. + {"bare rejection", errors.New("push to remote rejected"), false}, + {"protected branch", errors.New("remote rejected: refs/heads/main is a protected branch"), false}, + {"pre-receive hook", errors.New("push rejected by pre-receive hook"), false}, + {"unrelated failure", errors.New("dial tcp: connection refused"), false}, + {"auth failure", errors.New("permission denied"), false}, + // Hard divergence must never be treated as retryable: retrying can + // never converge, and it would eat the whole attempt budget before + // surfacing the guidance the operator actually needs. + {"no common ancestor", errors.New("merge failed: no common ancestor"), false}, + {"cannot find common ancestor", errors.New("cannot find common ancestor for merge"), false}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := isPushRaceErr(tt.err); got != tt.want { + t.Errorf("isPushRaceErr(%v) = %v, want %v", tt.err, got, tt.want) + } + }) + } +} + +// A wrapped divergence error must still be excluded: the loop wraps nothing +// itself, but the store layer does. +func TestIsPushRaceErrWrappedDivergence(t *testing.T) { + err := fmt.Errorf("push to remote: %w", errors.New("no common ancestor")) + if isPushRaceErr(err) { + t.Error("wrapped divergence classified as a retryable race") + } +} + +// The no-remote hint is deliberately broader than isRemoteNotFoundErr — a +// default-remote fetch on a rig that never configured one fails with Dolt's +// bare "Error 1105: no remote", which the "remote ... not found" phrasing +// misses, and sync runs on a timer. What must NOT widen with it is anything +// describing a remote that exists and is broken. +func TestIsNoRemoteConfiguredErr(t *testing.T) { + tests := []struct { + name string + err error + want bool + }{ + {"nil", nil, false}, + {"dolt bare no remote", errors.New("fetch from origin/main: Error 1105: no remote"), true}, + {"remote not found", errors.New(`remote "mini" not found`), true}, + {"not found, remote after", errors.New("not found: remote origin"), true}, + {"uppercase", errors.New("Error 1105: NO REMOTE"), true}, + // A configured-but-broken remote is a real failure and must keep its + // non-zero exit — the structural confirmation is a second gate, but the + // hint should not invite it here either. + {"repo missing on the remote side", errors.New("remote repository does not exist"), false}, + {"auth", errors.New("permission denied"), false}, + {"transport", errors.New("dial tcp: connection refused"), false}, + {"branch missing", errors.New("branch main not found on remote-tracking ref"), true}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := isNoRemoteConfiguredErr(tt.err); got != tt.want { + t.Errorf("isNoRemoteConfiguredErr(%v) = %v, want %v", tt.err, got, tt.want) + } + }) + } +} + +// Every error the narrower dolt-verb classifier accepts must still be accepted +// by sync's, or sync would exit non-zero where `bd dolt pull` exits 0. +func TestIsNoRemoteConfiguredErrSupersetOfRemoteNotFound(t *testing.T) { + for _, msg := range []string{ + `remote "origin" not found`, + "REMOTE NOT FOUND", + "could not be found: unknown remote", + } { + err := errors.New(msg) + if isRemoteNotFoundErr(err) && !isNoRemoteConfiguredErr(err) { + t.Errorf("%q: accepted by isRemoteNotFoundErr but rejected by isNoRemoteConfiguredErr", msg) + } + } +} + +func TestClassifyPullError(t *testing.T) { + t.Run("nil", func(t *testing.T) { + tables, err := classifyPullError(nil) + if err != nil || tables != nil { + t.Errorf("classifyPullError(nil) = %v, %v; want nil, nil", tables, err) + } + }) + t.Run("unrelated error passes through", func(t *testing.T) { + in := errors.New("dial tcp: connection refused") + tables, err := classifyPullError(in) + if tables != nil { + t.Errorf("tables = %v, want nil", tables) + } + if !errors.Is(err, in) { + t.Errorf("err = %v, want the original error", err) + } + }) + t.Run("merge conflicts are extracted, not surfaced as an error", func(t *testing.T) { + mce := &versioncontrolops.MergeConflictsError{ + Conflicts: []storage.Conflict{{Field: "issues"}, {Field: "dependencies"}}, + MergeErr: errors.New("merge failed"), + } + tables, err := classifyPullError(mce) + if err != nil { + t.Fatalf("err = %v, want nil (the conflict is an outcome, not a failure)", err) + } + want := []string{"dependencies", "issues"} + if len(tables) != len(want) { + t.Fatalf("tables = %v, want %v", tables, want) + } + for i := range want { + if tables[i] != want[i] { + t.Fatalf("tables = %v, want %v", tables, want) + } + } + }) + t.Run("wrapped merge conflicts are still extracted", func(t *testing.T) { + mce := &versioncontrolops.MergeConflictsError{Conflicts: []storage.Conflict{{Field: "issues"}}} + tables, err := classifyPullError(fmt.Errorf("pull from origin: %w", mce)) + if err != nil { + t.Fatalf("err = %v, want nil", err) + } + if len(tables) != 1 || tables[0] != "issues" { + t.Errorf("tables = %v, want [issues]", tables) + } + }) +} + +func TestUnionTables(t *testing.T) { + tests := []struct { + name string + a, b []string + want []string + }{ + {"both empty", nil, nil, nil}, + {"only a", []string{"issues"}, nil, []string{"issues"}}, + {"only b", nil, []string{"issues"}, []string{"issues"}}, + {"deduped and sorted", []string{"issues"}, []string{"issues", "dependencies"}, []string{"dependencies", "issues"}}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := unionTables(tt.a, tt.b) + if len(got) != len(tt.want) { + t.Fatalf("unionTables(%v, %v) = %v, want %v", tt.a, tt.b, got, tt.want) + } + for i := range tt.want { + if got[i] != tt.want[i] { + t.Fatalf("unionTables(%v, %v) = %v, want %v", tt.a, tt.b, got, tt.want) + } + } + }) + } +} + +func TestConflictTables(t *testing.T) { + got := conflictTables([]storage.Conflict{ + {Field: "issues"}, + {Field: "dependencies"}, + {Field: "issues"}, + {Field: ""}, + }) + want := []string{"(unknown)", "dependencies", "issues"} + if len(got) != len(want) { + t.Fatalf("conflictTables = %v, want %v", got, want) + } + for i := range want { + if got[i] != want[i] { + t.Fatalf("conflictTables = %v, want %v", got, want) + } + } + if n := len(conflictTables(nil)); n != 0 { + t.Errorf("conflictTables(nil) returned %d entries, want 0", n) + } +} + +// The is_blocked repair must run on EVERY attempt, including a quiet tick that +// merged nothing. RecomputeAllBlocked is specifically the repair that does not +// depend on a merge advancing HEAD (bd-6dnrw.37) — it is what recovers a column +// left stale by a conflicted pull an operator resolved by hand, which is a state +// sync manufactures itself by exiting 2. Gating it on "did anything merge" would +// mean that repair never runs again while every tick reports success. +func TestRunSyncLoopRecomputesOnEveryAttempt(t *testing.T) { + r := &syncOpsRecorder{ + pushErrs: []error{raceErr(), nil}, + recomputeVals: []int{0, 0}, + } + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if out.Status != syncStatusOK { + t.Fatalf("status = %q, want %q", out.Status, syncStatusOK) + } + // Two attempts, two recomputes — and the zero rows corrected on a quiet + // tick must not be mistaken for a reason to have skipped it. + if r.recomputes != 2 { + t.Errorf("recomputes = %d, want 2 (one per attempt, unconditionally)", r.recomputes) + } + if out.RowsCorrected != 0 { + t.Errorf("RowsCorrected = %d, want 0", out.RowsCorrected) + } +} + +// A push race followed by a conflicted retry: the run has already pulled and +// repaired, so the halt report must not describe itself as having touched +// nothing. +func TestRunSyncLoopConflictAfterPushRaceRecordsPulled(t *testing.T) { + r := &syncOpsRecorder{ + pushErrs: []error{raceErr()}, + conflictsSeq: [][]string{nil, nil, {"issues"}}, + } + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if out.Status != syncStatusConflict { + t.Fatalf("status = %q, want %q", out.Status, syncStatusConflict) + } + if !out.Pulled { + t.Error("Pulled = false, want true (attempt 1 pulled and recomputed before the race)") + } + if out.ConflictsPreexisting { + t.Error("ConflictsPreexisting = true, want false (this run's retry produced the conflict)") + } + if r.pushes != 1 { + t.Errorf("pushes = %d, want 1 (the conflicted retry must not push)", r.pushes) + } +} + +// Whether the conflicted merge was aborted or left live in the working set is +// read from WHICH detection source fired, never assumed: the SQL pull route +// aborts and restores, while the CLI/git-protocol route deliberately leaves the +// conflict rows in place for the operator (finishCLIPull). +func TestRunSyncLoopConflictLivenessComesFromTheSource(t *testing.T) { + t.Run("captured-only conflicts were aborted away", func(t *testing.T) { + r := &syncOpsRecorder{pullConflicts: [][]string{{"issues"}}} + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if out.ConflictsLive { + t.Error("ConflictsLive = true, want false (the settle pass aborted the merge)") + } + }) + + t.Run("live rows mean the database is conflicted now", func(t *testing.T) { + r := &syncOpsRecorder{conflictsSeq: [][]string{nil, {"issues"}}} + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if !out.ConflictsLive { + t.Error("ConflictsLive = false, want true (the rows are live in the working set)") + } + }) + + t.Run("a pre-existing conflict is live by definition", func(t *testing.T) { + r := &syncOpsRecorder{conflictsSeq: [][]string{{"issues"}}} + out, err := runSyncLoop(context.Background(), r.ops(), defaultSyncAttempts) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if !out.ConflictsLive || !out.ConflictsPreexisting { + t.Errorf("ConflictsLive/Preexisting = %v/%v, want true/true", out.ConflictsLive, out.ConflictsPreexisting) + } + }) +} + +// The halt report is the operator's only signal about what state the replica is +// in, and the three conflict cases need opposite instructions. +func TestSyncConflictMessage(t *testing.T) { + joined := func(out *syncOutcome) string { + return strings.Join(syncConflictMessage(out), "\n") + } + + t.Run("names the conflicted tables", func(t *testing.T) { + got := joined(&syncOutcome{Conflicts: []string{"dependencies", "issues"}}) + for _, table := range []string{"dependencies", "issues"} { + if !strings.Contains(got, table) { + t.Errorf("message does not name conflicted table %q:\n%s", table, got) + } + } + if !strings.Contains(got, "nothing pushed") { + t.Errorf("message does not say nothing was pushed:\n%s", got) + } + }) + + t.Run("aborted conflict says the working set was restored", func(t *testing.T) { + got := joined(&syncOutcome{Conflicts: []string{"issues"}}) + if !strings.Contains(got, "working set restored") { + t.Errorf("message does not report the restore:\n%s", got) + } + if strings.Contains(got, "ALREADY in a conflicted state") { + t.Errorf("fresh conflict described as pre-existing:\n%s", got) + } + }) + + // The CLI/git-protocol route leaves the conflict rows live. Telling that + // operator "the working set was restored" sends them away from a database + // that is conflicted right now. + t.Run("live conflict is never described as restored", func(t *testing.T) { + got := joined(&syncOutcome{Conflicts: []string{"issues"}, ConflictsLive: true}) + if !strings.Contains(got, "LIVE in the working set") { + t.Errorf("message does not report the live rows:\n%s", got) + } + if strings.Contains(got, "working set restored") { + t.Errorf("a live conflict must not be described as restored:\n%s", got) + } + }) + + t.Run("pre-existing conflict says the replica was already conflicted", func(t *testing.T) { + got := joined(&syncOutcome{Conflicts: []string{"issues"}, ConflictsPreexisting: true, ConflictsLive: true}) + if !strings.Contains(got, "ALREADY in a conflicted state") { + t.Errorf("message does not report the pre-existing conflict:\n%s", got) + } + if strings.Contains(got, "working set restored") { + t.Errorf("a live conflict must not be described as restored:\n%s", got) + } + }) + + t.Run("a run that pulled says so; one that did not stays quiet", func(t *testing.T) { + got := joined(&syncOutcome{Conflicts: []string{"issues"}, Pulled: true}) + if !strings.Contains(got, "completed its pull and is_blocked repair") { + t.Errorf("message does not report the earlier attempt:\n%s", got) + } + if quiet := joined(&syncOutcome{Conflicts: []string{"issues"}}); strings.Contains(quiet, "earlier attempt") { + t.Errorf("single-attempt halt mentions an earlier attempt:\n%s", quiet) + } + }) +} + +func TestSyncCommandRegistered(t *testing.T) { + var found bool + for _, cmd := range rootCmd.Commands() { + if cmd.Use == "sync" { + found = true + if cmd.GroupID != "sync" { + t.Errorf("GroupID = %q, want %q", cmd.GroupID, "sync") + } + if f := cmd.Flags().Lookup("remote"); f == nil { + t.Error("missing --remote flag") + } + f := cmd.Flags().Lookup("attempts") + if f == nil { + t.Fatal("missing --attempts flag") + } + if f.DefValue != fmt.Sprint(defaultSyncAttempts) { + t.Errorf("--attempts default = %q, want %d", f.DefValue, defaultSyncAttempts) + } + break + } + } + if !found { + t.Fatal("sync command not registered with rootCmd") + } +} + +// The exit codes are the command's machine contract: a sync timer branches on +// them. Pin them so a refactor cannot renumber them silently. +func TestSyncExitCodesArePinned(t *testing.T) { + if ExitSyncConflict != 2 { + t.Errorf("ExitSyncConflict = %d, want 2", ExitSyncConflict) + } + if ExitSyncRetriesExhausted != 3 { + t.Errorf("ExitSyncRetriesExhausted = %d, want 3", ExitSyncRetriesExhausted) + } +} diff --git a/plugins/beads/skills/beads/README.md b/plugins/beads/skills/beads/README.md index c82c06e58..8bc73c70f 100644 --- a/plugins/beads/skills/beads/README.md +++ b/plugins/beads/skills/beads/README.md @@ -102,7 +102,7 @@ NEXT: Implement rate limiting" | v0.60.0+ | CLI credential pass-through for Dolt server push/pull | | v0.58.0+ | `bd prime --claim`, `bd show --long`, `--stdin` flag | | v0.54.0+ | `bd doctor` detects committed runtime/sensitive files, `BD_BACKUP_ENABLED=false` | -| v0.52.0+ | `bd sync` deprecated (use `bd dolt push`), `--claim` for atomic start-work | +| v0.52.0+ | the JSONL-era `bd sync` deprecated (superseded by `bd dolt push`; a new federation-loop `bd sync` was added later — see `commands/sync.md`), `--claim` for atomic start-work | | v0.47.0+ | Pull-first sync, resolve-conflicts, dry-run create, gate auto-discovery | | v0.43.0+ | Full support: agents, gates, worktrees, chemistry patterns | | v0.40.0+ | Agent beads, async gates, worktree management | diff --git a/plugins/beads/skills/beads/commands/sync.md b/plugins/beads/skills/beads/commands/sync.md index cd54c24a2..9841fe420 100644 --- a/plugins/beads/skills/beads/commands/sync.md +++ b/plugins/beads/skills/beads/commands/sync.md @@ -3,12 +3,71 @@ description: Synchronize issues with a configured Dolt remote argument-hint: "" --- -The top-level `bd sync` command has been removed. Running it returns an -unknown-command error; it is not a compatibility no-op. Nested commands such -as `bd backup sync` and tracker-specific sync commands are separate commands -and remain supported. +`bd sync` runs one full synchronization cycle against the configured Dolt +remote: pull, check for merge conflicts, recompute the denormalized +`is_blocked` flag, then push — retrying a bounded number of times when another +replica wins the push race. It is the loop a multi-machine deployment otherwise +hand-rolls in shell, and it is the verb to reach for on a sync timer. -## Supported workflow +(This is not the old JSONL-era `bd sync`, which was removed in v0.51. Nested +commands such as `bd backup sync` and the tracker-specific sync commands are +separate commands and are unaffected.) + +```bash +bd sync # sync with the default remote +bd sync --remote mini # sync with a specific named remote +bd sync --attempts 5 # allow more push-race retries (default 3) +bd sync --json # machine-parseable outcome +``` + +Exit codes are the machine contract, so a timer can branch on them without +parsing output: + +| Code | Meaning | +|------|---------| +| `0` | Synced, or nothing to do | +| `1` | Error (transport, auth, storage) | +| `2` | Merge conflict — halted, nothing pushed; resolve it by hand | +| `3` | Push-race retries exhausted — transient, retry on the next tick | + +Two properties are the point of the verb. Conflicts are detected **positively**, +from the merge's own conflict rows and from Dolt's conflict tables — never +inferred from the pull's exit status, which is untrustworthy in both directions. +And a conflict sync cannot settle is **never** resolved by picking a side: it +halts before recomputing or pushing, and keeps halting the same way until an +operator resolves the divergence. (The pull underneath still auto-settles the +convergent conflict classes it always has — machine-local metadata rows, +audit-only dependency rows, last-write-wins on issue cells. Anything past those +halts here.) + +The halt message says which state the halt left behind, because it depends on +the pull route and both are real: the SQL route aborts the conflicted merge and +restores the working set, while the CLI/git-protocol route leaves the conflict +rows **live** for you. A conflict that was already live when sync started — from +an earlier halted sync or a hand-run merge — halts before the pull instead, and +says that too. + +The recompute between pull and push is not bookkeeping either — `is_blocked` is +denormalized, so a dependency edge merged in from another replica leaves +`bd ready` stale until it runs. It runs on every attempt, unconditionally: +`bd recompute-blocked`'s full pass is specifically the repair that does *not* +depend on a merge advancing HEAD, so it is what recovers a column left stale by +a conflicted pull you resolved by hand — a state sync itself creates by exiting +2. Gating it on "did this tick merge anything" would mean that repair never runs +again while every tick reports success. + +This is not `bd federation sync`, which syncs with named peer towns and takes a +`--strategy ours|theirs` to resolve whatever conflicts it meets. `bd sync` +targets the configured remote and has no such switch. + +`--json` reports `{"status", "attempts", "conflicts", "conflicts_live", +"rows_corrected", "pushed"}` on every non-error exit; exit 1 emits bd's standard +`{"error": ...}` envelope instead, so a timer reading `.status` must treat +`null` as the error case (or just branch on the exit code, which is the point). +A rig with no remote configured exits 0 with setup guidance; `dolt.local-only` +and the `no-push` config flag are honored. + +## The equivalent by hand ```bash # Before starting work or consuming changes from another clone diff --git a/scripts/check-doc-flags.sh b/scripts/check-doc-flags.sh index 24c16464b..8409b4564 100755 --- a/scripts/check-doc-flags.sh +++ b/scripts/check-doc-flags.sh @@ -57,7 +57,13 @@ echo "" # --- Check 1: Known-removed commands --- echo "=== Check 1: Removed commands ===" -# bd sync (removed in v0.51) +# bd sync: the JSONL-era command was removed in v0.51, and a top-level `bd sync` +# was reintroduced (wy-jpd3.4) as the federation loop — pull, positive conflict +# check, recompute-blocked, push. So the stale reference to hunt is no longer +# any mention of the command; it is docs still describing it as removed, +# deprecated, or a no-op, which is exactly what its own command doc said until +# the verb came back. CHANGELOG and the staged-for-removal audits are history +# and legitimately say so. SYNC_REFS=$(grep -rn 'bd sync\b' \ "$PROJECT_ROOT"/docs/*.md \ "$PROJECT_ROOT"/docs/*/*.md \ @@ -69,15 +75,17 @@ SYNC_REFS=$(grep -rn 'bd sync\b' \ "$PROJECT_ROOT"/plugins/beads/skills/beads/commands/*.md \ "$PROJECT_ROOT"/plugins/beads/skills/beads/resources/*.md \ 2>/dev/null \ - | grep -v 'CHANGELOG\|audit-sync-mode\|deprecated\|no-op\|removed\|was removed\|has been removed' \ + | grep -v 'CHANGELOG\|audit-sync-mode' \ + | grep -i 'deprecated\|no-op\|removed\|unknown-command' \ + | grep -vi 'removed in v0\.51\|JSONL-era' \ || true) if [ -n "$SYNC_REFS" ]; then - echo "FAIL: Found references to removed 'bd sync' command:" + echo "FAIL: Found docs describing 'bd sync' as removed/deprecated — it is a live command:" echo "$SYNC_REFS" | head -20 ERRORS=$((ERRORS + 1)) else - echo "PASS: No stale 'bd sync' references" + echo "PASS: No stale 'bd sync is removed' references" fi echo ""