stack/agents/rocko/work/queue-49/r1/MIGRATION.md

Row 49: explicit 3b→3c migration and cutover

Development seats use fixture databases only. These instructions are a plan, not live authorization. Mos runs the live operation only after their go, during a re-pin window that includes bus downtime. Nobody reads the live store for build/review evidence. There has been no live unit, file, bus or Console action.

1. Sage lands the reviewed candidate and identifies its pinned copy. Mos schedules the downtime/re-pin window and stops the bus using the established window procedure. No writer may remain; the migrator refuses an existing writer lock and never removes a stale lock. Resolve any lock under the established human recovery procedure, not by bypassing it.

2. Mos takes a consistent restorable backup of the stopped bus directory, including SQLite WAL state if present. Do not copy only bus.sqlite while WAL data exists. Record the backup identity and current copy, without printing database contents.

3. From the NEW pinned copy, Mos invokes the explicit migration, passing the actual absolute dataRoot (not a database filename):

   node /absolute/new-copy/packages/bus/src/migrate-schema.mjs /absolute/dataRoot
   

   Run this promptly after stopping the old bus: the initial epoch is migration host time minus a 60-second skew margin. Comments older than that initial cutoff cannot reliably be distinguished from historical comments without prior IDs. More than a minute of pre-migration downtime or tracker lag is outside this initial guarantee; arrange the window accordingly. Once 3c has run, later outages use persisted IDs and have no timestamp-window limit.

4. Migration validates source version, full trusted schema digest, metadata, WAL, timestamps and integrity before applying each named step. 3b→3c adds only the DDL in DDL.sql, creates the epoch and updates version/digest atomically. It preserves all existing evidence. Already-current is a validated no-op. An unknown version, damage, wrong metadata, missing store or active writer refuses. Stop the window on refusal; do not bypass validation or silently start old code against upgraded data. Future steps chain in order, with each committed version an explicit resume boundary.

5. Mos completes the re-pin and starts the new bus in the same approved window. Its startup reconcile restores cursor IDs and reads comments; the new copy is required because an old 3b Store refuses 3c. Perform the agreed human acceptance check. Any Console or other unit action remains a separately approved Mos step.

Rollback: code alone cannot downgrade 3c to 3b. With the bus stopped and Mos's go, restore the complete consistent pre-migration bus-directory backup AND the prior pinned copy. Restoring backup discards evidence recorded after the backup; Sage and Mos must decide the recovery rather than silently doing so. No automatic schema downgrade, pruning or live repair ships in this row.