stack/agents/darkwing/work/queue-181/BUILD.md

Row 181: the restore guard counts every row a restore drops

Brief: "# Brief: the restore guard counts every row a restore drops (row B)" in docs/plans/2026-10-20_stack-release-after-window.md (blob aafa471ae). Gitea #1679, Vikunja P19 390. Owner Darkwing, reviewer Filbert, gate owner Sage. Sage's rulings in sage-1163 (restated in sage-1180) settle the lists and the deviations below.

Files

File	What
build.patch	the change, git diff a757f8fe6 over the three paths below
candidate-manifest.sha256	one line per changed path

• Base: a757f8fe6 (row 180's landing, sage-1180).
• Changed: scripts/stack-release.sh, packages/cli/tests/stack-release.test.mjs, docs/TOOLS.md. These are the brief's touched files. Nothing else changed.
• Row 178 (Rocko) also touches scripts/stack-release.sh. Whichever lands second rebases (sage-1180).
• Line numbers in the script and test are at the candidate. Bus line numbers are at a757f8fe6.

Item 1: the tables a bus writer fills without an event

COUNTED (stack-release.sh:296) sits next to STORE_JS, in schema order:

role_claims thread_claims decision_events messages deliveries task_snapshots projects threads thread_opens instance_names usage_records

The only event writer is #event (broker.mjs:551, the INSERT at :561). The table below covers every INSERT in packages/bus/src (grep -nE "INSERT (OR [A-Z]+ )?INTO|UPDATE [a-z_]+ SET"). Outside the bus package, no code under packages/ or scripts/ writes these tables. The one other hit is a slice 1 prototype under agents/darkwing/work/slice1-proto/, which never opens a live store.

Table	Writer (broker.mjs unless named)	Why no event covers it
role_claims	:1575 role.claim (case :1542); :2483 #claimEnd (fn :2467), reached from role.release :1591, threadIdle :401 and :506, land-relaunch :1062, limit-check :1365, revoke :1614 and :1619, assistant.stop :2278	none of these write an event in the same transaction
thread_claims	:1551; :2470 #claimEnd	same
decision_events	:1687 (withdraw), :1734, :1769	the event at :1778 is written only if (s.human)
messages	:999, :1806, :1894 (tester message.send), :2377 (thread.send), :2518, :2565, :2596 (#specNotice :2588, from :1450)	no event
deliveries	:2645 #delivery (fn :2643), from message.receive :1915 and :1933, read :1953, routeWaiting :2661, routeThread :2670	no event (deviation 1)
task_snapshots	:1159 #snapshot (:1145)	recordTask's events are optional (:1116-1139)
projects	:2301 (case :2292)	no event
threads	:2331 (case :2318)	no event
thread_opens	:2362 thread.open, the tester path included (row 177)	no event
instance_names	:2257 name.set (:2242)	no event; consumeAuthority (:2255) is agents only
usage_records	usage.mjs:92, its own transaction (:88-98), at from new Date()	no event

Tables that are not counted:

• events is list 1, counted as before.
• decisions (list 3) is written only at :1696, and the action.allowed event at :1716 is in the same transaction.
• List 4 has no at column: meta, task_comment_cursors (:1129), message_threads (:2535) and sqlite_sequence. #route (:2535) writes a message_threads row only right after a messages row, which is counted (for example :2518 then :2531). A task_comment_cursors advance can be written with no event and no counted row, so a restore can drop it uncounted. The cost is that the PM sees comments a second time. Follow-up note F1 below.

The UPDATE list is empty

Every one of the 16 schema tables has a BEFORE UPDATE abort trigger, and a BEFORE DELETE one (packages/bus/schema.sql, for example meta :129-130). The only UPDATE in the bus source is the migration step at store.mjs:213-214, which drops meta_no_update inside the step's transaction (:212) and puts it back before the step commits. The guard counts rows by at, and no write path changes a row once written.

Deviations from the brief's examples (sage-1163; the brief is not re-pinned)

1. The brief names deliveries for list 3. message.receive (:1915, :1933) writes a deliveries row and no event, so it is in list 2.
2. The brief says projects has updated. It has at (packages/bus/src/migrations/3d-3e.sql:5), and the count uses it like every other table.
3. The brief says 14 tables have at. The head schema has 13: events, decisions and the 11 in COUNTED.

Item 2: one count over every listed table

STORE_JS count and heldcount take COUNTED as a fourth argument and count in the same open as before (readOnly for heldcount, ?immutable=1 for count):

• events after STAMP, then each listed table after STAMP;
• a listed table the store lacks counts 0 (no instance_names before 3g, no usage_records before 3h);
• a listed table that exists but cannot be read throws, as a failed events count does, and rollback refuses restore-mismatch ("cannot count the rows after STAMP"; the old text said "events", and no test pinned it).

The output is one line, TOTAL<tab>TEXT (:308). TEXT is N event(s) and then , M <table> row(s) for each listed table with rows, in COUNTED order. An events-only store prints the old text, so T13, T14 and T43 pass unchanged.

The brief's example puts usage_records before instance_names. I used schema order, which is COUNTED order.

Item 3: the refusal and the in-run recount

• post-backup-events (:917) refuses unless the total is 0 or --events equals it. The message is the full TEXT, so it names each table with rows. The flag and the code keep their names.
• The usage text (:39) and TOOLS.md say N is the total of the printed counts, read off the refusal.
• The in-run recount (:845-846) passes COUNTED too and compares the total with the pre-stop total. Rows are append-only (item 1), so an equal total means equal counts per table. Comparing the whole TEXT would add nothing.

Item 4: every table is in exactly one list

T46 runs packages/bus/schema.sql in memory, reads every table from sqlite_master, and checks that each one is in exactly one of:

1. events;
2. COUNTED, read from the script;
3. decisions;
4. meta, task_comment_cursors, message_threads, sqlite_sequence.

It also checks that every table in lists 1-3 has an at column and no table in list 4 does.

Tests

• T45 (stack-release.test.mjs:1220) has four subtests.
  • (a) Both modes, by unit, on scratch stores. Each of the 11 tables from a literal list (LISTED, so that a table dropped from the script's COUNTED fails here as well as in T46) counts 2\t1 event(s), 1 <t> row(s). One event, one usage_records row and one instance_names row count 3 in both modes. A 3f store with no usage_records counts 0 for it and doesn't throw. Neither mode changes the file's sha or leaves a -wal or -shm.
  • (b) End to end, for instance_names and usage_records. After activate --migrate, one row and no event refuses post-backup-events naming the table, with --events 1 in the message. With no --events and with --events 2, the run exits 3 before any systemctl stop and the fingerprint is unchanged. Then --events 1 restores to B/3g.
  • (c) A usage_records with no at refuses restore-mismatch before any stop.
  • (d) The in-run recount. A new one-shot fault in the systemctl stand-in, stop-writes-row (:139), writes a thread_opens row during the stop. The pre-stop total is 0, the recount finds 1, and the run rolls back post-backup-events to C.
• T46 (:1268) is item 4.
• T14 is unchanged and passes.

Runs

Sage gave the slot in sage-1182. The busy check passed, and the run (run181.sh, TMPDIR and output in my scratch) went from 2026-10-20T04:17:23.094Z to 04:23:54.822Z. Each mutant edits one file after a checked backup, runs the named test with --test-name-pattern, and puts the file back by the backup's sha.

Run	Test	Result	Failing subtests
stack-release.test.mjs, whole file	all	116 tests, 116 pass, 0 fail (row 180 had 109; T45 adds 6, T46 adds 1)	none
drop each of the 11 tables from COUNTED	T45	11 killed	(a) in every case; also (b) for instance_names and usage_records, (c) for usage_records, (d) for thread_opens
in-run recount on events only ("$COUNTED" removed at :845)	T45	killed	(b) both tables, since --events 1 no longer matches a recount of 0, and (d)
CREATE TABLE extra (seq INTEGER PRIMARY KEY, at TEXT NOT NULL) appended to schema.sql	T46	killed	"tables in no list"
decisions added to COUNTED	T46	killed	"a table is in two lists: decisions"

No test reads or pins a hash of the three changed paths except stack-release.test.mjs itself (git grep over packages/*/tests and scripts/test-*.sh).

Follow-up notes

• F1. A restore can drop task_comment_cursors advances without counting them (item 1). The table has no time column, so the guard can't count rows after STAMP. A fix needs either an at column (a schema change) or an event at :1129.
• F2 (Filbert's N1, #1679 comment 29372; optional). stack-release.sh:909 still says "the events after STAMP were counted" in the held-count recheck refusal. T29 pins that text (stack-release.test.mjs:815), so rewording it changes an existing test. I left it for a later row.

Candidate

• Base a757f8fe6. git log a757f8fe6..origin/refactor over the three paths is empty at 04:25Z (origin/refactor is a757f8fe6).
• build.patch: sha256 30a9b9e36afcf8f8ceaacce3fd3dddbde3733ba1a76fc87944766c0876093dda, patch-id (stable) 1fef78100554af5f4f1aa6a3e84663c23406e081, 3 files, 129 insertions, 16 deletions.
• candidate-manifest.sha256: sha256 46a4433ca4108682af2027dc27ad72359b45709006f809fbf45c4b45dfacc283.

Path	sha256
scripts/stack-release.sh	64f947a040d95b90b006dad43d6140eb4533082925e4e2a82ac4dc91c773f139
packages/cli/tests/stack-release.test.mjs	5ea483c114901de585a500e9cd87a02f5c06a63bb62f106290578784db6ca7d0
docs/TOOLS.md	4756c0ccf43be061ce9d2361882ec2ab78a0d2b622cda5224669d6bfd9bdda3b