Skip to content
SHC Docs

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.

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.”

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.

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.

  1. terraform plan: shc_node.ModifyPlan refuses 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. See terraform/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.
  2. The roll, before dpkg -i: rollPackageOverSSH asks the same question over the connection it already holds, and returns landed=false. This is the last moment the answer can still be a refusal rather than a post-mortem, and it covers a -refresh=false plan or a state file that has never carried installed_version.
  3. Boot: db.AssertLedgerCovered (ce core/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 with X500901OPFAIL naming the orphans and the remedy. It has to be the union rather than one catalogue at a time because _shc_migrations is shared across namespaces, which is exactly why assertNoDrift’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.