Files
stack/docs/plans/2026-10-20_activate-always-backs-up.md
jason.woltje 10e1bb4950 plans: row 185 brief, every activate backs up the stopped store (#1683); mos-0928 window plan
A same-schema activate takes no store backup: backup_store runs only when
the schemas differ, and the two live backups (3f, 3h) don't match 3i, so
rollback --restore refuses both. Row 185 makes every activate back up the
stopped store before any migration and keeps the in-run restore
migration-only. Part A of the mos-0928 plan (re-pin 89af38a83 to the
refactor head) needs it first. Part B, the row 178 proxy proof
activation, is drafted for Jason and runs nothing.
2026-10-20 01:32:18 -05:00

4.3 KiB

Brief: every activate backs up the stopped store

Sage, 2026-10-20, for mos-0928 Part A (agents/sage/work/window-plan/repin-rows-177-185.md). Gitea #1683. Owner Darkwing, reviewer Filbert, gate owner Sage. Base: the refactor head at briefing, 9f5153deb or later. No other open row touches scripts/stack-release.sh. Line numbers are at 9f5153deb.

Nothing here runs against the live stack. Every test uses the stand-in systemctl, units, stores and data root that packages/cli/tests/stack-release.test.mjs already builds.

Why

Mos's mos-0928 asks for a re-pin from 89af38a83 to the refactor head with a backup first and the row 181 restore guard in the rollback path. Both copies are at schema 3i, so the activate runs no migration, and backup_store (:349) runs only in the migration branch of run_steps (:839). A same-schema activate takes no store backup. rollback --restore then has nothing to name. The live root holds two backups, a 3f one from the 8e7ea89a1 window and a 3h one from the merged window. do_rollback refuses both restore-mismatch because their SCHEMA isn't the target's (:904-905).

A backup made by hand would sit outside the tool's layout, and restoring it by hand skips the row 181 guard, which is what Mos asked for. So the activate itself takes the backup, under the activation id the rollback then names.

The change

  1. run_steps migrate backs up the stopped store on every activate where the store exists, after the store-unclean and schema reads (:831-833) and before any migration. A failed backup rolls back with backup as today. A missing store takes no backup, as today.
  2. The in-run restore stays a migration-only step. TAKEN (:367, read at :543) is set only once a migration is about to run, so a gate failure on a same-schema activate puts back the units and the wrapper and leaves the store as it is, as today. BACKUP is set by every backup, so the log line names it and from_log backup finds it. The builder says in BUILD.md how they split the two and why.
  3. --plan for an activate prints one line that says a backup of the stopped store is taken under <dataRoot>/backups/stack/<activation>/. Keep the migration lines as they are.
  4. rollback and pm-on are unchanged. A rollback with --restore already moves the store it replaces to the post-attempt path, and pm-on never touches the store.
  5. docs/TOOLS.md "Pinned stack update" step 5 and step 6 say what the run now does: a backup on every activate, a restore after a gate failure only when a migration ran. Step 7 says a same-schema rollback can take --restore with that backup too.

Tests

  1. A same-schema activate leaves backups/stack/<activation>/ with SHA256SUMS, DATA_ROOT, SCHEMA equal to the store's, and STAMP, and the log line's backup names it. Update T5 if it asserts no backup.
  2. A gate failure on a same-schema activate rolls back without restoring: the store's sha after the rollback equals its sha after the failed gate, and no post-attempt store appears. T8's migration case still restores.
  3. A same-schema rollback --restore <that activation> with no rows after the STAMP restores and goes live. With one instance_names row after the STAMP it refuses post-backup-events, and --events 1 passes. This is the path Part A's rollback uses.
  4. --plan prints the backup line and writes nothing.
  5. A missing store still takes no backup.

Mutants, each killed by some gate test (mos-0862):

  • the backup runs only when the schemas differ (today's code)
  • TAKEN is set on a same-schema backup, so a gate failure restores
  • the log line's backup is empty on a same-schema activate

Gate

Filbert approves the candidate manifest. Cli suite and every scripts/test-*.sh green on Sage's gate, run from a git worktree of the candidate. Touched files: scripts/stack-release.sh, packages/cli/tests/stack-release.test.mjs, docs/TOOLS.md, and the packet. Anything else gets named in BUILD.md with the reason.

Out of scope

Pruning backups (nothing prunes them; each live one is about 2.2 MB). A backup on rollback or pm-on. Any change to the backup layout, the restore guard, a refusal code or a flag. The row 178 proof flags in activate, which mos-0928 Part B names as a later row. Any run against ~/.mosaic-dev or the live units.