Files
stack/docs/plans/2026-10-20_plan-backup-line.md

3.7 KiB

Brief: the activate plan's backup line says what the run will do

Sage, 2026-10-20, for Vikunja P19 404 (Filbert's N1 and N2 on row 185, #1683 comment 29404; filed by Mos in mos-0930, owner Sage). Gitea #1684. Owner Darkwing, reviewer Filbert, gate owner Sage. Base: the refactor head at briefing, b724b7b0b or later. No other open row touches scripts/stack-release.sh. Line numbers are at b724b7b0b.

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

Row 185 (490e2771d) made every activate back up the stopped store, and activate --plan now prints one backup: line (:814-820). The plan prints the backup line whenever the store file exists. But run_steps (:846-849) rolls back with store-newer or migration-needs-flag before backup_store, so in those two cases the run takes no backup. The plan then says two things that can't both happen: the run would roll back, and the run backs up the store. T26 pins both lines together for the not-given --migrate case. That is N1.

N2: docs/TOOLS.md "Pinned stack update" step 3 lists what --plan names and doesn't mention the backup line.

Neither changed the Part A window, a 3i to 3i activate with no --migrate, where the line was right.

The change

  1. In plan, print the backup line only when the run reaches backup_store: an activate with a store file whose schema equals the target's, or is in the target's chain with --migrate given. When the run would roll back with store-newer or migration-needs-flag first, print backup: none; the run rolls back before the backup instead. The no-store line and the rollback branch (no line) stay as they are.
  2. When S_CHANGED is set the plan has no reliable schema to judge by. Keep today's backup line there, and say in BUILD.md why that is the safe reading.
  3. Don't change run_steps, backup_store, any refusal code, exit code or flag. The run already does the right thing; only the plan text moves.
  4. docs/TOOLS.md step 3 says the plan names the backup: where the run puts it, or why it takes none.

Tests

  1. Same-schema activate with a store: the plan prints today's backup line (T50 stays as it is).
  2. In-chain migration with --migrate: the plan prints the backup line.
  3. In-chain migration without --migrate: the plan prints the needs: --migrate (not given; ...) line and backup: none; the run rolls back before the backup, and no other backup line. Update T26's not-given case to match.
  4. Store outside the chain: the plan prints the store-newer line and the same backup: none; ... line.
  5. No store file: backup: none; there is no store file (T51 stays).
  6. Every case writes nothing, as --plan does today.

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

  • the plan ignores --migrate when it picks the backup line (today's text for the in-chain case)
  • the plan prints the backup line for a store outside the chain
  • the plan prints the none; the run rolls back line for 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

Any change to what the run does: the backup, its layout, the restore guard, a refusal or a flag. The row 178 proof flags in activate (mos-0928 Part B, the A0 tool row). Any run against ~/.mosaic-dev or the live units. Going live needs a re-pin, which is a later window, not this row.