The migrations reset doctrine: a reset is a reset
Status: RULED, 2026-08-19, by the owner. Final.
Supersedes: 2026-08-18-migration-squash.md
and every bridge mechanism that document proposed or that ce shipped
(the manifest, the record-without-executing baseline branch, the ledger
compaction, the flatten guard and its make migrate/flatten target).
Scope: ce/migrations/, the runner in ce/core/db/migrate.go, and
every deployment that ever meets a reset catalogue.
The doctrine
Section titled “The doctrine”ce/migrations/ holds Atlas output (*_auto.sql files, atlas.sum,
and the embed.go that ships them), and nothing else. Appending a
migration is make migrate NAME=<slug>. Resetting the history is
rm -rf migrations/*.sql && make migrate, which produces one fresh
generated baseline, and bricks existing deployments by design: the
entire point of a reset is to reset, so nothing may be tracked, mapped,
manifested or recorded to make one “safe” for a database that predates
it. The remedy for an existing deployment is rebuild plus external
import (the estate-rebuild plan), never an in-place bridge. The
runner’s whole contract is correspondingly simple: verify atlas.sum,
execute unapplied catalogue files in order, record executed names, and
refuse loudly when a ledger and a catalogue disagree, X500901OPFAIL
when an orphaned ledger row falls inside the drift window,
X500967MIGAPL (atomic, nothing half-applied, nothing recorded) when a
reset baseline collides with schema the estate already carries. The
owner’s reasoning, plainly: tracking the machinery of a reset defeats
the reset; “of course it’s not safe for an existing deployment; that
is the point.”
What this retired
Section titled “What this retired”Removed from ce on 2026-08-19 (ce!139): the manifest file, the
record-without-executing baseline branch, the ledger compaction, the
flatten-guard script and its regen mode, the migrate/flatten target,
the nine bridge-only error codes (the MIGSQH, MIGSQJ through MIGSQN,
and MIGCPT mnemonics; retired codes are tracked by the ghost register
in scripts/arch-fitness.sh where dated pages still cite them), and
the guard suites whose only subject was the bridge (deletion
owner-ordered). What survives, re-aimed: the ent-vs-catalogue-head
invariant (ce/tests/migrations/schema_head_test.go), the
catalogue-shape guards, and the refusal tests
(ce/core/db/reset_refusal_test.go) that pin the loud brick.
Sequencing consequence
Section titled “Sequencing consequence”A cluster installed from a release that predates the removal carries a ledger row naming a retired catalogue filename; upgrading it across the removal refuses at boot. That is acceptable per this doctrine; such an estate rebuilds and imports. A new cluster simply installs from the first release carrying the removal (v0.0.58) and never sees the seam.
How the crossing is refused (added 2026-08-21)
Section titled “How the crossing is refused (added 2026-08-21)”“Refuses at boot” was half true when this page was written, and the half
that was missing is the one that mattered. assertNoDrift reads only the
catalogue’s own lexical window (name >= migs[0].Name AND name <= migs[len-1].Name), and a reset catalogue is one file, so that window is a
single point. Every row a pre-reset estate holds sorts below it: the
drift query returns nothing and the check passes. What actually refused
was X500967MIGAPL, the engine’s own “table already exists”, and only
because the regenerated baseline happened to recreate schema the estate
already carried. A reset whose baseline did not collide would have
half-run in silence.
Three refusals now stand between an estate and that outcome, listed earliest first. None of them is a bridge: every one of them ends in rebuild plus external import.
terraform plan:shc_node.ModifyPlanrefuses when the node’s own dpkg reading (installed_version, refreshed every plan) and the package the plan installs sit on opposite sides of v0.0.58, in either direction. Seeterraform/provider/internal/provider/migration_boundary.go. It fails open on an unread or unorderable version, on purpose; the apply-time and boot-time halves cover what it cannot see.- The roll, before
dpkg -i:rollPackageOverSSHasks the same question over the connection it already holds, and returnslanded=false. This is the last moment the answer can still be a refusal rather than a post-mortem, and it covers a-refresh=falseplan or a state file that has never carriedinstalled_version. - Boot:
db.AssertLedgerCovered(cecore/db/migrate.go), run once by the migrations subsystem over the union of every catalogue the binary carries, before a statement executes. A ledger row that no catalogue ships is refused withX500901OPFAILnaming the orphans and the remedy. It has to be the union rather than one catalogue at a time because_shc_migrationsis shared across namespaces, which is exactly whyassertNoDrift’s window exists and stays.
This is deliberately not shaped like BAD_RELEASES. That file names
versions that are bad for everyone and is copied across four surfaces kept
in lockstep by tests/unit/ci/bad_releases_test.go. This is one boundary
and a property of a pair (v0.0.58 is a good release for an estate
installed at v0.0.58), so it is a single constant in a single place.