Files
jason.woltjeandClaude Opus 5.5 47a2925375 agents: Rocko row 138 round 2 packet r4 (#1632)
Round 2 candidate on 26a0b0fab, manifest digest e3f9a400...8f70, 43
paths. It adds tests for Dewey's D1-D4 (comment 28752), the N-a project
socket timeout fix, and the title and N-f text fixes (sage-0492).
Rocko's run: 753 package tests passed, 59/59 mutants killed. Packet
inventory 4a2a9c57...683f verifies 85/85; scanned for secrets and
binaries, none found.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-15 20:37:41 -05:00

85 lines
4.5 KiB
Markdown

# Row 138: offline schema 3e to 3f window
Only Mos runs the live steps, with Jason's approved downtime/re-pin window.
Development seats run this command against disposable fixture copies only.
Nothing in this packet authorizes a seat to read the live store, stop/start a
unit, migrate a live file, or re-pin a copy.
## Exact change
Source schema 3e is packages/bus/tests/fixtures/schema-3e.sql, copied from
26a0b0fab's repository tree, SHA-256:
21e6c091f14f818396f4d7836f381cc1389d45b2680ecaa1a00646b652c45050.
Target schema is 3f, source SHA-256:
472cbcd0d4548848873f3029e8250dc07bba4fb8db2a93241aae5b8e7e3771e2.
The new ordered step is packages/bus/src/migrations/3e-3f.sql:
```sql
ALTER TABLE decisions ADD COLUMN spec_path TEXT;
ALTER TABLE decisions ADD COLUMN spec_commit TEXT;
```
Both columns are nullable. Existing decisions get nulls; existing events,
settlements and every other row/old column stay unchanged. There are no specs
or spec_confirmations tables. Each completed named step commits separately;
prior migration steps and future-version chaining remain supported. Normal
startup refuses 3e under the new copy; it never auto-migrates.
## Mos's procedure, before and inside the window
1. Before stopping anything, prepare the approved pinned code copy and verify
its candidate/source manifests and migration command. Identify the existing
pinned copy for rollback. This packet does not switch any live pointer.
2. In Mos's approved window, make the PM run idle and stop all users of the bus
and the bus itself using the window's existing service procedure. Confirm no
writer remains. Do not migrate while the bus or another writer is running.
3. Make a consistent, owner-only backup of the stopped data root's entire bus
directory, including any SQLite WAL/SHM files. Keep the prior pinned code
copy and its launch/service settings with the backup receipt. Record time,
backup paths and hashes without printing message content. Do not delete an
unexplained writer.lock; diagnose it under the existing stale-lock procedure.
4. On a disposable copy of that backup, run the approved new copy's command
below and validate normal opening/quick_check/foreign_key_check. A refusal
stops the window for diagnosis. Never improvise around schema/digest checks.
5. With the live bus still stopped and the original backup preserved, Mos runs:
```sh
node <approved-copy>/packages/bus/src/migrate-schema.mjs <absolute-dataRoot>
```
It must exit 0 and end with `bus schema 3f ready`. The exclusive writer lock,
source schema/digest, timestamps, WAL and integrity checks must all pass.
Only the same stopped source proven in step 4 is used.
6. Mos follows the approved re-pin/start procedure for the new copy and checks
the stack-copy/runtime proof and normal reads. No spec or organization file
edit is required for this schema step; project init is a separate human
operation. Human spec commits confirm the spec; uncited existing raises work.
7. Record the backup, code copy, command exit, readiness checks and any downtime.
Existing settled decisions remain settled. Hold unrelated row migrations
until their own reviewed window plan says they may run.
## Refusal and rollback
A failed step rolls its transaction back; earlier completed named steps remain
valid. Preserve evidence and diagnose instead of retrying blindly. Rerunning an
already-current 3f store validates it without changing evidence.
If Mos chooses rollback, stop every new-copy reader/writer first, preserve a
consistent copy of the post-attempt bus directory for reconciliation, restore
the complete pre-window bus backup with its original permissions and WAL/SHM
state, and restore the prior pinned copy and launch settings together. Old 3e
code must never open the upgraded 3f file. Do not strip columns or edit evidence
in place. If any new messages/decisions were recorded after start, rollback
would discard them from the active store: Mos/Jason must resolve that data
boundary before proceeding; keep the post-attempt copy intact.
## Fixture evidence
spec-migration.test.mjs builds a 3e database from the pinned tree DDL, populates
every evidence table, keeps an untouched copy, checks normal startup refuses,
migrates, and compares every old table/column/row and sequence counter. Only
schema_version/schema_digest values and the two added null columns differ.
Integrity and normal 3f reopening pass. Existing 3b/3c/3d migration tests remain,
and the future fixture now chains through 3f to a fixture-only 3g.