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.
This commit is contained in:
jason.woltje committed 2026-10-20 01:32:18 -05:00
1 parent 9f5153deb2
commit 10e1bb4950
2 files changed
+373

No files matched your search

@@ -0,0 +1,70 @@
# 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.