feat(sync): bd sync — the federation loop as one verb (wy-jpd3.4)

Every multi-machine beads deployment hand-rolls the same shell loop around
pull/push; this ships it as `bd sync [--remote <name>] [--attempts N]`.

Three properties are the point of the verb, and each is a lesson paid for by
the reference deployment (a two-machine federation on a 60s timer):

- 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 reasons that are not conflicts, and a settled merge that IS
  conflicted aborts and leaves dolt_conflicts empty, so an exit-status guess
  both invents phantom conflicts and misses real ones. A pre-flight check also
  halts on conflicts left live by an earlier halted sync, which Dolt otherwise
  refuses to merge over with an opaque transport error.
- A conflict sync cannot settle is NEVER resolved by picking a side: it halts
  before recomputing or pushing, with no --strategy-style override. A timer
  that silently picks a side loses work on a schedule. The halt message
  reports whether the conflict rows are live or were aborted away, read from
  WHICH detection source fired rather than assumed — the SQL pull route aborts
  and restores the working set, the CLI/git-protocol route deliberately leaves
  the rows live, and an operator told the wrong one looks in the wrong place.
- The is_blocked recompute runs unconditionally, on every attempt. That is
  deliberate and load-bearing: RecomputeAllBlocked is specifically the repair
  that does NOT depend on a merge advancing HEAD (bd-6dnrw.37), so it is what
  recovers a column left stale by a conflicted pull an operator resolved by
  hand — a state this verb manufactures itself by exiting 2. Gating it on "did
  this tick merge anything" re-imposes the condition it exists to escape, and
  from then on no tick merges anything, so the repair would never run again
  while every tick reported success. HEAD is the wrong instrument for that
  question anyway: the pull's own pre-merge auto-commit (GH#2474) moves it for
  purely local dirty state, and an auto-resolved merge can land in the working
  set without moving it at all (bd-6dnrw.39).

Exit codes are the machine contract so a timer can branch without parsing
output: 0 synced, 1 error, 2 merge conflict (halted, nothing pushed), 3
push-race retries exhausted (transient). --json reports the same outcome.

Push-race classification is deliberately narrow — race signatures (behind /
non-fast-forward / a lost --force-with-lease: stale info, fetch first, "contains
work that you do not have"), not the word "rejected". A protected branch or a
declining pre-receive hook also rejects, permanently; treating that as a race
burns the whole attempt budget every tick and reports exit 3 ("retry next tick")
forever instead of surfacing the failure.

Also: hasNoRemoteConfigured split out of isConfirmedNoRemote so sync can reuse
the structural no-remote proof with its own (broader) error hint without
loosening it — a solo rig must not fail every tick, but a typoed or broken
remote must still exit non-zero. The command doc and the doc-flags gate are
updated: `bd sync` is live again, so the stale reference to hunt is docs still
calling it removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge 2026-07-24 16:49:22 -07:00
commit f94ea5bfe5
7 changed files with 1514 additions and 10 deletions

View file

@ -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 <name>] [--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

View file

@ -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

628
cmd/bd/sync.go Normal file
View file

@ -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 <name> <url>' 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.")
}
}

764
cmd/bd/sync_test.go Normal file
View file

@ -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)
}
}

View file

@ -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 |

View file

@ -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

View file

@ -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 ""