beads/cmd/bd/remote_migrate_gate.go
Julian Knutsen 16871ee152
fix(schema,docs): make the shared data-behind consent step runnable (#6692)
Post-merge review of #6658 (landed as 5b9e938b5) found two guidance defects
in the #6575 data-behind stop. The gate itself is correct; both are in the
remedy chain it prints.

1. The shared arm prescribed `bd migrate schema`, which cannot succeed in the
   state that prints it. A data-behind refusal has a remote by construction —
   behind-ness is read from `remotes/<name>/<branch>` — and the verb consent
   (`sharedMigrateConsent`) has exactly one reader, inside `sharedNoRemoteGate`,
   reachable only on the `!hasRemote` branch. So after the pull the retry routed
   `smartAutoMigrate -> shared -> fallbackReasonSharedStore`, whose blunt body
   prescribes the `bd migrate --force` the data-behind body explicitly says not
   to use. The option, `dataBehindBody`, `AgentDirective`, `fallbackReasonNote`
   and both `--global` retargets now name `bd migrate schema --force`, which
   trips `forceOrEnvConsent` via `isForcedMigrate`.

   Retargeting the command rather than widening the consent read is deliberate:
   with a remote configured, #4259's cross-clone fork risk still demands the
   designated-migrator confirmation, which is what `sharedNoRemoteGate`'s own
   comment says the scoping is for.

2. The JSON payload's `docs` pointer stayed on the migrate-or-adopt anchor,
   whose ordering rule says `bd dolt pull` is refused on every
   pending-migration open — contradicting the `pull-first` option in the same
   payload. The `IsDataBehind()` arm now points at a new "Clone behind the
   remote" section, and the two living ordering rules (upgrading.md,
   init-safety.md) record the exception.

Tests: the consent step is now checked by running it — the command is taken
from `Options()`, resolved through the same cobra lookup and predicates the
root pre-run uses, and fed to the real gate against a remote-backed shared
fixture, with the shipped bare verb as the counterfactual. Asserting the
option's wording is what let the dead command ship. `docs` is pinned in
`TestHandleRemoteMigrateGateJSON_DataBehind`.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-23 05:46:48 -07:00

226 lines
12 KiB
Go

