release/1.3.0: stop the smart gate auto-migrating a data-behind clone (#6575) (#6659)

* fix(schema): stop the smart gate auto-migrating a data-behind clone (#6575)

Release-branch counterpart of the main-line fix. The four source files are
byte-identical to the main commit; only the CHANGELOG placement differs (a
1.3.1 "Fixed" bullet instead of Unreleased).

The smart migrate gate's first-mover verdict was computed from schema facts
alone: equal content hashes against the cached remote ref, equal max version,
and at-or-above the convergence floor. None of those say anything about where
the clone's branch sits relative to the ref the hashes came from, so a clone
that was level with the remote on SCHEMA but behind it in unpulled DATA commits
satisfied every precondition and was classified a safe first-mover.

It then migrated in place, minting local-only schema commits on a HEAD missing
the remote's data commits. When the pending batch moves a tracked table onto
the dolt_ignore plane (0062's events), every subsequent `bd dolt pull` refuses
to merge (#6368) and the clone can no longer fetch the very commits it was
already behind on. v1.3.0's upgrade audience is largely 1.1-era databases, which
is exactly the cohort reaching this state — this is being field-hit now, which
is why rc.2 is held for it.

The decisive fact was already wired: routeSmartGate's remote-ahead branch
consults adopt.IsStrictAncestor (ahead == 0 && behind >= 1) via
routeAdoptFastForward, and both production call sites supply it. The
equal-version path simply never read it. Read it there too, before granting the
automatic migrate, and stop with a new data-behind fallback reason naming the
one-command remedy.

The predicate does the narrowing for free: a level clone (ahead 0, behind 0) and
a clone with unpushed local commits (ahead > 0) both read false and still
auto-migrate, so only a strictly-behind clone is refused. An inconclusive
ancestry read degrades to the blunt #4515 block rather than assuming level,
matching the file's contract that no fallback is less safe than the blunt gate.
Below-floor outcomes are untouched — the check sits inside the floor arm.

Patch-line discipline: no new schema migration, no new feature surface. The stop
reuses the existing blunt RemoteMigrateGateError with an empty Decision, so
there is no change to the JSON or agent contract — no new Error()/userBody()/
AgentDirective/Options arms. Both shipped escape hatches still work unchanged:
--force/BD_ALLOW_REMOTE_MIGRATE=1 are consulted before the smart gate, and
BD_SMART_GATE=0 still yields the blunt block. Both stay in the release notes.

S0 capability matrix: no cell flips, so no same-commit matrix change is needed.
Verified two independent ways. No matrix fixture configures a Dolt remote — the
direct `dolt push` cell asserts "No remote is configured" and `dolt remote list`
asserts an empty listing — so checkRemoteMigrateGate returns at the hasRemote
check before the smart gate, making routeSmartGate (the only function whose
outcome changes) unreachable in every cell. Independently, matrix fixtures are
created by the binary under test, so schema is at latest and the gate exits
earlier still at len(pending) == 0. The one migrate probe, the `migrate schema`
row, therefore never reaches the changed code.

Regression test builds a genuinely data-behind clone against a real Dolt
server rather than stubbing the fact the bug is about, and adapts to this
branch's own LatestVersion (which lacks 0067). Verified failing at d487b9796
and passing here.

Fixes #6575

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

* fix(schema): give the data-behind stop a working remedy, and widen it

Review follow-up on the #6575 fix. The stop was right; what it told the
operator to do was not reachable, and it protected the rarer half of the
cohort.

F1 (blocker): the refusal prescribed `bd dolt pull`, and `bd dolt pull` was
refused by it. Measured on a real data-behind embedded clone (ahead=0,
behind=1, clean working set) at the previous head: the pull exited 1 printing
"Run `bd dolt pull` first, then retry"; `bd sync` and `bd init --reinit-local`
exited 1 the same way; `bd bootstrap` reported "Database already exists …
Nothing to do." and exited 0; `bd migrate schema --force` then `bd dolt push`
left ahead=1 behind=1 with the push rejected non-fast-forward. The only thing
that moved the clone was BD_ALLOW_REMOTE_MIGRATE=1 — performing the migration
the stop exists to prevent. An embedded workspace has no external `dolt` binary
either, so that was a fence with no gate.

It is the #4566 deadlock one refusal over, so it takes #4566's shape of fix:
a lenient open for the command whose whole purpose is to clear the refused
precondition. Narrower than #4566's, though — the remote-sync open tolerates
ONE gate reason (RemoteMigrateGateError.IsDataBehind) and nothing else. A pull
cannot resolve a fork skew, a below-floor database, a shared-store consent
decision or an opted-out blunt block, so waving it through those would buy
nothing and hide them; the dirty-table and dependency-re-key refusals stay
fatal on this open too. Broadening the existing LenientOpen classification
instead would have granted all of that in one line.

Verified end to end on both shapes, exit codes real: `bd dolt pull` 0
(0,1 -> 0,0), retrying the refused write auto-migrates as a true first-mover,
`bd dolt push` 0. On a diverged clone the pull merges: 0 when it can, 1 with
"merge conflicts in config require operator resolution; merge aborted and
working set restored" when it cannot, and `bd dolt pull --strategy theirs`
then 0 — which is why the diverged guidance names it.

F2 (high): LocalIsStrictAncestorOf is ahead == 0 && behind >= 1, so a clone
with any local commit of its own read "not behind" and still auto-migrated.
Measured at the previous head with ahead=1, behind=1: "safe first-mover", and
the migration ran. bd auto-commits every write, so behind-AND-ahead is the
ORDINARY multi-machine state and the shape the fix protected was the narrower
one. It reaches the identical wedge — the migration lands on a history missing
the remote's commits either way — so the predicate is now behind >= 1 whatever
ahead is, read from LocalAheadBehind (the counts LocalIsStrictAncestorOf was
already computing and discarding). A level clone and a purely-ahead clone have
nothing to pull and still auto-migrate, verified through the CLI.

The remedy differs by shape even though the command does not, so the two stay
separate verdicts all the way out to the message, the agent directive and the
JSON: one is told its pull fast-forwards, the other that it merges and how to
resolve conflicts. An adopter that wires only the older callback keeps the
narrower (pre-widening) reading rather than losing the stop.

F3 (medium): with data-behind outranking fallbackReasonSharedStore, a shared
store's refusal rendered with neither "co-resident" nor "#5920" anywhere —
Options()' sharedRisk only ever decorated the adopt option. The #5920
consequence and the `bd migrate schema` consent step the retry needs there now
travel with this reason, on every surface.

F4 (medium): --json emitted only fallback_reason: "data-behind" while
observed/expected/options stayed the blunt default, whose option 1 is
["bd migrate --force", "bd dolt push"] — the bug followed by a push that is
guaranteed rejected while the clone is still behind — and whose option 2
no-ops. The pull-first remedy lived only in prose --json never emitted.
observed/expected now describe this stop, options is the single pull-first
option, and data_behind_shape says which pull to expect. decision stays absent
and fallback_reason unchanged, so the key agents match on does not move.

The blunt body is REPLACED for this reason rather than decorated: both of its
options were measured wrong here, and leaving them under a note saying "pull
first" is what sent the last round back into the wedge. Error() is deliberately
untouched — the headline stays the blunt #4259 line, and the body's first
sentence accounts for it.

Both escape hatches are unchanged and re-measured: `bd migrate --force` and
BD_ALLOW_REMOTE_MIGRATE=1 are still consulted before the smart gate (exit 0),
and BD_SMART_GATE=0 still yields the blunt gate unconditionally — including
for `bd dolt pull`, which is what opting out means. The two corrections from
the first round are preserved: the "proceeds on its own" promise is still
gated on !e.Shared, and the unparseable-BD_SMART_GATE carve-out still lets
data-behind outrank an env complaint (BD_SMART_GATE=maybe re-measured).

Tests cover both shapes at three levels. The schema routing table pins the
widened predicate, the shape split, the error degradation, the
IsStrictAncestor fallback, and every remedy surface including IsDataBehind's
narrowness; neutralizing the widening fails three of its subtests. The
real-Dolt regression test now runs both shapes over the same two-clone
file:// fixture, measuring ahead/behind rather than stubbing it and asserting
that the strict-ancestor relation is false exactly where the diverged shape
needs the widening. A new embedded test builds a genuinely data-behind
embedded store, proves OpenForRemoteSync gets through the refusal without
migrating, and proves BD_SMART_GATE=0 on the same fixture does NOT.

No S0 matrix cells flip. No matrix fixture configures a Dolt remote, so
routeSmartGate stays unreachable; the only `dolt pull` probes are the
proxied-mode typed refusals, which are classified in historyCapabilityMatrix
before any store opens and are untouched.

This is the release/1.3.0 counterpart of the main-line change, code-identical
to it. Two differences, both from the base: the CHANGELOG entry is the expanded
form of the existing #6575 bullet inside `## [1.3.1] - 2026-09-16`'s `### Fixed`
(same position the bullet already held, so the #6653 CHANGELOG non-conflict is
preserved), and the dolt.Config literal in cmd/bd/main.go has no
PoolReadTimeoutFallback field on this base. The shipped `## [1.3.0]` section is
byte-identical: sha256 798a2ee0b0f0b7a3f0fc017ae01c919807740348a34f5ea8719b82a008533d00,
9169 lines, and the only CHANGELOG hunk is above its header.

This branch's own matrix (cmd/bd/topology_capability_matrix_test.go, absent on
main) was re-checked after the widening: no cell flips. No fixture configures a
Dolt remote (the direct `dolt push` cell asserts "No remote is configured" and
the direct `sync` cell asserts "status": "no-remote"), so routeSmartGate stays
unreachable, and there is no `dolt pull` probe row at all.

Refs #6575
Refs #6368
Refs #4566

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

* fix(schema): retarget the shared data-behind consent verb under --global

Self-review catch on the previous commit's own new text. The #5920 consent verb
the shared data-behind guidance names is TARGET-SCOPED: under --global the
refused open aimed at beads_global, so the project-scoped `bd migrate schema`
would consent the wrong database and leave the refusal in place. The existing
shared-no-remote arm already handles this (printGlobalDatabaseConsentHint and
the JSON retarget), and the new arm had to as well.

The JSON retarget could not simply reuse the Decision test: this stop reaches
the renderer through the default empty-Decision arm, keyed on the fallback
reason, so `e.Decision == "shared-no-remote"` misses it. The human body now
names the --global variant beside the project-scoped one, exactly as the
shared-no-remote body does. The pull itself is target-agnostic and is
deliberately NOT rewritten.

Refs #6575

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

* fix(schema): give the data-behind read path the pull remedy too

Round 2 fixed the write path and the agent payload, but left the two
lenient embedded opens rendering the blunt #4259 coordination block. Those
opens do not fail on this refusal - they warn and carry on - so the warning
IS the whole contract for `bd list`, `bd ready`, `bd show`
(openReadOnlyCommand) and `bd dolt commit` (openWorkingSetReconcile). Both
printed `gateErr` (Error(), the one-line summary) followed by the unchanged
sharedGuidance bullets, so on a data-behind clone the first thing bd said
was:

    • designated migrator (only ONE machine): bd migrate --force && bd dolt push
    • every other clone (another already migrated): bd bootstrap

Measured on a fast-forward clone at the previous head: that migrate lands
v67 on a history the clone is still behind on, and the `bd dolt push` after
it exits 1, rejected non-fast-forward - the #6575 state, reached by
following bd's own instruction, from the same clone whose write path says
in capitals not to run it. `bd bootstrap` no-ops against an existing
workspace. `bd list` is the first thing a 1.1-era upgrader runs and what
agents run constantly, so this was the most-read surface of the whole stop.

Both arms now branch on gateErr.IsDataBehind() and print
gateErr.UserMessage(), which is where the shape-branched pull-first body
already lives - the same thing server mode's warnLenientOpenRefusal has
printed all along. The intent framing is kept rather than replaced: the
command in hand is still succeeding against the old schema, which the
body (written for the fatal refusal) does not say. Refusals that are not
the data-behind stop keep the coordination bullets, which are right for
them; a second test pins that so the new body cannot swallow them.

Verified by running, not asserting - `bd list` and `bd dolt commit` on real
data-behind clones of both shapes, then `bd dolt pull` and a re-run, which
migrates.

Also fixes the agent payload contradicting itself. For data-behind,
AgentDirective calls `bd dolt pull` the single option, Options annotates it
`when: always, for this stop` and `risk: none - a pure fast-forward`, yet
human_decision_required stayed hard-coded true, so an agent keying on that
field stalled for approval of a step the same payload calls unconditional
and riskless - and the cost of that stall is reaching for
`bd migrate --force`. It is now false for exactly that arm. It stays true
when DataDiverged (the pull merges and can need conflict resolution and a
--strategy choice) and when Shared (the payload's second option needs an
operator who can confirm every co-resident client is upgraded, #5920);
getting either backwards would be worse than the contradiction. The `when`
string is deliberately unchanged for both shapes - the pull is the only way
forward either way; it is the risk, not the applicability, that diverging
changes.

Refs #6575

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

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-09-21 02:49:16 -07:00 • committed by GitHub
commit e1e1158dd9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
17 changed files with 2243 additions and 29 deletions

View file

@ -164,6 +164,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
without starting either. The `--json` payload changes shape to carry that —
see **Changed** above before parsing it.
- **The smart migrate gate no longer auto-migrates a clone whose data is behind
the remote** ([#6575](https://github.com/gastownhall/beads/issues/6575)). The
gate's first-mover verdict was computed from schema facts alone — equal
migration content hashes against the cached remote ref, at the same version,
at or above the convergence floor — and none of those say where the clone's
branch sits relative to that ref. A clone level with the remote on *schema*
but behind it in unpulled *data* commits satisfied every precondition, was
classified a safe first-mover, and migrated in place, minting local-only
schema commits on a HEAD missing those commits. When the pending batch moves
a tracked table onto the `dolt_ignore` plane, every later `bd dolt pull` then
refuses with `local changes would be stomped by merge: events`
([#6368](https://github.com/gastownhall/beads/issues/6368)) while `dolt
status` reads clean — and the clone can no longer fetch the very commits it
was behind on. Upgrading from a 1.1-era database is the ordinary way in, so
this release's upgrade audience is the exposed one. The gate now reads the
branch position its callers already supply and stops with guidance naming the
remedy: run `bd dolt pull`, then re-run what you were blocked on, and the
migrate proceeds as a true first-mover.
The stop applies whenever the clone has commits left to pull, whether or not
it also has commits of its own. bd auto-commits every write, so a clone that
is both behind and ahead is the ordinary multi-machine state, and it reaches
the same wedge; it is told its pull will *merge* rather than fast-forward, and
how to resolve conflicts if it reports them. A clone that is level with the
remote, or that only has unpushed local commits with nothing to pull, still
auto-migrates exactly as before.
**`bd dolt pull` works from the refused state.** It opens the store too, so
on a refused clone it would otherwise hit the very refusal that prescribes
it — and an embedded workspace has no external `dolt` binary to fall back to,
which would leave `BD_ALLOW_REMOTE_MIGRATE=1` (performing the migration the
stop exists to prevent) as the only way forward. `bd dolt pull` now opens
leniently for this one refusal, the way `bd dolt commit` does for the
dirty-working-set refusal
([#4566](https://github.com/gastownhall/beads/issues/4566)); every other gate
refusal still fails that open. This supersedes the [1.3.0] upgrade note's
statement that the pending-migration gate refuses `bd dolt pull` as well as
`bd dolt push`: for the data-behind stop it does not, by design.
Commands that keep working through the stop say the same thing. `bd list`,
`bd ready` and `bd show` succeed against the old schema, and `bd dolt commit`
still commits the working set; on embedded storage all of them used to print
the blunt migrate-or-adopt coordination bullets while doing so — naming
`bd migrate --force && bd dolt push`, which on a data-behind clone applies
the migration this stop exists to prevent and then fails the push
non-fast-forward, and `bd bootstrap`, which no-ops against an existing
workspace. They now print the pull-first guidance, shape-branched the same
way the fatal refusal is, alongside the note that the command in hand
continued at the current schema. Refusals that are *not* the data-behind stop
keep the coordination bullets, which are right for them.
`--json` callers get the same remedy the terminal does: `observed`,
`expected` and `options` describe the pull (a single `pull-first` option)
rather than the migrate-or-adopt decision that does not apply here, plus a
`data_behind_shape` of `fast-forward` or `diverged`. `fallback_reason` stays
`data-behind`. For the fast-forward shape on a non-shared store — one
unconditional option, no local commits, nothing discarded —
`human_decision_required` is now `false`, so an agent can run the pull
instead of stalling for approval of a step the same payload calls riskless.
It stays `true` for the diverged shape (the pull merges and can need conflict
resolution) and on a shared store (the follow-up consent step needs an
operator who can confirm every co-resident client is upgraded). On a shared
Dolt sql-server the guidance carries #5920's consequence — migrating promotes
the schema for every co-resident client, and clients still on an older bd
refuse the database until upgraded — and names the `bd migrate schema`
consent step the retry needs there.
Both existing workarounds keep working unchanged: `BD_SMART_GATE=0` opts out
of the smart gate entirely (which means the blunt gate applies to `bd dolt
pull` too — that is what opting out is), and running `bd dolt pull` before the
first open after upgrading avoids the state to begin with. `bd migrate
--force` / `BD_ALLOW_REMOTE_MIGRATE=1` are still consulted before the gate and
still override it.
- **A dotted config key now round-trips: what `bd config set` writes,
`bd config get` and bd's own readers find**
([#6578](https://github.com/gastownhall/beads/pull/6578), bd-zj95). Setting a

View file

@ -58,6 +58,7 @@ var storeConstructors = map[string]map[string]bool{
"OpenForReadOnlyCommand": true,
"OpenForPreviewCommand": true,
"OpenForWorkingSetReconcile": true,
"OpenForRemoteSync": true,
},
"github.com/steveyegge/beads/internal/storage/uow": {
"NewDoltServerUOWProvider": true,

View file

@ -324,6 +324,30 @@ func isWorkingSetReconcileCommand(cmd *cobra.Command) bool {
return parent.Name() == "dolt" || parent.Name() == "vc"
}
// isRemoteSyncCommand reports whether cmd is `bd dolt pull`: the one command
// the #6575 data-behind migrate-gate refusal tells the operator to run.
//
// It is the same deadlock isWorkingSetReconcileCommand breaks for #4566, one
// refusal over. The gate stops a data-behind clone from migrating and names
// `bd dolt pull` as the remedy — but the pull opens the store too, so it hit
// that refusal before it could clear its cause. On an embedded clone there is
// no external `dolt` binary to fall back to, which left the refused clone with
// exactly one exit: BD_ALLOW_REMOTE_MIGRATE=1, i.e. performing the migration
// the refusal exists to prevent. Opening via embeddeddolt.OpenForRemoteSync /
// dolt.Config.RemoteSyncOpen tolerates that ONE gate reason and nothing else.
//
// Deliberately just the pull, not `bd sync`: sync also pushes and can write
// issue rows, and a write against a stale schema is the hazard the gate is
// about. The pull only moves the commit graph, which is precisely the
// precondition the refusal is waiting on.
func isRemoteSyncCommand(cmd *cobra.Command) bool {
if cmd.Name() != "pull" {
return false
}
parent := cmd.Parent()
return parent != nil && parent.Name() == "dolt"
}
// isForcedMigrate reports whether cmd is `bd migrate` or `bd migrate schema`
// invoked with --force: the operator confirming they are the single designated
// migrator, so the remote-migrate gate (#4259) must not block this run's store
@ -1622,6 +1646,7 @@ var rootCmd = &cobra.Command{
DisableAutoStart: policy.disableAutoStart,
BeadsDir: beadsDir,
LenientOpen: isWorkingSetReconcileCommand(cmd),
RemoteSyncOpen: isRemoteSyncCommand(cmd),
}
// Load config to get database name and server connection settings.

View file

@ -18,6 +18,49 @@ const (
sharedServersDocsURL = "https://github.com/gastownhall/beads/blob/main/docs/getting-started/upgrading.md#shared-servers"
)
// humanDecisionRequired reports whether this refusal is one an agent must stop
// and hand to a human, rather than act on.
//
// Every arm of this gate but one is a coordination or data-loss decision the
// process cannot make — which clone is the designated migrator, whether it is
// safe to discard unpushed work, whether every co-resident client is upgraded
// — so the answer is true by default, and was hard-coded true before the
// #6575 data-behind stop existed.
//
// The data-behind stop is the exception, and only in its narrowest shape. It
// carries a single option whose command is `bd dolt pull`, whose When is
// unconditional ("always, for this stop") and whose Risk is "none — a pure
// fast-forward"; AgentDirective says the same in prose. Leaving the field true
// there made this payload contradict itself: an agent keying on it stopped to
// ask a human to approve a step the rest of the payload calls unconditional
// and riskless — and the cost of that stall is the operator reaching for
// `bd migrate --force` instead, which is the #6575 wedge.
//
// Both narrowing conditions are deliberate, and getting either backwards would
// be worse than leaving the field true:
//
// - DataDiverged: the clone has commits of its own, so the pull MERGES.
// Options() already says so — its Risk for this shape is conflicts "that
// must be resolved before it completes", with a `--strategy ours|theirs`
// choice behind them. A merge that can require conflict resolution, and a
// strategy that decides whose rows win, is exactly a human decision.
// AgentDirective agrees ("surface a conflict outcome to the operator
// rather than forcing past it"). Stays true.
//
// - Shared: the pull itself is still safe, but on a shared store the payload
// carries a SECOND option, migrate-shared-after-pulling, whose When
// requires the operator to confirm every co-resident bd client is upgraded
// (#5920) — unobservable from this process. This field describes the
// payload, not its first option, so one option needing a human makes the
// answer true. AgentDirective agrees ("Do NOT auto-run it"). Stays true.
//
// What is NOT narrowed on: the When string, which is "always, for this stop"
// in both shapes and correctly so — the pull is the only way forward either
// way. It is the Risk, not the applicability, that the diverged shape changes.
func humanDecisionRequired(e *schema.RemoteMigrateGateError) bool {
return !(e.IsDataBehind() && !e.DataDiverged && !e.Shared)
}
// handleRemoteMigrateGateJSON renders the #4259 remote-migrate gate error as a
// structured JSON error block for agent consumption.
//
@ -44,7 +87,13 @@ func handleRemoteMigrateGateJSON(e *schema.RemoteMigrateGateError) {
if globalFlag {
sharedConsent = schema.SharedConsentCommandGlobal
}
retargetShared := globalFlag && e.Decision == "shared-no-remote"
// The #6575 data-behind stop on a SHARED store carries the same consent
// verb in its second option (migrate-shared-after-pulling), so it needs
// the same retarget: under --global the project-scoped verb would
// consent the wrong database and leave the refusal in place. It reaches
// here through the default arm (empty Decision), so the Decision test
// alone would miss it.
retargetShared := globalFlag && (e.Decision == "shared-no-remote" || (e.IsDataBehind() && e.Shared))
opts := make([]map[string]interface{}, 0, len(e.Options()))
for _, o := range e.Options() {
@ -76,7 +125,7 @@ func handleRemoteMigrateGateJSON(e *schema.RemoteMigrateGateError) {
"latest_version": e.LatestVersion,
"pending": e.Pending,
"severity": "blocking",
"human_decision_required": true,
"human_decision_required": humanDecisionRequired(e),
"observed": fmt.Sprintf("%d pending schema migration(s) and a configured remote", e.Pending),
"expected": "exactly one designated clone migrates and publishes; every other clone adopts the result",
"options": opts,
@ -122,6 +171,29 @@ func handleRemoteMigrateGateJSON(e *schema.RemoteMigrateGateError) {
if e.FallbackReason != "" {
gate["fallback_reason"] = e.FallbackReason
}
// gastownhall/beads#6575: the data-behind stop is a blunt stop with
// a specific, verified, one-command remedy, and the blunt
// observed/expected pair above describes a decision that does not
// apply to it. Leaving them in place pointed an agent at
// `bd migrate --force` (the bug) followed by a `bd dolt push` that
// is guaranteed to be rejected non-fast-forward while the clone is
// still behind. e.Options() already returns the pull-first option
// for this reason, so options/hint are correct above; these two
// fields are what was still lying. decision stays absent — the
// stop has no Decision, and fallback_reason is the key an agent
// matches on.
if e.IsDataBehind() {
observed := "this clone is level with the remote on schema but is BEHIND it in commits it has not pulled, so the pending migration would land on a history missing them (#6575, #6368)"
if e.DataDiverged {
observed += "; it also has commits of its own, so pulling merges rather than fast-forwards"
gate["data_behind_shape"] = "diverged"
} else {
observed += "; it has no commits of its own, so pulling is a pure fast-forward"
gate["data_behind_shape"] = "fast-forward"
}
gate["observed"] = observed
gate["expected"] = "run `" + schema.DataBehindRemedyCommand + "` first; the migration is only allowed once this clone has nothing left to pull"
}
}
m["remote_migrate_gate"] = gate
}

View file

@ -0,0 +1,354 @@
package main
import (
"bytes"
"encoding/json"
"io"
"os"
"strings"
"testing"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/storage/schema"
)
// TestIsRemoteSyncCommand pins which command gets the #6575 narrow lenient
// open. It is exactly `bd dolt pull` — the command the data-behind refusal
// prescribes, which before this fix was blocked by the refusal that prescribed
// it (the #4566 deadlock shape, one refusal over).
//
// The negative cases matter as much as the positive one: `bd sync` also pushes
// and can write issue rows, and a write against a stale schema is the hazard
// the gate exists for, so it is deliberately NOT enrolled. A bare `pull` with
// no `dolt` parent must not match either, or any future `bd <x> pull` would
// inherit an exemption nobody reviewed.
func TestIsRemoteSyncCommand(t *testing.T) {
build := func(parent, child string) *cobra.Command {
c := &cobra.Command{Use: child}
if parent != "" {
p := &cobra.Command{Use: parent}
p.AddCommand(c)
}
return c
}
cases := []struct {
parent, child string
want bool
}{
{parent: "dolt", child: "pull", want: true},
{parent: "dolt", child: "push", want: false},
{parent: "dolt", child: "commit", want: false},
{parent: "vc", child: "pull", want: false},
{parent: "", child: "pull", want: false},
{parent: "", child: "sync", want: false},
}
for _, c := range cases {
name := c.parent + " " + c.child
t.Run(strings.TrimSpace(name), func(t *testing.T) {
if got := isRemoteSyncCommand(build(c.parent, c.child)); got != c.want {
t.Errorf("isRemoteSyncCommand(%q) = %v, want %v", name, got, c.want)
}
})
}
}
// TestIsRemoteSyncCommandMatchesTheRealPullCommand guards the classification
// against the real command tree rather than a hand-built stand-in, so renaming
// or re-parenting `bd dolt pull` cannot silently drop the exemption and
// re-wedge the refused cohort.
func TestIsRemoteSyncCommandMatchesTheRealPullCommand(t *testing.T) {
if !isRemoteSyncCommand(doltPullCmd) {
t.Error("isRemoteSyncCommand(doltPullCmd) = false; the data-behind refusal's own remedy would be blocked again (#6575)")
}
if isRemoteSyncCommand(doltPushCmd) {
t.Error("isRemoteSyncCommand(doltPushCmd) = true; only the pull may open past the refusal")
}
if isRemoteSyncCommand(doltCommitCmd) {
t.Error("isRemoteSyncCommand(doltCommitCmd) = true; the commit has its own #4566 classification")
}
}
// TestHandleRemoteMigrateGateJSON_DataBehind covers the review's F4: the
// agent-facing block for the #6575 stop used to carry only an opaque
// `fallback_reason: "data-behind"` while observed/expected/options stayed the
// blunt migrate-or-adopt default — so an agent reading the documented contract
// surfaced `bd migrate --force` (the bug) followed by a `bd dolt push` that is
// guaranteed to be rejected non-fast-forward while the clone is still behind,
// plus a `bd bootstrap` that no-ops. The prose remedy existed only in text
// --json never emitted.
func TestHandleRemoteMigrateGateJSON_DataBehind(t *testing.T) {
capture := func(t *testing.T, gate *schema.RemoteMigrateGateError) map[string]interface{} {
t.Helper()
origStderr := os.Stderr
r, w, pipeErr := os.Pipe()
if pipeErr != nil {
t.Fatal(pipeErr)
}
os.Stderr = w
defer func() { os.Stderr = origStderr }()
handleRemoteMigrateGateJSON(gate)
_ = w.Close()
var buf bytes.Buffer
if _, err := io.Copy(&buf, r); err != nil {
t.Fatal(err)
}
_ = r.Close()
var parsed map[string]interface{}
if err := json.Unmarshal(buf.Bytes(), &parsed); err != nil {
t.Fatalf("json.Unmarshal stderr: %v\nstderr was: %s", err, buf.String())
}
return parsed
}
for _, tc := range []struct {
name string
diverged bool
wantShape string
}{
{name: "fast-forward shape", diverged: false, wantShape: "fast-forward"},
{name: "diverged shape", diverged: true, wantShape: "diverged"},
} {
t.Run(tc.name, func(t *testing.T) {
gate := &schema.RemoteMigrateGateError{
CurrentVersion: 66, LatestVersion: 67, Pending: 1,
FallbackReason: "data-behind",
DataDiverged: tc.diverged,
}
parsed := capture(t, gate)
obj, ok := parsed["remote_migrate_gate"].(map[string]interface{})
if !ok {
t.Fatalf("remote_migrate_gate missing or wrong type: %T", parsed["remote_migrate_gate"])
}
// The machine-readable reason an agent matches on is unchanged.
if got, _ := obj["fallback_reason"].(string); got != "data-behind" {
t.Errorf("fallback_reason = %v, want \"data-behind\"", obj["fallback_reason"])
}
if _, ok := obj["decision"]; ok {
t.Errorf("this is a blunt stop and must not carry a decision key, got %v", obj["decision"])
}
if got, _ := obj["data_behind_shape"].(string); got != tc.wantShape {
t.Errorf("data_behind_shape = %v, want %q", obj["data_behind_shape"], tc.wantShape)
}
// observed/expected must describe THIS stop, not the
// designated-migrator decision that does not apply to it.
observed, _ := obj["observed"].(string)
if !strings.Contains(observed, "BEHIND") {
t.Errorf("observed = %q, want the behind-the-remote framing", observed)
}
expected, _ := obj["expected"].(string)
if !strings.Contains(expected, schema.DataBehindRemedyCommand) {
t.Errorf("expected = %q, want the pull-first remedy", expected)
}
if strings.Contains(expected, "designated clone migrates") {
t.Errorf("expected = %q, still the blunt migrate-or-adopt framing", expected)
}
// options must be the single measured remedy, and must not hand an
// agent either of the two dead ends.
rawOpts, ok := obj["options"].([]interface{})
if !ok || len(rawOpts) != 1 {
t.Fatalf("options = %v, want exactly one (the pull)", obj["options"])
}
o, _ := rawOpts[0].(map[string]interface{})
if id, _ := o["id"].(string); id != "pull-first" {
t.Errorf("option id = %v, want \"pull-first\"", o["id"])
}
cmds, _ := o["commands"].([]interface{})
if len(cmds) != 1 || cmds[0] != schema.DataBehindRemedyCommand {
t.Errorf("option commands = %v, want [%q]", cmds, schema.DataBehindRemedyCommand)
}
if o["when"] == nil || o["risk"] == nil {
t.Errorf("option missing when/risk: %v", o)
}
// The top-level hint stays the non-runnable directive, and must
// name the remedy rather than the escape hatch.
hint, _ := parsed["hint"].(string)
if hint != gate.AgentDirective() {
t.Errorf("hint = %q, want the agent directive", hint)
}
if !strings.Contains(hint, schema.DataBehindRemedyCommand) {
t.Errorf("hint = %q, want it to name the remedy", hint)
}
if hint == gate.EscapeHint() {
t.Errorf("hint must not be the runnable escape command %q", gate.EscapeHint())
}
// Nothing anywhere in the block may offer the migrate/push pair or
// the no-op bootstrap for this state.
blob, err := json.Marshal(parsed)
if err != nil {
t.Fatal(err)
}
for _, banned := range []string{"bd bootstrap", "bd migrate --force"} {
if strings.Contains(string(blob), banned) {
t.Errorf("the data-behind block offers %q, which was measured not to work from this state:\n%s", banned, blob)
}
}
})
}
// A shared, data-behind refusal carries the #5920 consent verb in its
// second option, and that verb is target-scoped: under --global the
// project-scoped `bd migrate schema` would consent the WRONG database and
// leave the refusal in place. This stop reaches the renderer through the
// default (empty-Decision) arm, so the retarget cannot be keyed on
// Decision alone the way shared-no-remote's is.
t.Run("shared under --global retargets the consent verb", func(t *testing.T) {
origGlobal := globalFlag
globalFlag = true
defer func() { globalFlag = origGlobal }()
gate := &schema.RemoteMigrateGateError{
CurrentVersion: 66, LatestVersion: 67, Pending: 1,
FallbackReason: "data-behind",
Shared: true,
}
parsed := capture(t, gate)
obj, ok := parsed["remote_migrate_gate"].(map[string]interface{})
if !ok {
t.Fatalf("remote_migrate_gate missing or wrong type: %T", parsed["remote_migrate_gate"])
}
rawOpts, ok := obj["options"].([]interface{})
if !ok || len(rawOpts) != 2 {
t.Fatalf("options = %v, want the pull plus the shared consent step", obj["options"])
}
consent, _ := rawOpts[1].(map[string]interface{})
cmds, _ := consent["commands"].([]interface{})
if len(cmds) != 1 || cmds[0] != schema.SharedConsentCommandGlobal {
t.Errorf("consent option commands = %v, want [%q] under --global", cmds, schema.SharedConsentCommandGlobal)
}
// The pull is target-agnostic and must NOT be rewritten.
pull, _ := rawOpts[0].(map[string]interface{})
pullCmds, _ := pull["commands"].([]interface{})
if len(pullCmds) != 1 || pullCmds[0] != schema.DataBehindRemedyCommand {
t.Errorf("pull option commands = %v, want [%q] unchanged", pullCmds, schema.DataBehindRemedyCommand)
}
})
}
// TestHandleRemoteMigrateGateJSON_HumanDecisionRequired pins the one arm of
// this payload where human_decision_required is false, and — more importantly
// — the three where it must stay true.
//
// The field was hard-coded true, which made the data-behind payload contradict
// itself: the single option it carries is annotated `when: "always, for this
// stop"` and `risk: "none — a pure fast-forward"`, and AgentDirective says the
// same, yet an agent keying on this field stopped to ask a human to approve an
// unconditional, riskless step. The cost of that stall is the operator
// reaching for `bd migrate --force` instead — the #6575 wedge.
//
// The two narrowings are the substance of the finding: a diverged pull MERGES
// and can need conflict resolution (and a `--strategy ours|theirs` choice), and
// a shared store carries a SECOND option whose precondition is operator
// confirmation that every co-resident client is upgraded (#5920), which this
// process cannot observe. Either one flipping to false would be worse than the
// contradiction it replaced.
func TestHandleRemoteMigrateGateJSON_HumanDecisionRequired(t *testing.T) {
capture := func(t *testing.T, gate *schema.RemoteMigrateGateError) map[string]interface{} {
t.Helper()
origStderr := os.Stderr
r, w, pipeErr := os.Pipe()
if pipeErr != nil {
t.Fatal(pipeErr)
}
os.Stderr = w
defer func() { os.Stderr = origStderr }()
handleRemoteMigrateGateJSON(gate)
_ = w.Close()
var buf bytes.Buffer
if _, err := io.Copy(&buf, r); err != nil {
t.Fatal(err)
}
_ = r.Close()
var parsed map[string]interface{}
if err := json.Unmarshal(buf.Bytes(), &parsed); err != nil {
t.Fatalf("json.Unmarshal stderr: %v\nstderr was: %s", err, buf.String())
}
return parsed
}
for _, tc := range []struct {
name string
gate *schema.RemoteMigrateGateError
want bool
why string
}{
{
name: "data-behind, fast-forward, not shared",
gate: &schema.RemoteMigrateGateError{CurrentVersion: 66, LatestVersion: 67, Pending: 1, FallbackReason: "data-behind"},
want: false,
why: "the single option is an unconditional, riskless, non-destructive pull",
},
{
name: "data-behind, diverged",
gate: &schema.RemoteMigrateGateError{CurrentVersion: 66, LatestVersion: 67, Pending: 1, FallbackReason: "data-behind", DataDiverged: true},
want: true,
why: "the pull merges and can need conflict resolution / a strategy choice",
},
{
name: "data-behind, shared",
gate: &schema.RemoteMigrateGateError{CurrentVersion: 66, LatestVersion: 67, Pending: 1, FallbackReason: "data-behind", Shared: true},
want: true,
why: "the second option needs operator confirmation that every co-resident client is upgraded (#5920)",
},
{
name: "data-behind, diverged and shared",
gate: &schema.RemoteMigrateGateError{CurrentVersion: 66, LatestVersion: 67, Pending: 1, FallbackReason: "data-behind", DataDiverged: true, Shared: true},
want: true,
why: "both narrowings apply",
},
{
name: "blunt remote-backed stop",
gate: &schema.RemoteMigrateGateError{CurrentVersion: 66, LatestVersion: 67, Pending: 1},
want: true,
why: "only ONE clone may migrate a shared remote — a coordination decision",
},
{
name: "adopt",
gate: &schema.RemoteMigrateGateError{CurrentVersion: 66, LatestVersion: 67, Pending: 1, Decision: "adopt"},
want: true,
why: "adoption is destructive",
},
{
name: "fork-skew",
gate: &schema.RemoteMigrateGateError{CurrentVersion: 66, LatestVersion: 67, Pending: 1, Decision: "fork-skew"},
want: true,
why: "picking a canonical clone discards the others' unpushed work",
},
{
name: "shared-no-remote",
gate: &schema.RemoteMigrateGateError{CurrentVersion: 66, LatestVersion: 67, Pending: 1, Decision: "shared-no-remote", Shared: true},
want: true,
why: "other clients' binary versions are not observable from this process",
},
} {
t.Run(tc.name, func(t *testing.T) {
parsed := capture(t, tc.gate)
obj, ok := parsed["remote_migrate_gate"].(map[string]interface{})
if !ok {
t.Fatalf("remote_migrate_gate missing or wrong type: %T", parsed["remote_migrate_gate"])
}
got, ok := obj["human_decision_required"].(bool)
if !ok {
t.Fatalf("human_decision_required missing or not a bool: %T", obj["human_decision_required"])
}
if got != tc.want {
t.Errorf("human_decision_required = %v, want %v — %s", got, tc.want, tc.why)
}
// The contradiction is only resolved if the rest of the payload
// still says what it said: a false here has to come with the
// unconditional, riskless single option it is claiming.
if !tc.want {
rawOpts, ok := obj["options"].([]interface{})
if !ok || len(rawOpts) != 1 {
t.Fatalf("human_decision_required=false with options = %v; it may only be false for the single-option pull", obj["options"])
}
o, _ := rawOpts[0].(map[string]interface{})
if risk, _ := o["risk"].(string); !strings.HasPrefix(risk, "none") {
t.Errorf("human_decision_required=false but option risk = %q; want a risk-free option", risk)
}
if when, _ := o["when"].(string); !strings.HasPrefix(when, "always") {
t.Errorf("human_decision_required=false but option when = %q; want an unconditional option", when)
}
}
})
}
}

View file

@ -109,6 +109,16 @@ func newDoltStore(ctx context.Context, cfg *dolt.Config) (s storage.DoltStorage,
// branch is the embedded half of one policy, not the whole of it.
return embeddeddolt.OpenForWorkingSetReconcile(ctx, cfg.BeadsDir, cfg.Database, "main")
}
if cfg.RemoteSyncOpen {
// `bd dolt pull` must not be bricked by the #6575 data-behind gate
// refusal, because that refusal's entire remedy IS this pull: the gate
// stops a clone that is behind the remote from migrating and tells the
// operator to pull first, and an embedded clone has no external dolt
// binary to do it with. Same deadlock as #4566, and this open tolerates
// only that one gate reason (see openRemoteSync). The server arm above
// honors the same cfg.RemoteSyncOpen inside dolt.New.
return embeddeddolt.OpenForRemoteSync(ctx, cfg.BeadsDir, cfg.Database, "main")
}
return embeddeddolt.Open(ctx, cfg.BeadsDir, cfg.Database, "main")
}

View file

@ -0,0 +1,277 @@
package dolt
import (
"context"
"database/sql"
"errors"
"fmt"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads/internal/storage/doltutil"
"github.com/steveyegge/beads/internal/storage/schema"
"github.com/steveyegge/beads/internal/storage/versioncontrolops"
)
// TestDoltNew_SmartRemoteMigrateGate_DataBehindBlocks_RealDolt is the
// regression test for gastownhall/beads#6575: the smart gate's first-mover
// verdict used to be computed from schema facts alone, so a clone level with
// the remote on SCHEMA but behind it in DATA commits was classified a safe
// first-mover and auto-migrated in place — minting local-only schema commits
// on a HEAD missing the remote's data commits, which is one route into the
// #6368 events pull refusal.
//
// The fixture builds a genuinely data-behind clone against a real Dolt server
// — the behind-ness is MEASURED here (the same ahead/behind primitive the gate
// consults), never stubbed, because a test that fakes the fact the bug is about
// proves nothing:
//
// - "source" regresses its schema cursor one migration below latest (commit
// C0) and publishes C0 to a file:// origin.
// - "laggingClone" is a genuine server-side DOLT_CLONE of origin at C0.
// - "source" then makes a pure DATA commit C1 (a config row — no schema
// change at all, so the two stay at the SAME schema version) and pushes.
// - laggingClone runs CALL DOLT_FETCH('origin') only, so its cached
// remotes/origin/main advances to C1 while its own branch HEAD stays at C0.
//
// laggingClone is now schema-level with the remote (equal content hashes,
// equal max version — the smart gate's first-mover precondition) and yet one
// data commit behind it. The gate must refuse with the pull-first fallback
// reason rather than auto-migrate.
//
// BOTH shapes of that state are covered, because the review of the first fix
// measured that the narrower one was the rarer one (F2). The subtests differ
// only in whether the clone also makes a local commit of its own before the
// gate runs:
//
// - ahead=0, behind=1 — a strict ancestor; `bd dolt pull` fast-forwards.
// - ahead=1, behind=1 — diverged; `bd dolt pull` merges. Since bd
// auto-commits every write, this is the ordinary multi-machine state, and
// it reaches the identical wedge. At the first fix's head this shape
// printed "safe first-mover" and migrated.
//
// The second half of each subtest then proves the remedy loop self-heals and
// that the fix does not over-refuse: once the clone has nothing left to pull,
// the very same gate call auto-migrates it as a true first-mover.
func TestDoltNew_SmartRemoteMigrateGate_DataBehindBlocks_RealDolt(t *testing.T) {
for _, tc := range []struct {
name string
// localCommits is how many commits of its own the lagging clone makes
// after fetching: 0 is the strict-ancestor shape, 1 the diverged one.
localCommits int
wantDiverged bool
// wantRemedy is the substring the guidance must carry for this shape,
// so a clone is never told its pull will fast-forward when it merges.
wantRemedy string
}{
{name: "strict ancestor", localCommits: 0, wantRemedy: "pure fast-forward"},
{name: "diverged", localCommits: 1, wantDiverged: true, wantRemedy: "MERGES"},
} {
t.Run(tc.name, func(t *testing.T) {
runDataBehindGateCase(t, tc.localCommits, tc.wantDiverged, tc.wantRemedy)
})
}
}
func runDataBehindGateCase(t *testing.T, localCommits int, wantDiverged bool, wantRemedy string) {
skipIfNoDolt(t)
t.Setenv(schema.SmartGateEnv, "1")
t.Setenv(schema.AllowRemoteMigrateEnv, "0")
ctx, cancel := testContext(t)
defer cancel()
latest := schema.LatestVersion()
floor := schema.LastNonDeterministicMigration
if latest-1 < floor {
t.Skipf("latest=%d too close to floor=%d to build the fixture", latest, floor)
}
pBehind := latest - 1
tmpDir := t.TempDir()
sourceDB := uniqueTestDBName(t)
source, err := New(ctx, &Config{
Path: tmpDir,
CommitterName: "test",
CommitterEmail: "test@example.com",
Database: sourceDB,
CreateIfMissing: true,
MaxOpenConns: 1, // single session so working-set regressions are visible to the gate reads
})
if err != nil {
t.Fatalf("New (source): %v", err)
}
sdb := source.db
defer func() {
dropCtx, dropCancel := context.WithTimeout(context.Background(), 5*testTimeout)
defer dropCancel()
_, _ = sdb.ExecContext(dropCtx, fmt.Sprintf("DROP DATABASE IF EXISTS `%s`", sourceDB))
source.Close()
}()
mustExec := func(stage string, db *sql.DB, q string, args ...any) {
t.Helper()
if _, err := db.ExecContext(ctx, q, args...); err != nil {
t.Fatalf("%s: %v", stage, err)
}
}
remoteURL := "file://" + filepath.Join(tmpDir, "data-behind-remote")
// --- source: regress to pBehind (commit C0) and publish it. ---
mustExec("regress to pBehind", sdb, "DELETE FROM schema_migrations WHERE version = ?", latest)
mustExec("stage C0", sdb, "CALL DOLT_ADD('-A')")
mustExec("commit C0", sdb, "CALL DOLT_COMMIT('--allow-empty', '-m', 'test: regress to pBehind (C0)')")
mustExec("add remote", sdb, "CALL DOLT_REMOTE('add', 'origin', ?)", remoteURL)
mustExec("push C0", sdb, "CALL DOLT_PUSH('origin', 'main')")
// --- laggingClone: a genuine server-side clone of origin at C0. ---
laggingDB := uniqueTestDBName(t)
mustExec("clone lagging peer", sdb, "CALL DOLT_CLONE(?, ?)", remoteURL, laggingDB)
defer func() {
dropCtx, dropCancel := context.WithTimeout(context.Background(), 5*testTimeout)
defer dropCancel()
_, _ = sdb.ExecContext(dropCtx, fmt.Sprintf("DROP DATABASE IF EXISTS `%s`", laggingDB))
}()
laggingConn, err := sql.Open("mysql", doltutil.ServerDSN{
Host: "127.0.0.1", Port: testServerPort, User: "root", Database: laggingDB,
}.String())
if err != nil {
t.Fatalf("open laggingClone connection: %v", err)
}
defer laggingConn.Close()
laggingConn.SetMaxOpenConns(1)
// --- source: a pure DATA commit C1 (no schema change) and publish. The
// schema cursor stays at pBehind on BOTH sides, so the clone lands on the
// gate's equal-version first-mover path while being a data commit behind. ---
mustExec("source data edit", sdb, "REPLACE INTO config (`key`, value) VALUES ('data-behind-marker', 'C1')")
mustExec("commit C1", sdb, "CALL DOLT_COMMIT('-Am', 'test: pure data commit (C1)')")
mustExec("push C1", sdb, "CALL DOLT_PUSH('origin', 'main')")
// --- laggingClone: fetch only (no merge) so its cached ref advances but
// its own branch HEAD stays at C0. ---
mustExec("fetch (no merge)", laggingConn, "CALL DOLT_FETCH('origin')")
// --- and, for the diverged shape, commits of its own on top of C0. bd
// auto-commits every write, so this is what an ordinary local `bd create`
// leaves behind. ---
for i := 0; i < localCommits; i++ {
mustExec("clone data edit", laggingConn,
"REPLACE INTO config (`key`, value) VALUES ('local-marker', ?)", fmt.Sprintf("L%d", i))
mustExec("clone local commit", laggingConn, "CALL DOLT_COMMIT('-Am', 'test: local-only data commit')")
}
// Fixture sanity: the clone's schema cursor equals the remote's (the
// first-mover precondition), not below it.
var laggingCurrent int
if err := laggingConn.QueryRowContext(ctx,
"SELECT COALESCE(MAX(version), 0) FROM schema_migrations").Scan(&laggingCurrent); err != nil {
t.Fatalf("read laggingClone current version: %v", err)
}
if laggingCurrent != pBehind {
t.Fatalf("laggingClone current version = %d, want %d", laggingCurrent, pBehind)
}
var remoteCurrent int
if err := laggingConn.QueryRowContext(ctx,
"SELECT COALESCE(MAX(version), 0) FROM schema_migrations AS OF 'remotes/origin/main'").Scan(&remoteCurrent); err != nil {
t.Fatalf("read cached remote current version: %v", err)
}
if remoteCurrent != laggingCurrent {
t.Fatalf("cached remote version = %d, want %d (equal-version first-mover path)", remoteCurrent, laggingCurrent)
}
// The load-bearing measurement: the clone IS behind its own cached remote
// ref, in exactly the shape this subtest claims, read through the same
// primitive the gate consults.
ahead, behind, err := versioncontrolops.LocalAheadBehind(ctx, laggingConn, "remotes/origin/main")
if err != nil {
t.Fatalf("LocalAheadBehind: %v", err)
}
if behind < 1 || ahead != localCommits {
t.Fatalf("fixture position = ahead %d, behind %d; want ahead %d, behind >= 1", ahead, behind, localCommits)
}
// The strict-ancestor relation is the NARROWER fact the first fix used, and
// the diverged shape is precisely where it reads false while the clone is
// still behind — pin that, so this subtest cannot silently stop covering
// the widening it exists for.
strictAncestor, err := versioncontrolops.LocalIsStrictAncestorOf(ctx, laggingConn, "remotes/origin/main")
if err != nil {
t.Fatalf("LocalIsStrictAncestorOf: %v", err)
}
if want := localCommits == 0; strictAncestor != want {
t.Fatalf("LocalIsStrictAncestorOf = %v, want %v for ahead=%d", strictAncestor, want, ahead)
}
// And it is behind for data reasons only — the working set is clean, so the
// refusal below cannot be attributed to local dirt.
clean, err := versioncontrolops.WorkingSetClean(ctx, laggingConn)
if err != nil {
t.Fatalf("WorkingSetClean: %v", err)
}
if !clean {
t.Fatalf("fixture working set is dirty; the data-behind refusal must not depend on dirt")
}
// #6575: the gate must refuse rather than auto-migrate this clone.
err = schema.CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt(
ctx, laggingConn, "origin", nil, realFastForwardAdopter())
var gateErr *schema.RemoteMigrateGateError
if !errors.As(err, &gateErr) {
t.Fatalf("data-behind clone (ahead=%d): expected the gate to refuse, got %v (#6575: schema parity is not proof of first-mover status)", ahead, err)
}
if gateErr.Decision != "" {
t.Errorf("Decision = %q, want \"\" (the blunt #4515 stop)", gateErr.Decision)
}
if !gateErr.IsDataBehind() {
t.Errorf("FallbackReason = %q, want %q", gateErr.FallbackReason, "data-behind")
}
if gateErr.DataDiverged != wantDiverged {
t.Errorf("DataDiverged = %v, want %v", gateErr.DataDiverged, wantDiverged)
}
msg := gateErr.UserMessage()
// The remedy has to be there, and has to be the one measured to work from
// this state: the refusal's own open classification lets `bd dolt pull`
// through (see embeddeddolt's TestEmbeddedOpenForRemoteSync_DataBehind).
if !strings.Contains(msg, schema.DataBehindRemedyCommand) {
t.Errorf("UserMessage does not carry the pull-first remedy:\n%s", msg)
}
if !strings.Contains(msg, wantRemedy) {
t.Errorf("UserMessage does not describe this shape's pull (%q):\n%s", wantRemedy, msg)
}
// No data motion: the refusal must not have moved the clone's HEAD.
aheadAfter, behindAfter, err := versioncontrolops.LocalAheadBehind(ctx, laggingConn, "remotes/origin/main")
if err != nil {
t.Fatalf("compare laggingClone HEAD to origin/main after refusal: %v", err)
}
if aheadAfter != ahead || behindAfter != behind {
t.Errorf("after refusal: ahead=%d behind=%d, want ahead=%d behind=%d (no data motion)",
aheadAfter, behindAfter, ahead, behind)
}
// --- remedy loop: `bd dolt pull` (a fast-forward for the strict-ancestor
// shape, a merge for the diverged one) leaves the clone with nothing left to
// pull, and the SAME gate call then auto-migrates it as a true first-mover.
// This is what keeps the fix from over-refusing. ---
if localCommits == 0 {
mustExec("pull (fast-forward)", laggingConn, "CALL DOLT_MERGE('--ff-only', 'remotes/origin/main')")
} else {
mustExec("pull (merge)", laggingConn, "CALL DOLT_MERGE('remotes/origin/main')")
}
_, behindAfterPull, err := versioncontrolops.LocalAheadBehind(ctx, laggingConn, "remotes/origin/main")
if err != nil {
t.Fatalf("LocalAheadBehind after pull: %v", err)
}
if behindAfterPull != 0 {
t.Fatalf("clone is still behind by %d after the pull; fixture broken", behindAfterPull)
}
if err := schema.CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt(
ctx, laggingConn, "origin", nil, realFastForwardAdopter()); err != nil {
t.Fatalf("the first-mover auto-migrate must be allowed once there is nothing left to pull, got %v", err)
}
}

View file

@ -141,6 +141,9 @@ func realFastForwardAdopter() *schema.FastForwardAdopter {
WorkingSetClean: func(ctx context.Context, db schema.DBConn) (bool, error) {
return versioncontrolops.WorkingSetClean(ctx, db)
},
AheadBehind: func(ctx context.Context, db schema.DBConn, ref string) (int, int, error) {
return versioncontrolops.LocalAheadBehind(ctx, db, ref)
},
FastForward: func(ctx context.Context, db schema.DBConn, ref string) error {
return versioncontrolops.FastForwardAdopt(ctx, db, ref)
},

View file

@ -382,6 +382,15 @@ type Config struct {
// open of a clean database converges normally.
LenientOpen bool
// RemoteSyncOpen is LenientOpen's narrow sibling for the #6575
// data-behind gate refusal: it tolerates ONLY that refusal (and only that
// refusal — not the dirty-table guard, not any other gate reason), because
// the refusal's documented remedy is `bd dolt pull`, which opens the store
// and so hit the refusal that prescribed it. Set for the remote-sync
// commands that can clear the refused precondition. Honored in embedded
// (openRemoteSync) and server mode alike.
RemoteSyncOpen bool
// Server connection options
ServerSocket string // Unix domain socket path (overrides Host/Port when set)
ServerHost string // Server host (default: 127.0.0.1)
@ -2041,7 +2050,9 @@ func newServerMode(ctx context.Context, cfg *Config) (*DoltStore, error) {
if !cfg.ReadOnly && !cfg.Gateway {
applied, err := store.initSchema(ctx, dbFacts.bootstrapHeal)
if err != nil {
if !cfg.LenientOpen || !warnLenientOpenRefusal(err) {
tolerated := (cfg.LenientOpen && warnLenientOpenRefusal(err)) ||
(cfg.RemoteSyncOpen && warnRemoteSyncOpenRefusal(err))
if !tolerated {
return nil, fmt.Errorf("failed to initialize schema: %w", err)
}
// A tolerated refusal still reports what the aborted pass
@ -2118,6 +2129,35 @@ func warnLenientOpenRefusal(err error) bool {
return false
}
// warnRemoteSyncOpenRefusal reports whether a remote-sync open
// (Config.RemoteSyncOpen) may continue past err instead of failing, warning on
// stderr when it may.
//
// It is warnLenientOpenRefusal's narrow sibling and tolerates exactly one
// refusal: the #6575 data-behind remote-migrate gate stop, whose documented
// remedy is `bd dolt pull` — a command that opens the store and therefore hit
// the very refusal that prescribed it. That is the #4566 deadlock shape, and
// #4566's own fix (a lenient open for `bd dolt commit`) is the precedent.
//
// Everything else — every other gate reason, the dirty-table guard, and any
// other migration failure — still fails the open here, exactly as on a strict
// open. A pull cannot resolve a fork skew, a below-floor database or a
// shared-store consent decision, so letting it through those refusals would
// buy nothing and hide them.
func warnRemoteSyncOpenRefusal(err error) bool {
var gateErr *schema.RemoteMigrateGateError
if errors.As(err, &gateErr) && gateErr.IsDataBehind() {
fmt.Fprintf(os.Stderr,
"Warning: %s"+
" Remote-sync command: continuing on schema v%d without migrating, so this\n"+
" pull can bring in the commits this clone is behind on. Re-run the command\n"+
" you were blocked on once it completes.\n",
gateErr.UserMessage(), gateErr.CurrentVersion)
return true
}
return false
}
var (
cleanServerCircuitState = CleanStaleCircuitBreakerFiles
newServerCircuitBreaker = maybeNewCircuitBreaker
@ -2913,6 +2953,13 @@ func (s *DoltStore) initSchema(ctx context.Context, bootstrapHeal *schema.FreshB
IsStrictAncestor: func(ctx context.Context, db schema.DBConn, ref string) (bool, error) {
return versioncontrolops.LocalIsStrictAncestorOf(ctx, db, ref)
},
// The raw counts the equal-version data-behind check needs
// (gastownhall/beads#6575): behind >= 1 whatever ahead is, plus
// which shape it is so the refusal names the pull the operator
// will actually get.
AheadBehind: func(ctx context.Context, db schema.DBConn, ref string) (int, int, error) {
return versioncontrolops.LocalAheadBehind(ctx, db, ref)
},
WorkingSetClean: func(ctx context.Context, db schema.DBConn) (bool, error) {
return versioncontrolops.WorkingSetClean(ctx, db)
},

View file

@ -54,6 +54,19 @@ func OpenForWorkingSetReconcile(ctx context.Context, beadsDir, database, branch
return openCached(ctx, beadsDir, database, branch, openWorkingSetReconcile)
}
// OpenForRemoteSync opens like Open, except that the #6575 data-behind
// remote-migrate gate refusal — and only that one — skips the pending
// migrations with a stderr warning instead of failing the open: that refusal's
// entire remedy is `bd dolt pull`, which opens the store itself and so hit the
// refusal that prescribed it, leaving the refused clone with no in-band exit at
// all (the same deadlock #4566 broke for `bd dolt commit`). Every other gate
// refusal, the dirty-table guard and the dependency re-key still fail this open
// exactly as they fail a strict one. The returned store is otherwise a normal
// writable store.
func OpenForRemoteSync(ctx context.Context, beadsDir, database, branch string) (*EmbeddedDoltStore, error) {
return openCached(ctx, beadsDir, database, branch, openRemoteSync)
}
func openCached(ctx context.Context, beadsDir, database, branch string, intent openIntent) (*EmbeddedDoltStore, error) {
key, err := cacheKey(beadsDir)
if err != nil {
@ -65,8 +78,9 @@ func openCached(ctx context.Context, beadsDir, database, branch string, intent o
// Cache hit: the requested intent is ignored - the store keeps
// whatever intent it was opened with on the slow path below. This is
// safe today because intent is derived once per process from the
// command classification (isReadOnlyCommand / isWorkingSetReconcileCommand
// in cmd/bd/main.go), so a single process never opens the same data
// command classification (isReadOnlyCommand /
// isWorkingSetReconcileCommand / isRemoteSyncCommand in
// cmd/bd/main.go), so a single process never opens the same data
// directory under two different intents, and autoMigrateOnVersionBump
// (cmd/bd/version_tracking.go) always opens its own openStrict store
// and closes it before the main command's open runs, so it never

View file

@ -0,0 +1,381 @@
//go:build cgo
package embeddeddolt_test
import (
"database/sql"
"errors"
"os"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads/internal/storage/embeddeddolt"
"github.com/steveyegge/beads/internal/storage/schema"
)
// buildDataBehindEmbedded leaves the embedded database at beadsDir in the
// #6575 state: level with its own cached remotes/origin/main on SCHEMA (both
// at latest-1, so the smart gate takes its equal-version first-mover path) and
// BEHIND it by one pure DATA commit. extraLocalCommits > 0 additionally gives
// it commits of its own, producing the diverged shape (ahead >= 1, behind >= 1).
//
// The behind-ness is produced the way the field cohort reaches it — a real
// file:// remote that has commits this history does not — rather than by
// stubbing the ancestry fact. A single database can build it because pushing
// C1 and then rewinding local HEAD to C0 leaves the remote-tracking ref ahead
// of the branch, which is exactly what a fetch-without-merge produces on a
// clone; no second engine is needed.
func buildDataBehindEmbedded(t *testing.T, beadsDir string, extraLocalCommits int) {
t.Helper()
ctx := t.Context()
dataDir := filepath.Join(beadsDir, "embeddeddolt")
store, err := embeddeddolt.Open(ctx, beadsDir, "testdb", "main")
if err != nil {
t.Fatalf("Open (create): %v", err)
}
store.Close()
db, cleanup, err := embeddeddolt.OpenSQL(ctx, dataDir, "testdb", "main")
if err != nil {
t.Fatalf("OpenSQL: %v", err)
}
defer func() { _ = cleanup() }()
mustExec := func(stage, q string, args ...any) {
t.Helper()
if _, err := db.ExecContext(ctx, q, args...); err != nil {
t.Fatalf("%s: %v", stage, err)
}
}
// C0: regress the schema cursor one migration below latest — the "old
// binary" state the 1.3.0 upgrade cohort is in — and publish it.
mustExec("regress schema cursor", "DELETE FROM schema_migrations WHERE version = ?", schema.LatestVersion())
mustExec("stage C0", "CALL DOLT_ADD('-A')")
mustExec("commit C0", "CALL DOLT_COMMIT('--allow-empty', '-m', 'test: regress schema cursor (C0)')")
var c0 string
if err := db.QueryRowContext(ctx, "SELECT commit_hash FROM dolt_log LIMIT 1").Scan(&c0); err != nil {
t.Fatalf("read C0 hash: %v", err)
}
mustExec("add remote", "CALL DOLT_REMOTE('add', 'origin', ?)",
"file://"+filepath.Join(t.TempDir(), "remote"))
mustExec("push C0", "CALL DOLT_PUSH('origin', 'main')")
// C1: a pure DATA commit, published. No schema change, so both sides stay
// at latest-1 and the gate lands on its equal-version path.
mustExec("data edit", "REPLACE INTO config (`key`, value) VALUES ('data-behind-marker', 'C1')")
mustExec("commit C1", "CALL DOLT_COMMIT('-Am', 'test: pure data commit (C1)')")
mustExec("push C1", "CALL DOLT_PUSH('origin', 'main')")
// Rewind the branch to C0. remotes/origin/main stays at C1, so this
// history is now behind its cached remote ref by one data commit.
mustExec("rewind to C0", "CALL DOLT_RESET('--hard', ?)", c0)
for i := 0; i < extraLocalCommits; i++ {
mustExec("local data edit", "REPLACE INTO config (`key`, value) VALUES ('local-marker', ?)", i)
mustExec("local commit", "CALL DOLT_COMMIT('-Am', 'test: local-only data commit')")
}
assertAheadBehind(t, db, extraLocalCommits, 1)
}
// assertAheadBehind pins the fixture's measured position against
// remotes/origin/main, so a refusal below can never be attributed to a fixture
// that failed to produce the state it claims.
func assertAheadBehind(t *testing.T, db *sql.DB, wantAhead, wantBehind int) {
t.Helper()
var ahead, behind int
if err := db.QueryRowContext(t.Context(), `
SELECT
(SELECT COUNT(*) FROM dolt_log WHERE commit_hash NOT IN
(SELECT commit_hash FROM dolt_log AS OF 'remotes/origin/main')) AS ahead,
(SELECT COUNT(*) FROM dolt_log AS OF 'remotes/origin/main' WHERE commit_hash NOT IN
(SELECT commit_hash FROM dolt_log)) AS behind
`).Scan(&ahead, &behind); err != nil {
t.Fatalf("measure ahead/behind: %v", err)
}
if ahead != wantAhead || behind != wantBehind {
t.Fatalf("fixture position = ahead %d, behind %d; want ahead %d, behind %d",
ahead, behind, wantAhead, wantBehind)
}
}
// pendingMigrationStillPending fails unless the binary's latest migration is
// still unapplied — i.e. the open under test did NOT migrate.
func pendingMigrationStillPending(t *testing.T, beadsDir string) {
t.Helper()
db, cleanup, err := embeddeddolt.OpenSQL(t.Context(), filepath.Join(beadsDir, "embeddeddolt"), "testdb", "main")
if err != nil {
t.Fatalf("OpenSQL (verify): %v", err)
}
defer func() { _ = cleanup() }()
var count int
if err := db.QueryRowContext(t.Context(),
"SELECT COUNT(*) FROM schema_migrations WHERE version = ?", schema.LatestVersion()).Scan(&count); err != nil {
t.Fatalf("read schema_migrations: %v", err)
}
if count != 0 {
t.Fatalf("the open applied the pending migration (version %d recorded); a data-behind clone must not migrate",
schema.LatestVersion())
}
}
// TestEmbeddedOpenForRemoteSync_DataBehind is the F1 regression test for
// gastownhall/beads#6575: the refusal must not block its own prescribed
// remedy.
//
// The data-behind stop tells the operator to run `bd dolt pull`. That command
// opens the store, and a strict open re-hits the refusal that prescribed it, so
// before this the refused clone had no in-band exit at all — on embedded there
// is no external `dolt` binary either, leaving only
// BD_ALLOW_REMOTE_MIGRATE=1, i.e. performing the migration the refusal exists
// to prevent. This is the same deadlock #4566 broke for `bd dolt commit`, and
// the remote-sync open is its narrow twin.
//
// Both shapes are covered: strict-ancestor (ahead 0) and diverged (ahead 1).
func TestEmbeddedOpenForRemoteSync_DataBehind(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt tests")
}
for _, tc := range []struct {
name string
extraLocalCommits int
wantDiverged bool
}{
{name: "strict ancestor (ahead 0, behind 1)", extraLocalCommits: 0},
{name: "diverged (ahead 1, behind 1)", extraLocalCommits: 1, wantDiverged: true},
} {
t.Run(tc.name, func(t *testing.T) {
t.Setenv(schema.AllowRemoteMigrateEnv, "0")
t.Setenv(schema.SmartGateEnv, "1")
schema.SetForceAllowRemoteMigrate(false)
ctx := t.Context()
beadsDir := filepath.Join(t.TempDir(), ".beads")
buildDataBehindEmbedded(t, beadsDir, tc.extraLocalCommits)
// A strict open still refuses, and refuses for the data-behind
// reason (not some other fixture artifact).
gated, gateErr := embeddeddolt.Open(ctx, beadsDir, "testdb", "main")
if gateErr == nil {
gated.Close()
t.Fatal("Open of a data-behind, remote-backed DB = nil error, want the #6575 refusal")
}
var rmErr *schema.RemoteMigrateGateError
if !errors.As(gateErr, &rmErr) {
t.Fatalf("Open error = %T (%v), want *schema.RemoteMigrateGateError", gateErr, gateErr)
}
if !rmErr.IsDataBehind() {
t.Fatalf("FallbackReason = %q, want the data-behind stop", rmErr.FallbackReason)
}
if rmErr.DataDiverged != tc.wantDiverged {
t.Errorf("DataDiverged = %v, want %v", rmErr.DataDiverged, tc.wantDiverged)
}
// ...and the remote-sync open — what `bd dolt pull` uses — gets
// through it, without migrating.
syncStore, syncErr := embeddeddolt.OpenForRemoteSync(ctx, beadsDir, "testdb", "main")
if syncErr != nil {
t.Fatalf("OpenForRemoteSync of a data-behind DB = %v; the refusal must not block the pull it prescribes (#6575)", syncErr)
}
syncStore.Close()
pendingMigrationStillPending(t, beadsDir)
})
}
}
// TestEmbeddedOpenForRemoteSync_OtherRefusalsStayFatal pins the narrowness of
// the exemption above, which is the whole reason it is keyed on the gate's
// REASON rather than being another blanket lenient open: a pull cannot resolve
// a fork skew, a below-floor database or an opted-out blunt block, so it must
// not be waved through them. Here BD_SMART_GATE=0 produces the blunt
// opted-out stop on the very same fixture that the data-behind case above
// opens successfully.
func TestEmbeddedOpenForRemoteSync_OtherRefusalsStayFatal(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt tests")
}
t.Setenv(schema.AllowRemoteMigrateEnv, "0")
schema.SetForceAllowRemoteMigrate(false)
ctx := t.Context()
beadsDir := filepath.Join(t.TempDir(), ".beads")
// Build the fixture with the smart gate ON (the fixture helper's own
// Open must not be the thing that is opted out), then opt out for the
// probe below.
t.Setenv(schema.SmartGateEnv, "1")
buildDataBehindEmbedded(t, beadsDir, 0)
t.Setenv(schema.SmartGateEnv, "0")
store, err := embeddeddolt.OpenForRemoteSync(ctx, beadsDir, "testdb", "main")
if err == nil {
store.Close()
t.Fatal("OpenForRemoteSync = nil error with BD_SMART_GATE=0; the exemption must apply to the data-behind reason only")
}
var rmErr *schema.RemoteMigrateGateError
if !errors.As(err, &rmErr) {
t.Fatalf("error = %T (%v), want *schema.RemoteMigrateGateError", err, err)
}
if rmErr.IsDataBehind() {
t.Fatalf("FallbackReason = %q; with the smart gate off this must be the blunt opted-out stop", rmErr.FallbackReason)
}
}
// TestEmbeddedLenientOpenWarning_DataBehind is the READ-path half of
// gastownhall/beads#6575, and the half the write-path fix missed.
//
// The lenient embedded opens do not fail on this refusal — they warn and carry
// on — so the warning IS the entire user-facing contract for `bd list`,
// `bd ready`, `bd show` (openReadOnlyCommand) and `bd dolt commit`
// (openWorkingSetReconcile). Those are the first commands a 1.1-era upgrader
// runs and the ones agents run constantly, and they printed the blunt #4259
// coordination bullets: `bd migrate --force && bd dolt push`, which on a
// data-behind clone applies the migration this stop exists to prevent and then
// fails the push non-fast-forward, and `bd bootstrap`, which no-ops against an
// existing workspace. A fence whose own signage pointed into the wedge.
//
// The assertions are deliberately two-sided — the pull must be present AND the
// wedge commands must be absent — because the previous round satisfied
// "mentions the remedy somewhere" while still printing the bullets underneath
// it.
func TestEmbeddedLenientOpenWarning_DataBehind(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt tests")
}
shapes := []struct {
name string
extraLocalCommits int
wantShapeText string
notShapeText string
}{
{
name: "fast-forward (ahead 0, behind 1)",
wantShapeText: "pure fast-forward",
notShapeText: "MERGES rather than",
},
{
name: "diverged (ahead 1, behind 1)",
extraLocalCommits: 1,
wantShapeText: "MERGES rather than",
notShapeText: "pure fast-forward",
},
}
intents := []struct {
name string
open func(t *testing.T, beadsDir string) (*embeddeddolt.EmbeddedDoltStore, error)
modeText string
}{
{
name: "openReadOnlyCommand (bd list)",
open: func(t *testing.T, beadsDir string) (*embeddeddolt.EmbeddedDoltStore, error) {
return embeddeddolt.OpenForReadOnlyCommand(t.Context(), beadsDir, "testdb", "main")
},
modeText: "Read-only command: continuing on schema v",
},
{
name: "openWorkingSetReconcile (bd dolt commit)",
open: func(t *testing.T, beadsDir string) (*embeddeddolt.EmbeddedDoltStore, error) {
return embeddeddolt.OpenForWorkingSetReconcile(t.Context(), beadsDir, "testdb", "main")
},
modeText: "Working-set reconcile command: continuing on schema v",
},
}
for _, shape := range shapes {
for _, intent := range intents {
t.Run(shape.name+"/"+intent.name, func(t *testing.T) {
t.Setenv(schema.AllowRemoteMigrateEnv, "0")
t.Setenv(schema.SmartGateEnv, "1")
schema.SetForceAllowRemoteMigrate(false)
beadsDir := filepath.Join(t.TempDir(), ".beads")
buildDataBehindEmbedded(t, beadsDir, shape.extraLocalCommits)
var store *embeddeddolt.EmbeddedDoltStore
var openErr error
warning := captureStderr(t, func() {
store, openErr = intent.open(t, beadsDir)
})
if openErr != nil {
t.Fatalf("lenient open of a data-behind DB = %v; it must warn and continue", openErr)
}
store.Close()
pendingMigrationStillPending(t, beadsDir)
for _, want := range []string{
schema.DataBehindRemedyCommand,
"This clone is BEHIND the remote",
"Do NOT use `bd migrate --force` to get past this",
shape.wantShapeText,
intent.modeText,
} {
if !strings.Contains(warning, want) {
t.Errorf("warning is missing %q; got:\n%s", want, warning)
}
}
if strings.Contains(warning, shape.notShapeText) {
t.Errorf("warning describes the wrong pull shape (%q); got:\n%s", shape.notShapeText, warning)
}
// The blunt #4259 coordination bullets, which ARE the #6575
// wedge when this is the refusal.
for _, unwanted := range []string{
"bd migrate --force && bd dolt push",
"designated migrator (only ONE machine)",
"bd bootstrap",
} {
if strings.Contains(warning, unwanted) {
t.Errorf("warning still prescribes %q on a data-behind clone; got:\n%s", unwanted, warning)
}
}
})
}
}
}
// TestEmbeddedLenientOpenWarning_OtherRefusalsKeepBluntGuidance is the other
// side of that fence. The data-behind body REPLACES the blunt coordination
// bullets rather than decorating them, so it must not swallow them for the
// refusals they are right for. BD_SMART_GATE=0 turns the same fixture into the
// blunt opted-out stop, where migrate-or-adopt genuinely is the decision.
func TestEmbeddedLenientOpenWarning_OtherRefusalsKeepBluntGuidance(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt tests")
}
t.Setenv(schema.AllowRemoteMigrateEnv, "0")
schema.SetForceAllowRemoteMigrate(false)
beadsDir := filepath.Join(t.TempDir(), ".beads")
t.Setenv(schema.SmartGateEnv, "1")
buildDataBehindEmbedded(t, beadsDir, 0)
t.Setenv(schema.SmartGateEnv, "0")
var store *embeddeddolt.EmbeddedDoltStore
var openErr error
warning := captureStderr(t, func() {
store, openErr = embeddeddolt.OpenForReadOnlyCommand(t.Context(), beadsDir, "testdb", "main")
})
if openErr != nil {
t.Fatalf("lenient open with the smart gate off = %v; it must warn and continue", openErr)
}
store.Close()
for _, want := range []string{
"designated migrator (only ONE machine): bd migrate --force && bd dolt push",
"every other clone (another already migrated): bd bootstrap",
"Read-only command: continuing on schema v",
} {
if !strings.Contains(warning, want) {
t.Errorf("blunt warning is missing %q; got:\n%s", want, warning)
}
}
if strings.Contains(warning, "This clone is BEHIND the remote") {
t.Errorf("the data-behind body leaked into a non-data-behind refusal; got:\n%s", warning)
}
}

View file

@ -66,9 +66,11 @@ type EmbeddedDoltStore struct {
}
// openIntent classifies why a store is being opened. openStrict fails the
// open on any pending-migration refusal; the other two intents relax both
// the #4259 remote-migrate gate refusal and the #4566 dirty-table refusal,
// each with its own warning text (see initSchema).
// open on any pending-migration refusal; openReadOnlyCommand and
// openWorkingSetReconcile relax both the #4259 remote-migrate gate refusal and
// the #4566 dirty-table refusal, each with its own warning text (see
// initSchema); openRemoteSync relaxes exactly one gate refusal and nothing
// else.
type openIntent int
const (
@ -86,8 +88,52 @@ const (
// touch, so failing the open here would deadlock the documented recovery
// (#4566). Used by OpenForWorkingSetReconcile.
openWorkingSetReconcile
// openRemoteSync is the same shape of deadlock break as
// openWorkingSetReconcile, for the #6575 data-behind gate refusal: that
// refusal's entire remedy is `bd dolt pull`, which itself opens the store
// and so hit the refusal that prescribed it — a fence with no gate. Unlike
// the two intents above it relaxes exactly ONE refusal and nothing else:
// only a gate error whose reason is data-behind
// (RemoteMigrateGateError.IsDataBehind). Every other gate refusal, the
// #4566 dirty-table guard, and the #5268 dependency re-key still fail this
// open exactly as they do a strict one — the pull is being let through its
// own precondition, not granted a general exemption. Used by
// OpenForRemoteSync.
openRemoteSync
)
// toleratesGateRefusal reports whether this open's intent may warn and
// continue past a remote-migrate gate refusal (#4259/#5920/#6575) instead of
// failing the open.
//
// openRemoteSync is deliberately conditional on the REASON rather than being
// another blanket exemption: it exists only so `bd dolt pull` can execute the
// #6575 data-behind refusal's own remedy, and widening it to every gate
// refusal would quietly let a pull through a fork-skew or shared-store stop
// that the pull cannot help with.
func (s *EmbeddedDoltStore) toleratesGateRefusal(gateErr *schema.RemoteMigrateGateError) bool {
switch s.intent {
case openReadOnlyCommand, openWorkingSetReconcile:
return true
case openRemoteSync:
return gateErr.IsDataBehind()
default: // openStrict
return false
}
}
// toleratesMigrationRefusal reports whether this open's intent may warn and
// continue past a MigrateUp refusal that is not the gate: the #4566
// dirty-table guard and the #5268 dependency re-key conflict.
//
// openRemoteSync is absent on purpose. It is not listed as "not openStrict"
// because that phrasing is what would have silently enrolled it: the remote-
// sync exemption was granted for one gate reason, and a dirty working set or a
// re-key conflict is a different refusal with a different recovery.
func (s *EmbeddedDoltStore) toleratesMigrationRefusal() bool {
return s.intent == openReadOnlyCommand || s.intent == openWorkingSetReconcile
}
// errClosed is returned when a method is called after Close.
var errClosed = errors.New("embeddeddolt: store is closed")
@ -369,6 +415,13 @@ func (s *EmbeddedDoltStore) initSchema(ctx context.Context) error {
IsStrictAncestor: func(ctx context.Context, db schema.DBConn, ref string) (bool, error) {
return versioncontrolops.LocalIsStrictAncestorOf(ctx, db, ref)
},
// The raw counts the equal-version data-behind check needs
// (gastownhall/beads#6575): behind >= 1 whatever ahead is, plus
// which shape it is so the refusal names the pull the operator
// will actually get.
AheadBehind: func(ctx context.Context, db schema.DBConn, ref string) (int, int, error) {
return versioncontrolops.LocalAheadBehind(ctx, db, ref)
},
WorkingSetClean: func(ctx context.Context, db schema.DBConn) (bool, error) {
return versioncontrolops.WorkingSetClean(ctx, db)
},
@ -388,7 +441,7 @@ func (s *EmbeddedDoltStore) initSchema(ctx context.Context) error {
}
if err := schema.CheckRemoteMigrateGateWithAdopt(ctx, conn, adopt); err != nil {
var gateErr *schema.RemoteMigrateGateError
if s.intent != openStrict && errors.As(err, &gateErr) {
if errors.As(err, &gateErr) && s.toleratesGateRefusal(gateErr) {
// The gate exists to stop in-place migration on a remote-backed,
// already-initialized database (#4259), not to block reads or a
// working-set commit. Warn and continue on the current schema;
@ -402,20 +455,76 @@ func (s *EmbeddedDoltStore) initSchema(ctx context.Context) error {
" • every other clone (another already migrated): bd bootstrap\n" +
" • several machines: only ONE migrates; sync each other clone and run\n" +
" bd dolt pull after the migrator pushes, before upgrading it\n"
// #6575: sharedGuidance is the blunt migrate-or-adopt block, and
// on the data-behind stop every bullet in it is measurably wrong
// — `bd migrate --force` applies the migration this stop exists
// to prevent, the `bd dolt push` after it is rejected
// non-fast-forward while the clone is still behind, and
// `bd bootstrap` no-ops against an existing workspace. The one
// command that moves the clone forward is `bd dolt pull`, and
// gateErr's own UserMessage is where that body lives, already
// branched for the fast-forward and diverged pulls. Printing
// %v (Error(), the one-line summary) and appending the bullets
// dropped it: a 1.1-era upgrader's first `bd list` and their
// `bd dolt commit` both land in the two arms below, so the first
// thing bd said to a data-behind clone was the wedge. Server
// mode's warnLenientOpenRefusal (dolt/store.go) has rendered
// UserMessage all along; these arms are the ones that lagged.
//
// The intent framing stays: the command in hand is still
// SUCCEEDING against the old schema, which UserMessage — written
// for the fatal refusal — does not say. So the mode line is
// appended to the data-behind body rather than replacing it.
body := "Warning: " + gateErr.Error() + "\n"
if gateErr.IsDataBehind() {
body = "Warning: " + gateErr.UserMessage()
}
switch s.intent {
case openWorkingSetReconcile:
case openRemoteSync:
// This is the refusal's own prescribed remedy running. It gets
// the short confirmation rather than the full data-behind body:
// toleratesGateRefusal admits only the data-behind stop here, so
// the operator has necessarily just been handed that body by the
// command this pull is unblocking, and re-printing "pull first"
// at the moment they are finally doing it is noise. What it must
// never do is name `bd migrate --force`.
fmt.Fprintf(os.Stderr,
"Warning: %[1]v\n"+
" Remote-sync command: continuing on schema v%[2]d without migrating, so\n"+
" this pull can bring in the commits this clone is behind on. Re-run the\n"+
" command you were blocked on once it completes.\n",
gateErr, gateErr.CurrentVersion)
case openWorkingSetReconcile:
if gateErr.IsDataBehind() {
fmt.Fprintf(os.Stderr,
"%[1]s"+
" Working-set reconcile command: continuing on schema v%[2]d without\n"+
" migrating; the commit applies to the working set at the current\n"+
" schema. It does not resolve the schema — the pull above is what does.\n",
body, gateErr.CurrentVersion)
break
}
fmt.Fprintf(os.Stderr,
"%[1]s"+
" Working-set reconcile command: continuing on schema v%[2]d without\n"+
" migrating; the commit applies to the working set at the current\n"+
" schema."+sharedGuidance,
gateErr, gateErr.CurrentVersion)
body, gateErr.CurrentVersion)
default: // openReadOnlyCommand
if gateErr.IsDataBehind() {
fmt.Fprintf(os.Stderr,
"%[1]s"+
" Read-only command: continuing on schema v%[2]d without migrating, so\n"+
" this read succeeds against the old schema. Writes stay blocked until\n"+
" this clone has pulled.\n",
body, gateErr.CurrentVersion)
break
}
fmt.Fprintf(os.Stderr,
"Warning: %[1]v\n"+
"%[1]s"+
" Read-only command: continuing on schema v%[2]d without migrating.\n"+
" Writes are blocked until the schema is reconciled."+sharedGuidance,
gateErr, gateErr.CurrentVersion)
body, gateErr.CurrentVersion)
}
return nil
}
@ -426,7 +535,7 @@ func (s *EmbeddedDoltStore) initSchema(ctx context.Context) error {
// controls; schema.MigrateUpWithLock requires a sql-server session lock.
if _, err := schema.MigrateUp(ctx, conn); err != nil {
var dirtyErr *schema.DirtyTablesError
if s.intent != openStrict && errors.As(err, &dirtyErr) {
if s.toleratesMigrationRefusal() && errors.As(err, &dirtyErr) {
// The guard exists to keep dirty user data from being entangled
// with a migration, but its documented recovery - committing the
// working set - also opens the store and would otherwise hit
@ -451,7 +560,7 @@ func (s *EmbeddedDoltStore) initSchema(ctx context.Context) error {
return nil
}
var rekeyErr *schema.DependencyRekeyConflictError
if s.intent != openStrict && errors.As(err, &rekeyErr) {
if s.toleratesMigrationRefusal() && errors.As(err, &rekeyErr) {
// Same principle for the dependency re-key's refusal (#5268): it is
// a convergence repair, not a precondition for reading, and before
// that pass existed these clones opened fine. Bricking 'bd list' and

View file

@ -40,3 +40,8 @@ func OpenForReadOnlyCommand(_ context.Context, _, _, _ string) (*EmbeddedDoltSto
func OpenForWorkingSetReconcile(_ context.Context, _, _, _ string) (*EmbeddedDoltStore, error) {
return nil, errNoCGO
}
// OpenForRemoteSync returns an error when CGO is not enabled.
func OpenForRemoteSync(_ context.Context, _, _, _ string) (*EmbeddedDoltStore, error) {
return nil, errNoCGO
}

View file

@ -118,6 +118,15 @@ type RemoteMigrateGateError struct {
// (the gate staying enabled by default). Set only when
// FallbackReason == fallbackReasonUnparseableEnv.
UnrecognizedSmartGateEnv string
// DataDiverged distinguishes the two shapes of the data-behind stop
// (gastownhall/beads#6575). Both are "this clone is missing commits the
// remote has", and both take the same remedy COMMAND — `bd dolt pull` —
// but false means the clone has no commits of its own so the pull is a
// pure fast-forward, and true means it has both, so the pull MERGES and
// can report conflicts to resolve first. Set only when
// FallbackReason == fallbackReasonDataBehind; meaningless otherwise.
DataDiverged bool
}
const (
@ -161,8 +170,37 @@ const (
// auto-executing it would promote the schema for every co-resident client.
// Structural, not a routing outcome — it outranks the other reasons.
fallbackReasonSharedStore = "shared-store"
// fallbackReasonDataBehind (gastownhall/beads#6575): schema parity with
// the cached remote ref held, but this clone's local HEAD is a strict
// ancestor of that ref — it is behind the remote in data commits it has
// not pulled, so it is not the first-mover the smart gate may
// auto-resolve. Unlike the reasons above, this one has a one-command
// remedy the operator can run right now (`bd dolt pull`), after which the
// migrate is a true first-mover.
fallbackReasonDataBehind = "data-behind"
)
// DataBehindRemedyCommand is the one command that moves a data-behind clone
// forward, and the single source for every surface that names it: the human
// body and note, the agent directive, the JSON option, and the store-open
// classification that has to let this command through the very refusal that
// prescribes it (gastownhall/beads#6575 F1 — a refusal whose documented
// recovery is blocked by the refusal is a fence with no gate; the #4566
// precedent for `bd dolt commit` is the same shape).
const DataBehindRemedyCommand = "bd dolt pull"
// IsDataBehind reports whether this refusal is the #6575 data-behind stop:
// the clone is level with the cached remote ref on schema but missing commits
// the ref has, so the pending migration must not be applied until it pulls.
//
// It is exported because the recovery for this particular stop is itself a
// store-opening command (DataBehindRemedyCommand), so the mode-specific store
// opens have to recognize this reason — and ONLY this reason — to open
// leniently for it. Every other refusal stays fatal on those opens.
func (e *RemoteMigrateGateError) IsDataBehind() bool {
return e != nil && e.Decision == "" && e.FallbackReason == fallbackReasonDataBehind
}
func (e *RemoteMigrateGateError) Error() string {
unit := "migrations"
if e.Pending == 1 {
@ -229,15 +267,97 @@ func (e *RemoteMigrateGateError) fallbackReasonNote() string {
why = SmartGateEnv + "=" + e.UnrecognizedSmartGateEnv + " is set but was not recognized (only boolean values enable/disable it), so it stayed enabled by default but still could not resolve this stop"
case fallbackReasonSharedStore:
why = "this store is shared (dolt sql-server); the first-mover auto-migrate is disabled here because it would lock out co-resident clients (#5920)"
case fallbackReasonDataBehind:
why = "this clone is behind the remote in data commits it has not pulled, so it is not the first-mover it looks like on schema alone — migrating in place would diverge from those commits, and can leave every later `bd dolt pull` refusing to merge (#6575, #6368). Run `" + DataBehindRemedyCommand + "` first, then retry: this clone is then the true first-mover it looked like"
// Only promise the retry resolves itself where it actually does. On a
// shared store the first-mover auto-migrate is suppressed regardless
// (fallbackReasonSharedStore, #5920), so pulling clears THIS stop but
// the retry still needs explicit consent — saying otherwise would send
// the operator in a loop.
if !e.Shared {
why += " and the migrate proceeds on its own"
} else {
// #5920's consequence has to travel with this reason too. Before
// this arm existed a shared, data-behind store reported
// fallbackReasonSharedStore, whose note names the co-resident
// lockout; data-behind now outranks it, so without this clause the
// operator loses the warning that promoting the schema on a shared
// server locks out every co-resident client still on an older bd.
why += " — but on this shared store the migrate still needs explicit consent (`" + SharedConsentCommand + "`), because it promotes the schema for every co-resident bd client at once and clients still on an older binary will refuse this database until they are upgraded (#5920)"
}
default:
return ""
}
return "\n Smart gate (#4516): " + why + ".\n"
}
// dataBehindBody is the guidance block for the #6575 data-behind stop. It
// REPLACES the blunt migrate-or-adopt body rather than decorating it, because
// in this state both of that body's options are wrong and were measured wrong:
// `bd migrate --force` is exactly the migration this stop exists to prevent
// (and the `bd dolt push` that follows it is rejected as a non-fast-forward,
// since the clone is still behind), and `bd bootstrap` against an existing
// workspace reports "Database already exists … Nothing to do." and exits 0.
// The one command that moves this clone forward is the pull.
func (e *RemoteMigrateGateError) dataBehindBody() string {
body := "\n" +
" This clone is BEHIND the remote: the remote has commits this clone has not\n" +
" pulled. On schema alone it looks like a first-mover, which is why the line\n" +
" above reads the way it does — but applying the pending migration here would\n" +
" put new schema commits on a history that is missing those commits. Once a\n" +
" migration moves a tracked table onto Dolt's ignore plane (0062's `events`),\n" +
" every later `" + DataBehindRemedyCommand + "` refuses to merge and this clone can no longer\n" +
" fetch the commits it was already behind on (#6575, #6368).\n" +
"\n" +
" Pull first — that is the whole remedy:\n" +
" " + DataBehindRemedyCommand + "\n"
if e.DataDiverged {
body += "" +
" This clone also has commits of its own, so the pull MERGES rather than\n" +
" fast-forwards. If it reports conflicts, resolve them and let the pull\n" +
" finish before retrying (`" + DataBehindRemedyCommand + " --strategy ours|theirs` decides them\n" +
" in bulk on embedded storage; `bd conflicts resolve` on a server store).\n"
} else {
body += "" +
" This clone has no commits of its own, so the pull is a pure fast-forward:\n" +
" nothing local is merged or discarded.\n"
}
body += "" +
"\n" +
" Then re-run what you just ran.\n"
if e.Shared {
// #5920: on a shared store the first-mover auto-migrate stays
// suppressed after the pull, so the retry needs the consent verb.
// Saying "it proceeds on its own" here would loop the operator.
body += "" +
" This database is served to co-resident bd clients, so the migration itself\n" +
" still needs explicit consent afterwards — it promotes the schema for EVERY\n" +
" client at once, and clients still on an older bd will refuse this database\n" +
" until they are upgraded (#5920):\n" +
" " + SharedConsentCommand + "\n" +
" (" + SharedConsentCommandGlobal + " for the shared global database)\n"
} else {
body += "" +
" The migration then runs on its own: with nothing left to pull, this clone\n" +
" is the first-mover it looked like.\n"
}
body += "" +
"\n" +
" Do NOT use `bd migrate --force` to get past this. It applies the migration\n" +
" while this clone is still behind — the exact state this stop exists to\n" +
" prevent — and the `bd dolt push` that would follow is rejected as a\n" +
" non-fast-forward, because the clone is still missing the remote's commits.\n"
return body
}
// userBody returns the decision-specific guidance block. The default (blunt
// #4515) body is byte-identical to before the smart gate existed.
func (e *RemoteMigrateGateError) userBody() string {
// The #6575 stop is a blunt stop (empty Decision) with a remedy the blunt
// body contradicts, so it is keyed on the fallback reason instead.
if e.IsDataBehind() {
return e.dataBehindBody()
}
switch e.Decision {
case gateDecisionAdopt:
return "\n" +
@ -332,6 +452,35 @@ func (e *RemoteMigrateGateError) EscapeHint() string {
// to the operator and let them choose, per the AgentDiagnostic contract ("Go
// observes and reports, the agent decides and acts").
func (e *RemoteMigrateGateError) AgentDirective() string {
// #6575: the data-behind stop is the one refusal in this type with a
// single, safe, non-destructive, auto-runnable remedy — pulling commits
// this clone is already behind on takes nothing away and needs no
// cross-clone coordination. Saying so is the point: the default directive
// below sends the agent to remote_migrate_gate.options, and if those
// options were the blunt migrate-or-adopt pair the agent would surface
// the migration this stop exists to prevent (whose follow-up push is
// rejected non-fast-forward anyway) and a bootstrap that no-ops.
if e.IsDataBehind() {
d := "Pull, do NOT migrate: this clone is level with the remote on schema but is missing commits the remote " +
"has, so the pending migration would land on a history without them and can wedge every later " +
"`" + DataBehindRemedyCommand + "` (#6575, #6368). The remedy is `" + DataBehindRemedyCommand + "`, which is in " +
"remote_migrate_gate.options as the single option."
if e.DataDiverged {
d += " This clone also has commits of its own, so that pull MERGES rather than fast-forwards and may " +
"report conflicts to resolve before it completes — surface a conflict outcome to the operator " +
"rather than forcing past it."
} else {
d += " This clone has no commits of its own, so that pull is a pure fast-forward and discards nothing."
}
if e.Shared {
d += " After the pull the migration still needs the operator's explicit consent (" + SharedConsentCommand +
"): this database is shared with co-resident bd clients and migrating promotes the schema for all of " +
"them at once (#5920). Do NOT auto-run it."
} else {
d += " After the pull, re-running the original command migrates on its own; nothing else is needed."
}
return d
}
switch e.Decision {
case gateDecisionAdopt:
return "Adopt, do NOT migrate: the remote is already migrated, so migrating here would fork it (#4259). " +
@ -392,6 +541,39 @@ func (e *RemoteMigrateGateError) Options() []GateOption {
Commands: []string{"bd bootstrap"},
Risk: "re-clones and replaces the local database; push or export unpushed work first or it is lost" + sharedRisk,
}
// #6575: exactly ONE option, and it is the pull. The blunt pair below is
// actively wrong in this state — `bd migrate --force` is the bug, its
// `bd dolt push` is rejected non-fast-forward while the clone is still
// behind, and `bd bootstrap` no-ops against an existing workspace — so
// offering them here would hand an agent two dead ends and no exit.
// Unlike every other option in this type it carries no precondition the
// operator has to confirm: pulling commits this clone is already behind on
// is not a coordination decision.
if e.IsDataBehind() {
risk := "none — a pure fast-forward; this clone has no commits of its own, so nothing local is merged or discarded"
when := "always, for this stop: this clone is behind the remote and must pull before it may migrate"
if e.DataDiverged {
risk = "this clone also has commits of its own, so the pull MERGES; it can report conflicts that must be resolved before it completes (bd dolt pull --strategy ours|theirs on embedded storage, bd conflicts resolve on a server store). Nothing is discarded without that resolution"
}
pull := GateOption{
ID: "pull-first",
When: when,
Commands: []string{DataBehindRemedyCommand},
Risk: risk,
}
if e.Shared {
// The pull itself is still safe; what the shared store changes is
// what happens AFTER it, so the consent step becomes a second
// option rather than a footnote on the first (#5920).
return []GateOption{pull, {
ID: "migrate-shared-after-pulling",
When: "the pull above has completed AND every co-resident bd client of this server is upgraded to this binary (confirmed with the operator)",
Commands: []string{SharedConsentCommand},
Risk: "co-resident clients still on an older bd will refuse this database until upgraded; running it before the pull completes is the wedge this stop prevents",
}}
}
return []GateOption{pull}
}
switch e.Decision {
case gateDecisionAdopt:
// Remote is confirmed ahead: migrate is not a valid path, only adopt.
@ -584,6 +766,10 @@ func checkRemoteMigrateGate(ctx context.Context, db DBConn, remoteName string, e
// follow-up).
fallbackReason := ""
unrecognizedSmartGateEnv := ""
// dataDiverged records which shape of the #6575 data-behind stop fired, so
// the guidance names the pull the operator will actually get (a merge, not
// a fast-forward). Meaningless unless fallbackReason is data-behind.
dataDiverged := false
if SmartGateEnabled() {
decision, skew, ref, atLatest := routeSmartGate(ctx, db, current, latest, remoteName, adopt)
switch decision {
@ -669,6 +855,25 @@ func checkRemoteMigrateGate(ctx context.Context, db DBConn, remoteName string, e
Decision: gateDecisionForkSkew,
SkewVersions: skew,
}
case smartDataBehind, smartDataDiverged:
// gastownhall/beads#6575: schema parity held but this clone is
// missing commits the cached remote ref has. Stop, and carry the
// pull-first remedy on every surface (body, note, agent directive,
// options) — the blunt migrate-or-adopt guidance is wrong here,
// not merely incomplete.
//
// This reason is reported even on a shared store, where
// fallbackReasonSharedStore would otherwise outrank it: that one
// says the gate WOULD have resolved and was overruled, which is
// not true here. The gate refuses this state on its own merits,
// and the pull-first remedy is a precondition the operator has to
// satisfy either way; #5920's co-resident consequence is folded
// into the data-behind guidance instead of being lost with the
// reason it outranks.
fallbackReason = fallbackReasonDataBehind
// The two verdicts share the reason and the remedy command; they
// differ in whether that command fast-forwards or merges.
dataDiverged = decision == smartDataDiverged
case smartBelowFloor:
fallbackReason = fallbackReasonBelowFloor
case smartUndetermined:
@ -679,9 +884,15 @@ func checkRemoteMigrateGate(ctx context.Context, db DBConn, remoteName string, e
// fact for the operator than the technical routing outcome, so it
// takes priority as the surfaced reason. Not over shared-store: that
// one is structural (the gate WOULD have resolved, and was overruled),
// so fixing the env value would not change the outcome.
// so fixing the env value would not change the outcome. Not over
// data-behind either, for the same reason (gastownhall/beads#6575):
// that stop stands whatever BD_SMART_GATE says, and it is the one
// reason carrying a remedy the operator can act on right now, so
// burying it behind an env-value complaint would cost them the fix.
envState, envValue := smartGateEnvValue()
if envState == smartGateEnvUnparseable && fallbackReason != fallbackReasonSharedStore {
if envState == smartGateEnvUnparseable &&
fallbackReason != fallbackReasonSharedStore &&
fallbackReason != fallbackReasonDataBehind {
fallbackReason = fallbackReasonUnparseableEnv
unrecognizedSmartGateEnv = envValue
}
@ -697,6 +908,7 @@ func checkRemoteMigrateGate(ctx context.Context, db DBConn, remoteName string, e
FallbackReason: fallbackReason,
Shared: shared,
UnrecognizedSmartGateEnv: unrecognizedSmartGateEnv,
DataDiverged: dataDiverged,
}
}

View file

@ -12,9 +12,10 @@ import (
// gate would fire, it consults the remote's cached schema state and
// auto-resolves the one provably-safe case (first-mover migrate), while still
// stopping — with sharper guidance — on the cases that genuinely need a human.
// Every fallback path (unreadable remote state, below the convergence floor)
// degrades to the blunt #4515 block, so the default is never less safe than
// the blunt gate; it only resolves cases the blunt gate cannot distinguish.
// Every fallback path (unreadable remote state, below the convergence floor,
// a clone behind the remote in data commits) degrades to the blunt #4515
// block, so the default is never less safe than the blunt gate; it only
// resolves cases the blunt gate cannot distinguish.
//
// Set BD_SMART_GATE=0 (or any boolean false) to opt out and keep the blunt
// #4515 behavior unconditionally: any remote-backed database with pending
@ -128,6 +129,28 @@ const (
// a TOCTOU miss, or the merge itself refusing) falls through to the
// plain smartAdopt directive instead, never forcing the write.
smartAdoptFastForward
// smartDataBehind (gastownhall/beads#6575): schema parity with the cached
// remote ref holds — the first-mover precondition — but local HEAD is
// BEHIND that ref with no local commits of its own (ahead == 0,
// behind >= 1), so this clone is missing DATA commits it has not pulled.
// Migrating in place here mints local-only schema commits on a HEAD that
// lacks those commits; when the pending batch moves a tracked table onto
// the dolt_ignore plane (0062's events), every subsequent `bd dolt pull`
// then refuses (#6368) and the clone can no longer fetch the very commits
// it was behind on. Stop, and direct the operator to pull first — a pure
// fast-forward in this shape — after which the same open auto-migrates as
// a true first-mover.
smartDataBehind
// smartDataDiverged is smartDataBehind's other shape: behind >= 1 AND
// ahead >= 1, i.e. this clone has unpushed local commits as well as
// unpulled remote ones. It reaches the identical wedge — the pending
// migration lands on a HEAD missing the remote's commits either way — so
// it stops for the same reason. It is a separate verdict only because the
// remedy behaves differently: `bd dolt pull` MERGES here rather than
// fast-forwarding, and can report conflicts the operator has to resolve
// before it completes. bd auto-commits every write, so this is the
// ORDINARY multi-machine shape, not an exotic one.
smartDataDiverged
)
// FastForwardAdopter injects the driver-side fast-forward primitives that
@ -149,6 +172,20 @@ type FastForwardAdopter struct {
// IsStrictAncestor reports whether local HEAD is a strict ancestor of
// ref (versioncontrolops.LocalIsStrictAncestorOf).
IsStrictAncestor func(ctx context.Context, db DBConn, ref string) (bool, error)
// AheadBehind reports the raw commit counts behind IsStrictAncestor:
// how many commits local HEAD has that ref lacks, and how many ref has
// that local lacks (versioncontrolops.LocalAheadBehind). The
// data-behind stop (gastownhall/beads#6575) needs behind >= 1 whatever
// ahead is, which IsStrictAncestor's ahead == 0 && behind >= 1 cannot
// express, and needs to tell the two shapes apart so the remedy it
// prints matches the pull the operator will actually get (fast-forward
// vs merge).
//
// A nil AheadBehind is safe: localDataBehind falls back to
// IsStrictAncestor, which reports only the ahead == 0 shape — the
// narrower, pre-#6575-widening behavior — so an injection site that
// wires only the older callback keeps working.
AheadBehind func(ctx context.Context, db DBConn, ref string) (ahead, behind int, err error)
// WorkingSetClean reports whether the working set has no uncommitted
// changes, dolt-ignored wisp tables excepted
// (versioncontrolops.WorkingSetClean).
@ -194,6 +231,54 @@ func routeAdoptFastForward(ctx context.Context, db DBConn, ref string, adopt *Fa
return true
}
// localDataBehind reports whether local HEAD is missing commits that ref has
// (behind >= 1) and, when it is, whether the clone ALSO has commits of its own
// that ref lacks (ahead >= 1 — the diverged shape). It is the equal-version
// path's only ancestry fact (gastownhall/beads#6575).
//
// The predicate is behind >= 1 regardless of ahead, not the narrower strict-
// ancestor relation the remote-ahead path uses. Both shapes reach the same
// wedge: the migration lands on a HEAD missing the remote's commits either
// way, and the ignore-plane flip then refuses every later `bd dolt pull`.
// Since bd auto-commits every write, "has local commits AND is behind" is the
// ordinary multi-machine state, so restricting the stop to ahead == 0 would
// leave the larger half of the affected cohort unprotected. A level clone
// (behind == 0) and a purely-ahead clone (behind == 0, ahead >= 1) are still
// permitted — they are genuine first-movers with nothing to pull.
//
// adopt may be nil, or wire neither callback (the shared unit-of-work
// provider's injection site) — then there is no ancestry fact to read and
// routing stays exactly as it was before this check existed. With only
// IsStrictAncestor wired, the fact narrows to the ahead == 0 shape; the
// diverged shape then reads "not behind", which is the pre-widening
// behavior rather than a new hazard.
//
// Unlike routeAdoptFastForward, a query error is NOT folded into "false":
// here false means "permit the more automatic action", so an inconclusive
// read has to be reported to the caller and degrade to the blunt block.
func localDataBehind(ctx context.Context, db DBConn, ref string, adopt *FastForwardAdopter) (behind bool, diverged bool, err error) {
if adopt == nil {
return false, false, nil
}
if adopt.AheadBehind != nil {
ahead, behindCount, err := adopt.AheadBehind(ctx, db, ref)
if err != nil {
return false, false, err
}
return behindCount >= 1, behindCount >= 1 && ahead >= 1, nil
}
if adopt.IsStrictAncestor == nil {
return false, false, nil
}
ancestor, err := adopt.IsStrictAncestor(ctx, db, ref)
if err != nil {
return false, false, err
}
// A strict ancestor is by definition ahead == 0, so this fallback can
// only ever report the non-diverged shape.
return ancestor, false, nil
}
// canAutoFastForward reports whether adopt is actually able to EXECUTE the
// fast-forward once the read-side preconditions (routeAdoptFastForward) are
// satisfied: a FastForward callback must be wired, and the store must not be
@ -319,6 +404,29 @@ func routeSmartGate(ctx context.Context, db DBConn, current, latest int, remoteN
// remote == local on every shared version and at the same max version: a first-mover.
if current >= LastNonDeterministicMigration {
// Schema parity is not proof of first-mover status
// (gastownhall/beads#6575). It says nothing about where this clone's
// branch sits relative to the ref the hashes just came from: a clone
// that is level on schema and behind on DATA satisfies every
// precondition above. Read the ancestry fact the caller already wired
// for the remote-ahead path before granting the automatic migrate.
behind, diverged, err := localDataBehind(ctx, db, ref, adopt)
if err != nil {
// Inconclusive ancestry read on a ref whose content hashes just
// resolved. Degrade to the blunt block rather than assume level:
// the gate's contract is that every fallback is at least as safe
// as #4515.
return smartUndetermined, nil, "", false
}
if behind {
// Same stop, same remedy command; the two verdicts differ only in
// what that command DOES (fast-forward vs merge), which the
// operator-facing text has to get right.
if diverged {
return smartDataDiverged, nil, ref, false
}
return smartDataBehind, nil, ref, false
}
return smartAutoMigrate, nil, ref, false
}
return smartBelowFloor, nil, ref, false

View file

@ -416,6 +416,17 @@ type fakeAdopter struct {
ffCalls int
readOnly bool
// aheadResult/behindResult/aheadBehindErr back the AheadBehind callback,
// counted by aheadBehindCalls. Wired into the adopter only when
// withAheadBehind is true, so the tests that leave it off keep exercising
// the IsStrictAncestor-only fallback an injection site that never wired
// the newer callback would take (gastownhall/beads#6575).
withAheadBehind bool
aheadResult int
behindResult int
aheadBehindErr error
aheadBehindCalls int
}
func (f *fakeAdopter) adopter() *FastForwardAdopter {
@ -436,6 +447,12 @@ func (f *fakeAdopter) adopter() *FastForwardAdopter {
return f.ffErr
}
}
if f.withAheadBehind {
a.AheadBehind = func(_ context.Context, _ DBConn, _ string) (int, int, error) {
f.aheadBehindCalls++
return f.aheadResult, f.behindResult, f.aheadBehindErr
}
}
return a
}
@ -800,6 +817,491 @@ func TestSmartGateRoutingFastForward(t *testing.T) {
})
}
// TestSmartGateRoutingDataBehind covers the equal-version path's ancestry
// check (gastownhall/beads#6575): schema parity with the cached remote ref is
// not proof of first-mover status, because a clone can be level on schema and
// behind on data commits. These subtests pin the ROUTING around canned
// ancestry results; the genuinely data-behind clone — two real clones, a
// file:// remote, a real DOLT_FETCH, the ancestry fact measured rather than
// stubbed — lives in internal/storage/dolt
// (TestDoltNew_SmartRemoteMigrateGate_DataBehindBlocks_RealDolt).
func TestSmartGateRoutingDataBehind(t *testing.T) {
floor := LastNonDeterministicMigration
t.Run("data-behind clone: blunt block naming the pull-first remedy", func(t *testing.T) {
t.Setenv(SmartGateEnv, "1")
t.Setenv(AllowRemoteMigrateEnv, "0")
db, mock, _ := sqlmock.New()
defer db.Close()
expectSmartFiringGate(mock, floor)
hashes := map[int]string{floor - 1: "h1", floor: "h2"}
expectSmartRemoteRead(mock, hashes, hashes)
fa := &fakeAdopter{ancestorResult: true, cleanResult: true}
err := CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt(context.Background(), db, "", nil, fa.adopter())
var gateErr *RemoteMigrateGateError
if !errors.As(err, &gateErr) {
t.Fatalf("a data-behind clone must not auto-migrate, got %v", err)
}
if gateErr.Decision != "" {
t.Errorf("Decision = %q, want \"\" (the blunt #4515 stop — no new JSON/agent contract)", gateErr.Decision)
}
if gateErr.FallbackReason != fallbackReasonDataBehind {
t.Errorf("FallbackReason = %q, want %q", gateErr.FallbackReason, fallbackReasonDataBehind)
}
if !strings.Contains(gateErr.UserMessage(), "Run `bd dolt pull` first") {
t.Errorf("UserMessage should name the pull-first remedy:\n%s", gateErr.UserMessage())
}
if fa.ancestorCalls != 1 {
t.Errorf("IsStrictAncestor calls = %d, want 1", fa.ancestorCalls)
}
// Deliberately NOT part of the equal-version precondition: a dirty
// working set on a level clone is not the #6575 wedge state, and
// refusing it would broaden the gate beyond the field-hit bug.
if fa.cleanCalls != 0 {
t.Errorf("WorkingSetClean calls = %d, want 0 (the equal-version path must not require a clean working set)", fa.cleanCalls)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet expectations: %v", err)
}
})
t.Run("level clone: still the safe first-mover auto-migrate", func(t *testing.T) {
t.Setenv(SmartGateEnv, "1")
t.Setenv(AllowRemoteMigrateEnv, "0")
db, mock, _ := sqlmock.New()
defer db.Close()
expectSmartFiringGate(mock, floor)
hashes := map[int]string{floor: "h1"}
expectSmartRemoteRead(mock, hashes, hashes)
// ancestorResult false covers BOTH non-behind shapes the predicate
// collapses: HEAD == ref (level) and ahead > 0 (unpushed local
// commits). Neither is refused.
fa := &fakeAdopter{ancestorResult: false, cleanResult: true}
if err := CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt(context.Background(), db, "", nil, fa.adopter()); err != nil {
t.Fatalf("a clone that is not behind must still auto-migrate, got %v", err)
}
if fa.ancestorCalls != 1 {
t.Errorf("IsStrictAncestor calls = %d, want 1", fa.ancestorCalls)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet expectations: %v", err)
}
})
t.Run("ancestry read error: blunt block, never the automatic migrate", func(t *testing.T) {
t.Setenv(SmartGateEnv, "1")
t.Setenv(AllowRemoteMigrateEnv, "0")
db, mock, _ := sqlmock.New()
defer db.Close()
expectSmartFiringGate(mock, floor)
hashes := map[int]string{floor: "h1"}
expectSmartRemoteRead(mock, hashes, hashes)
fa := &fakeAdopter{ancestorErr: errors.New("dolt_log AS OF: branch not found")}
err := CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt(context.Background(), db, "", nil, fa.adopter())
var gateErr *RemoteMigrateGateError
if !errors.As(err, &gateErr) {
t.Fatalf("an inconclusive ancestry read must fall back to the blunt block, got %v", err)
}
if gateErr.FallbackReason != fallbackReasonUnreadableState {
t.Errorf("FallbackReason = %q, want %q", gateErr.FallbackReason, fallbackReasonUnreadableState)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet expectations: %v", err)
}
})
t.Run("no adopter wired: routing is unchanged", func(t *testing.T) {
t.Setenv(SmartGateEnv, "1")
t.Setenv(AllowRemoteMigrateEnv, "0")
db, mock, _ := sqlmock.New()
defer db.Close()
expectSmartFiringGate(mock, floor)
hashes := map[int]string{floor: "h1"}
expectSmartRemoteRead(mock, hashes, hashes)
// The unit-of-work provider's injection site passes nil (and is
// shared, where the first-mover arm is suppressed anyway). With no
// ancestry fact to read, the verdict stays exactly what it was.
if err := CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt(context.Background(), db, "", nil, nil); err != nil {
t.Fatalf("a nil adopter must not change the first-mover verdict, got %v", err)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet expectations: %v", err)
}
})
t.Run("below the convergence floor: outcome and reads unchanged", func(t *testing.T) {
t.Setenv(SmartGateEnv, "1")
t.Setenv(AllowRemoteMigrateEnv, "0")
db, mock, _ := sqlmock.New()
defer db.Close()
current := floor - 1
expectSmartFiringGate(mock, current)
hashes := map[int]string{current: "h1"}
expectSmartRemoteRead(mock, hashes, hashes)
fa := &fakeAdopter{ancestorResult: true, cleanResult: true}
err := CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt(context.Background(), db, "", nil, fa.adopter())
var gateErr *RemoteMigrateGateError
if !errors.As(err, &gateErr) {
t.Fatalf("expected gate error, got %v", err)
}
if gateErr.FallbackReason != fallbackReasonBelowFloor {
t.Errorf("FallbackReason = %q, want %q (below-floor outcomes must stay byte-identical)", gateErr.FallbackReason, fallbackReasonBelowFloor)
}
if fa.ancestorCalls != 0 {
t.Errorf("IsStrictAncestor calls = %d, want 0 (the ancestry read must not fire below the floor)", fa.ancestorCalls)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet expectations: %v", err)
}
})
t.Run("shared store: data-behind outranks the shared-store suppression reason", func(t *testing.T) {
t.Setenv(SmartGateEnv, "1")
t.Setenv(AllowRemoteMigrateEnv, "0")
SetForceAllowRemoteMigrate(false)
SetSharedMigrateConsent(false)
db, mock, _ := sqlmock.New()
defer db.Close()
expectSmartFiringGate(mock, floor)
hashes := map[int]string{floor: "h1"}
expectSmartRemoteRead(mock, hashes, hashes)
// Both facts hold, and either one blocks. The shared-store reason
// says "the gate WOULD have resolved and was overruled", which is not
// true here — and the pull-first remedy is a precondition this
// operator has to satisfy either way.
fa := &fakeAdopter{ancestorResult: true, cleanResult: true}
err := CheckSharedStoreMigrateGate(context.Background(), db, "", nil, fa.adopter())
var gateErr *RemoteMigrateGateError
if !errors.As(err, &gateErr) {
t.Fatalf("expected gate error, got %v", err)
}
if gateErr.FallbackReason != fallbackReasonDataBehind {
t.Errorf("FallbackReason = %q, want %q", gateErr.FallbackReason, fallbackReasonDataBehind)
}
if !gateErr.Shared {
t.Error("Shared should still be set on a shared-store refusal")
}
// But the note must NOT promise the retry resolves itself here: on a
// shared store the first-mover auto-migrate stays suppressed (#5920),
// so pulling clears this stop and the retry still needs consent.
msg := gateErr.UserMessage()
if !strings.Contains(msg, "Run `bd dolt pull` first") {
t.Errorf("shared store should still get the pull-first remedy:\n%s", msg)
}
if strings.Contains(msg, "proceeds on its own") {
t.Errorf("shared store must not be promised an automatic retry (the first-mover arm is suppressed here):\n%s", msg)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet expectations: %v", err)
}
})
t.Run("non-shared store IS promised the automatic retry", func(t *testing.T) {
t.Setenv(SmartGateEnv, "1")
t.Setenv(AllowRemoteMigrateEnv, "0")
db, mock, _ := sqlmock.New()
defer db.Close()
expectSmartFiringGate(mock, floor)
hashes := map[int]string{floor: "h1"}
expectSmartRemoteRead(mock, hashes, hashes)
fa := &fakeAdopter{ancestorResult: true, cleanResult: true}
err := CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt(context.Background(), db, "", nil, fa.adopter())
var gateErr *RemoteMigrateGateError
if !errors.As(err, &gateErr) {
t.Fatalf("expected gate error, got %v", err)
}
if msg := gateErr.UserMessage(); !strings.Contains(msg, "proceeds on its own") {
t.Errorf("an ordinary clone's retry DOES auto-resolve and should say so:\n%s", msg)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet expectations: %v", err)
}
})
// An unparseable BD_SMART_GATE value normally outranks the routing reason,
// but it must not bury data-behind: that stop stands whatever the env says,
// and it is the only reason carrying a remedy the operator can act on now.
t.Run("unparseable BD_SMART_GATE does not bury the pull-first remedy", func(t *testing.T) {
t.Setenv(SmartGateEnv, "yes")
t.Setenv(AllowRemoteMigrateEnv, "0")
db, mock, _ := sqlmock.New()
defer db.Close()
expectSmartFiringGate(mock, floor)
hashes := map[int]string{floor: "h1"}
expectSmartRemoteRead(mock, hashes, hashes)
fa := &fakeAdopter{ancestorResult: true, cleanResult: true}
err := CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt(context.Background(), db, "", nil, fa.adopter())
var gateErr *RemoteMigrateGateError
if !errors.As(err, &gateErr) {
t.Fatalf("expected gate error, got %v", err)
}
if gateErr.FallbackReason != fallbackReasonDataBehind {
t.Errorf("FallbackReason = %q, want %q (the env complaint must not outrank it)", gateErr.FallbackReason, fallbackReasonDataBehind)
}
if msg := gateErr.UserMessage(); !strings.Contains(msg, "Run `bd dolt pull` first") {
t.Errorf("UserMessage lost the pull-first remedy:\n%s", msg)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet expectations: %v", err)
}
})
}
// TestSmartGateRoutingDataBehindShapes covers the widened data-behind
// predicate (gastownhall/beads#6575 review finding F2): the stop is keyed on
// behind >= 1 whatever ahead is, not on the strict-ancestor relation.
//
// The narrower form protected only a clone with zero local commits, and bd
// auto-commits every write — so "has local commits AND is behind" is the
// ORDINARY multi-machine state, and it reaches the identical wedge (the
// pending migration lands on a history missing the remote's commits either
// way). What differs is the remedy's behavior, not the remedy: the pull
// fast-forwards in one shape and merges in the other, so the two verdicts stay
// distinguishable all the way out to the message and the JSON.
func TestSmartGateRoutingDataBehindShapes(t *testing.T) {
floor := LastNonDeterministicMigration
route := func(t *testing.T, fa *fakeAdopter, shared bool) error {
t.Helper()
t.Setenv(SmartGateEnv, "1")
t.Setenv(AllowRemoteMigrateEnv, "0")
SetForceAllowRemoteMigrate(false)
SetSharedMigrateConsent(false)
db, mock, _ := sqlmock.New()
defer db.Close()
expectSmartFiringGate(mock, floor)
hashes := map[int]string{floor: "h1"}
expectSmartRemoteRead(mock, hashes, hashes)
var err error
if shared {
err = CheckSharedStoreMigrateGate(context.Background(), db, "", nil, fa.adopter())
} else {
err = CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt(context.Background(), db, "", nil, fa.adopter())
}
if mockErr := mock.ExpectationsWereMet(); mockErr != nil {
t.Fatalf("unmet expectations: %v", mockErr)
}
return err
}
t.Run("behind with no local commits: the fast-forward shape", func(t *testing.T) {
fa := &fakeAdopter{withAheadBehind: true, aheadResult: 0, behindResult: 1}
err := route(t, fa, false)
var gateErr *RemoteMigrateGateError
if !errors.As(err, &gateErr) {
t.Fatalf("a data-behind clone must not auto-migrate, got %v", err)
}
if gateErr.FallbackReason != fallbackReasonDataBehind {
t.Fatalf("FallbackReason = %q, want %q", gateErr.FallbackReason, fallbackReasonDataBehind)
}
if gateErr.DataDiverged {
t.Error("DataDiverged = true, want false (ahead == 0 is a pure fast-forward)")
}
if msg := gateErr.UserMessage(); !strings.Contains(msg, "pure fast-forward") {
t.Errorf("message should say the pull fast-forwards:\n%s", msg)
}
// The raw counts are what the widened predicate reads; the older
// boolean callback must not be consulted when they are available.
if fa.aheadBehindCalls != 1 {
t.Errorf("AheadBehind calls = %d, want 1", fa.aheadBehindCalls)
}
if fa.ancestorCalls != 0 {
t.Errorf("IsStrictAncestor calls = %d, want 0 once AheadBehind is wired", fa.ancestorCalls)
}
})
t.Run("behind WITH local commits: the diverged shape still stops", func(t *testing.T) {
// The F2 case: before the widening this routed to smartAutoMigrate and
// the migration ran, measured on a real clone at ahead=1, behind=1.
fa := &fakeAdopter{withAheadBehind: true, aheadResult: 1, behindResult: 1}
err := route(t, fa, false)
var gateErr *RemoteMigrateGateError
if !errors.As(err, &gateErr) {
t.Fatalf("a diverged, behind clone reaches the same wedge and must not auto-migrate, got %v", err)
}
if gateErr.FallbackReason != fallbackReasonDataBehind {
t.Fatalf("FallbackReason = %q, want %q", gateErr.FallbackReason, fallbackReasonDataBehind)
}
if !gateErr.DataDiverged {
t.Error("DataDiverged = false, want true (ahead >= 1 means the pull merges)")
}
msg := gateErr.UserMessage()
if !strings.Contains(msg, "MERGES") {
t.Errorf("a diverged clone must be told its pull merges rather than fast-forwards:\n%s", msg)
}
if strings.Contains(msg, "pure fast-forward") {
t.Errorf("a diverged clone must NOT be promised a fast-forward:\n%s", msg)
}
})
t.Run("purely ahead: still the safe first-mover auto-migrate", func(t *testing.T) {
// Nothing to pull, so nothing to wedge. Refusing here would be the
// over-refusal a patch line must not ship.
fa := &fakeAdopter{withAheadBehind: true, aheadResult: 3, behindResult: 0}
if err := route(t, fa, false); err != nil {
t.Fatalf("a clone with only unpushed local commits must still auto-migrate, got %v", err)
}
})
t.Run("level: still the safe first-mover auto-migrate", func(t *testing.T) {
fa := &fakeAdopter{withAheadBehind: true, aheadResult: 0, behindResult: 0}
if err := route(t, fa, false); err != nil {
t.Fatalf("a level clone must still auto-migrate, got %v", err)
}
})
t.Run("ahead/behind read error: blunt block, never the automatic migrate", func(t *testing.T) {
fa := &fakeAdopter{withAheadBehind: true, aheadBehindErr: errors.New("dolt_log AS OF: branch not found")}
err := route(t, fa, false)
var gateErr *RemoteMigrateGateError
if !errors.As(err, &gateErr) {
t.Fatalf("an inconclusive read must fall back to the blunt block, got %v", err)
}
if gateErr.FallbackReason != fallbackReasonUnreadableState {
t.Errorf("FallbackReason = %q, want %q", gateErr.FallbackReason, fallbackReasonUnreadableState)
}
})
t.Run("no AheadBehind wired: falls back to the strict-ancestor fact", func(t *testing.T) {
// An injection site that wired only the older callback keeps the
// pre-widening (narrower) behavior rather than losing the stop
// altogether: a strict ancestor is by definition ahead == 0, so the
// shape it reports is never "diverged".
fa := &fakeAdopter{ancestorResult: true, cleanResult: true}
err := route(t, fa, false)
var gateErr *RemoteMigrateGateError
if !errors.As(err, &gateErr) {
t.Fatalf("expected the data-behind stop via the fallback, got %v", err)
}
if gateErr.FallbackReason != fallbackReasonDataBehind {
t.Errorf("FallbackReason = %q, want %q", gateErr.FallbackReason, fallbackReasonDataBehind)
}
if gateErr.DataDiverged {
t.Error("DataDiverged = true; the IsStrictAncestor fallback can only report ahead == 0")
}
if fa.aheadBehindCalls != 0 {
t.Errorf("AheadBehind calls = %d, want 0 (not wired)", fa.aheadBehindCalls)
}
if fa.ancestorCalls != 1 {
t.Errorf("IsStrictAncestor calls = %d, want 1", fa.ancestorCalls)
}
})
}
// TestDataBehindRemedySurfaces pins the review's F1/F3/F4 findings on the
// message and agent contract: every surface has to name the ONE remedy that
// was measured to work, the shared-store consequence has to survive the
// precedence choice that made data-behind outrank shared-store, and the blunt
// migrate-or-adopt options must not be offered — in this state
// `bd migrate --force` is the bug (and its follow-up `bd dolt push` is
// rejected non-fast-forward while the clone is still behind) while
// `bd bootstrap` no-ops against an existing workspace.
func TestDataBehindRemedySurfaces(t *testing.T) {
base := func(shared, diverged bool) *RemoteMigrateGateError {
return &RemoteMigrateGateError{
CurrentVersion: 66, LatestVersion: 67, Pending: 1,
FallbackReason: fallbackReasonDataBehind,
Shared: shared,
DataDiverged: diverged,
}
}
t.Run("only the pull is offered", func(t *testing.T) {
for _, diverged := range []bool{false, true} {
e := base(false, diverged)
opts := e.Options()
if len(opts) != 1 || opts[0].ID != "pull-first" {
t.Fatalf("diverged=%v: Options() = %+v, want exactly one pull-first option", diverged, opts)
}
if len(opts[0].Commands) != 1 || opts[0].Commands[0] != DataBehindRemedyCommand {
t.Errorf("diverged=%v: option commands = %v, want [%q]", diverged, opts[0].Commands, DataBehindRemedyCommand)
}
for _, o := range opts {
for _, c := range o.Commands {
if c == "bd migrate --force" || c == "bd bootstrap" {
t.Errorf("diverged=%v: option %q offers %q, which was measured not to work in this state", diverged, o.ID, c)
}
}
}
if d := e.AgentDirective(); !strings.Contains(d, DataBehindRemedyCommand) {
t.Errorf("diverged=%v: AgentDirective must name the remedy:\n%s", diverged, d)
}
if body := e.userBody(); strings.Contains(body, "bd bootstrap") {
t.Errorf("diverged=%v: the body must not send the operator to a no-op bootstrap:\n%s", diverged, body)
}
}
})
t.Run("shared store keeps the #5920 lockout warning", func(t *testing.T) {
// F3: before this, Shared+data-behind rendered with neither
// "co-resident" nor "#5920" anywhere, because data-behind outranks
// fallbackReasonSharedStore (whose note carried them) and Options()'
// sharedRisk only ever decorated the adopt option.
msg := base(true, false).UserMessage()
for _, want := range []string{"co-resident", "#5920", SharedConsentCommand} {
if !strings.Contains(msg, want) {
t.Errorf("shared data-behind message is missing %q:\n%s", want, msg)
}
}
if strings.Contains(msg, "proceeds on its own") {
t.Errorf("a shared store must not be promised an automatic retry:\n%s", msg)
}
opts := base(true, false).Options()
if len(opts) != 2 || opts[0].ID != "pull-first" || opts[1].ID != "migrate-shared-after-pulling" {
t.Fatalf("shared Options() = %+v, want pull-first then the consent step", opts)
}
if d := base(true, false).AgentDirective(); !strings.Contains(d, "#5920") {
t.Errorf("shared AgentDirective must carry the co-resident consequence:\n%s", d)
}
})
t.Run("non-shared store IS promised the automatic retry", func(t *testing.T) {
msg := base(false, false).UserMessage()
if !strings.Contains(msg, "proceeds on its own") {
t.Errorf("an ordinary clone's retry DOES auto-resolve and should say so:\n%s", msg)
}
if strings.Contains(msg, SharedConsentCommand) {
t.Errorf("a non-shared clone must not be sent to the shared consent verb:\n%s", msg)
}
})
t.Run("IsDataBehind is exactly this stop", func(t *testing.T) {
// The store opens key their one narrow exemption on this predicate, so
// it must not widen to any other refusal.
if !base(false, false).IsDataBehind() {
t.Error("IsDataBehind() = false for the data-behind stop")
}
for _, reason := range []string{
fallbackReasonUnreadableState, fallbackReasonBelowFloor,
fallbackReasonOptedOut, fallbackReasonUnparseableEnv, fallbackReasonSharedStore, "",
} {
e := base(false, false)
e.FallbackReason = reason
if e.IsDataBehind() {
t.Errorf("IsDataBehind() = true for FallbackReason %q", reason)
}
}
// A tailored decision is never this stop either, whatever the reason
// field happens to hold.
e := base(false, false)
e.Decision = gateDecisionForkSkew
if e.IsDataBehind() {
t.Error("IsDataBehind() = true for a fork-skew decision")
}
if (*RemoteMigrateGateError)(nil).IsDataBehind() {
t.Error("IsDataBehind() = true on a nil receiver")
}
})
}
// TestSmartGateEnabled pins the default-on contract: unset and unparseable
// values keep the smart gate active; only an explicit boolean false opts out.
func TestSmartGateEnabled(t *testing.T) {

View file

@ -15,17 +15,23 @@ import (
// elsewhere calls these yet — they are wired into the smart migrate gate in
// a later change.
// LocalIsStrictAncestorOf reports whether local HEAD is a STRICT ancestor of
// ref in the Dolt commit graph: local has zero commits that ref lacks
// (ahead == 0) and at least one commit that local lacks (behind >= 1). A
// local HEAD equal to ref (ahead == 0, behind == 0) is NOT a strict
// ancestor, and returns false.
// LocalAheadBehind reports how far local HEAD has diverged from ref in the
// Dolt commit graph: ahead is the number of commits local has that ref lacks,
// behind the number ref has that local lacks. (0, 0) means the two are level.
//
// It is the raw fact behind LocalIsStrictAncestorOf, exposed separately
// because the two callers need different slices of it: a fast-forward adopt
// needs "ahead == 0 && behind >= 1", while the data-behind migrate stop
// (gastownhall/beads#6575) needs "behind >= 1" whatever ahead is — a clone
// with local commits of its own AND unpulled remote commits reaches the same
// wedge, and telling the operator which shape they are in changes whether
// their `bd dolt pull` fast-forwards or merges.
//
// ref must already be present locally (e.g. a cached remote-tracking ref
// such as "origin/main" after a fetch); this performs no fetch of its own.
func LocalIsStrictAncestorOf(ctx context.Context, db DBConn, ref string) (bool, error) {
func LocalAheadBehind(ctx context.Context, db DBConn, ref string) (ahead, behind int, err error) {
if err := issueops.ValidateRef(ref); err != nil {
return false, fmt.Errorf("invalid ref: %w", err)
return 0, 0, fmt.Errorf("invalid ref: %w", err)
}
// Dolt's AS OF requires a literal ref, not a bind parameter; ref was
@ -41,11 +47,25 @@ func LocalIsStrictAncestorOf(ctx context.Context, db DBConn, ref string) (bool,
(SELECT commit_hash FROM dolt_log)) AS behind
`, ref, ref)
var ahead, behind int
if err := db.QueryRowContext(ctx, query).Scan(&ahead, &behind); err != nil {
return false, fmt.Errorf("compare local HEAD to %s: %w", ref, err)
return 0, 0, fmt.Errorf("compare local HEAD to %s: %w", ref, err)
}
return ahead, behind, nil
}
// LocalIsStrictAncestorOf reports whether local HEAD is a STRICT ancestor of
// ref in the Dolt commit graph: local has zero commits that ref lacks
// (ahead == 0) and at least one commit that local lacks (behind >= 1). A
// local HEAD equal to ref (ahead == 0, behind == 0) is NOT a strict
// ancestor, and returns false.
//
// ref must already be present locally (e.g. a cached remote-tracking ref
// such as "origin/main" after a fetch); this performs no fetch of its own.
func LocalIsStrictAncestorOf(ctx context.Context, db DBConn, ref string) (bool, error) {
ahead, behind, err := LocalAheadBehind(ctx, db, ref)
if err != nil {
return false, err
}
return ahead == 0 && behind >= 1, nil
}