package main
import (
"encoding/json"
"fmt"
"os"
"github.com/steveyegge/beads/internal/storage/schema"
)
const (
// remoteBackedDocsURL covers the #4259 migrate-or-adopt decisions: the
// database syncs with a remote and the question is which clone migrates.
remoteBackedDocsURL = "https://github.com/gastownhall/beads/blob/main/docs/getting-started/upgrading.md#remote-backed-databases-and-multiple-clones"
// sharedServersDocsURL covers the #5920 shared-store decisions: one
// database, many clients of one server, and the question is whether they
// are all upgraded.
sharedServersDocsURL = "https://github.com/gastownhall/beads/blob/main/docs/getting-started/upgrading.md#shared-servers"
// dataBehindDocsURL covers the #6575 data-behind stop. It needs its own
// anchor for the same reason sharedServersDocsURL does: the remote-backed
// section's recipe is migrate-or-adopt coordination, and its ordering rule
// says `bd dolt pull` is refused on every pending-migration open — which is
// exactly the command this stop's options prescribe. An agent following the
// default link would be steered off the one command that works.
dataBehindDocsURL = "https://github.com/gastownhall/beads/blob/main/docs/getting-started/upgrading.md#clone-behind-the-remote"
)
// 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.
//
// The top-level "hint" is deliberately a non-runnable directive, NOT the
// `BD_ALLOW_REMOTE_MIGRATE=1 bd migrate` escape command: handing an agent a
// ready-to-run migrate as "the fix" is the footgun that forks shared remotes on
// multi-clone setups. The migrate command lives only inside
// remote_migrate_gate.options[migrate], gated on its "single designated
// migrator" precondition and annotated with its risk, so the agent surfaces a
// human decision instead of auto-running it.
func handleRemoteMigrateGateJSON(e *schema.RemoteMigrateGateError) {
outer := buildJSONError(e.Error(), e.AgentDirective())
if m, ok := outer.(map[string]interface{}); ok {
// The shared-no-remote consent verb is the one command in this block
// that 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. Mirror the
// human/text path (printGlobalDatabaseConsentHint,
// noticeSharedMigrateRefusal) and name the --global verb when this
// invocation targeted the global database. Only shared-no-remote is
// retargeted; the remote-backed arms coordinate through bd bootstrap /
// bd migrate --force, which --global does not rewrite.
sharedConsent := schema.SharedConsentCommand
if globalFlag {
sharedConsent = schema.SharedConsentCommandGlobal
}
// The #6575 data-behind stop on a SHARED store carries a consent verb in
// its second option (migrate-shared-after-pulling) too — the forced one,
// since that stop is always remote-backed — 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() {
commands := o.Commands
if retargetShared {
// The runnable command deliberately lives inside the option, not
// in the top-level hint, so an agent that extracts it
// programmatically must get the --global verb too — fixing only
// "expected" would still hand it the wrong-target command.
retargeted := make([]string, len(commands))
for i, c := range commands {
switch c {
case schema.SharedConsentCommand:
retargeted[i] = schema.SharedConsentCommandGlobal
case schema.SharedConsentCommandForced:
// The data-behind arm's consent step is the FORCED verb (that
// stop is remote-backed by construction, where the bare verb's
// consent is never read), so it needs its own global form —
// matching only the bare verb would leave this option pointing
// at the project database.
retargeted[i] = schema.SharedConsentCommandForcedGlobal
default:
retargeted[i] = c
}
}
commands = retargeted
}
opts = append(opts, map[string]interface{}{
"id": o.ID,
"when": o.When,
"commands": commands,
"risk": o.Risk,
})
}
gate := map[string]interface{}{
"current_version": e.CurrentVersion,
"latest_version": e.LatestVersion,
"pending": e.Pending,
"severity": "blocking",
"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,
"docs": remoteBackedDocsURL,
}
// Smart gate (#4516): when a state-aware decision narrowed the stop,
// tell the agent which case it is and (for a fork) which versions skewed.
switch e.Decision {
case "adopt":
gate["decision"] = "adopt"
gate["observed"] = "the remote is already migrated; migrating here would fork it"
gate["expected"] = "adopt the remote's migrated database (destructive re-clone — operator decision)"
case "shared-no-remote":
// #5920: no remote at all, so the migrate-or-adopt framing above
// does not apply — there is one shared copy and the only question
// is whether every client of it is upgraded. The base docs link
// goes with that framing, so it has to move too: an agent
// following it would brief the operator on designated-migrator
// and bd bootstrap coordination that does not exist here.
gate["decision"] = "shared-no-remote"
gate["observed"] = fmt.Sprintf("%d pending schema migration(s) on a shared server database, no consent", e.Pending)
gate["expected"] = "operator upgrades co-resident clients, then consents once via " + sharedConsent
gate["docs"] = sharedServersDocsURL
case "adopt-ff":
// A strict refinement of adopt, and on a shared store now a
// routine outcome rather than something auto-executed — so it
// needs its own tailoring instead of inheriting the default
// "exactly one designated clone migrates and publishes", which
// contradicts the adopt-only options this decision carries.
gate["decision"] = "adopt-ff"
gate["observed"] = "the remote is already migrated and this clone can fast-forward to it losslessly (no unpushed commits, clean working set)"
gate["expected"] = "adopt the remote's migrated database; nothing local is discarded"
case "fork-skew":
gate["decision"] = "fork-skew"
gate["observed"] = fmt.Sprintf("this clone and the remote applied different content for migration(s) %s — already forked", schema.FormatMigrationVersions(e.SkewVersions))
gate["expected"] = "pick one canonical clone and re-bootstrap the others (data-loss decision)"
gate["skew_versions"] = e.SkewVersions
default:
// Blunt #4515 stop — name WHY the smart gate (#4516) could not do
// better (gastownhall/beads#4551 follow-up), so an agent/operator can
// tell "unreadable remote state" apart from "below the convergence
// floor" apart from "opted out" apart from "unparseable BD_SMART_GATE".
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"
// The docs pointer is set once above alongside the blunt
// observed/expected pair, and has to move with them: the section it
// names tells the reader `bd dolt pull` is refused on every
// pending-migration open, which contradicts the single option this
// payload carries. Same move, for the same reason, as
// shared-no-remote's retarget above.
gate["docs"] = dataBehindDocsURL
}
}
m["remote_migrate_gate"] = gate
}
encoder := json.NewEncoder(os.Stderr)
encoder.SetIndent("", " ")
_ = encoder.Encode(outer)
}