stack/agents/darkwing/work/queue-a1/build.md

Queue A1 build (#1508), candidate for review

Darkwing built this on 2026-09-26 from section 8 of agents/filbert/work/queue-as-data-plan-2026-09-26.md (sha256 282fabbb, the only spec), split as Sage approved: render is in A1, move in-review needs --candidate until piece D, and a round's issue is the row's first issue. Filbert reviews the code; Sage commits after the suites. Base is HEAD 3a209eea. Nothing is committed, staged or pushed.

A stray pkill at 22:02:32Z stopped my first turn with only src/errors.mjs and src/io.mjs on disk. I reread both against what I had meant them to be. They match: the exit-code class, and the file layer with realIo as the only layer the CLI uses. Everything else was written after the restart.

Files

build-manifest.sha256 pins the 20 files. build.patch (sha256 419804f2) adds all 20 as new files with their modes. It applies cleanly to 3a209eea, and the applied tree matches the manifest and passes scripts/test-queue.sh.

• packages/queue/src/: errors.mjs, io.mjs (the fault-injectable file layer), lock.mjs (lock and unlock gate, 8.4), queue.mjs (serialization, replay, the transition matrix, next, render), store.mjs (canonical checks, the write path, witness, views, snapshot, verify), cli.mjs.
• packages/queue/tests/: data 19, lock 17, store 18, write 20, commit 21 tests, plus helpers.mjs and two child fixtures.
• packages/queue/package.json and README.md. The package has no dependencies.
• scripts/queue-commit.sh (0755): the 8.12 procedure and --install-hook.
• scripts/git-hooks/pre-commit (0755, POSIX sh): the queue guard.
• scripts/test-queue.sh (0755): the suite, in the style of test-discord.sh.
• docs/plans/BRIEF-TEMPLATE.md: the 8.13 template.

Which path runs verify once genesis is in

scripts/test-queue.sh runs node packages/queue/src/cli.mjs verify when git cat-file -e HEAD:docs/plans/queue.json succeeds. At HEAD today there is no queue.json, so it prints skip queue verify: HEAD has no docs/plans/queue.json (before the genesis commit) and stays green. A2 moves that call to scripts/mosaic queue verify when it adds the dispatch. queue-commit.sh also calls node packages/queue/src/cli.mjs directly (snapshot, then verify --snapshot from HEAD's archive) until A2.

Sage's five conditions

1. Nothing ran against the canonical .git. After all runs, .git/hooks holds only the samples, .git has no mosaic-queue* file, and git config --show-scope --get-all core.hooksPath returns nothing in any scope (rc 1). Every hook install, genesis, lock and gate test runs in a scratch repo under the system temp directory. Suite runs used a --shared clone at /tmp/qa1-verify.
2. docs/plans/QUEUE.md, AGENTS.md and docs/TOOLS.md are unedited. docs/SESSIONS.md shows as modified in the working tree, but that was someone else's edit before my session began; I didn't touch it.
3. scripts/test-queue.sh is green at HEAD with no queue.json: 19 checks passed, verify skipped as above.
4. H is recorded before the canary. commit.test.mjs has "H recorded before the canary": a shim commits on the first git hook run, and queue-commit.sh exits 1 with refs/heads/<branch> moved since <H>; nothing published. A second test moves HEAD after commit-tree with the same result. Mutation M1 (read H after the canary) fails the first test.
5. The fault file layer is reachable only from tests. Faults enter through the options the API takes (io, proc, hook, now, readOrder, lockWaitMs); cli.mjs passes none. The only process.env read in src/ is the default env in store.mjs's context.

Bugs found while building

• A nested node --test inherits NODE_TEST_CONTEXT and exits 0 whatever its tests do. Step 4's run of HEAD's archived tests therefore passed with a failing test in the archive. queue-commit.sh and test-queue.sh now run it under env -u NODE_TEST_CONTEXT, and a test commits an archive with a failing test and expects a refusal (mutation M4). Other suites in this repo that nest node --test may have the same blind spot. I haven't checked them.
• git 2.55 does not hold index.lock while the commit editor is open. The plan expected a paused git commit -e to block step 8. It doesn't: the paused commit loses later at its own HEAD update with cannot lock ref 'HEAD': is at C but expected H. The test now asserts that outcome. Nothing is lost, but the reason differs from the plan's.
• ext4 hands a freed inode number straight back. My first test for release's inode check wrote a byte-identical lock after unlinking the original and got the same inode back, so it proved nothing. It now writes a copy and renames it over the lock, which guarantees a new inode.

Choices the spec left open

• Verb names release and set. add requires --gate. A null brief is allowed only on rows that genesis creates as done. sync --op is optional.
• Reads need no actor. next with no seat and no $MOSAIC_AGENT_NAME refuses.
• accept-history accepts a stale table but not an unknown one. When a write succeeds but the table write is skipped, the CLI warns and exits 0.
• An invalid witness is treated as absent.
• GIT_DIR, GIT_WORK_TREE and GIT_COMMON_DIR refuse in the CLI. queue-commit.sh also refuses GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY and GIT_ALTERNATE_OBJECT_DIRECTORIES.
• Leftover temp files are unlinked. Genesis uses link, so it cannot replace an existing file.
• unlock works on a missing or invalid lock file.
• note on a blocked row edits blockedReason.
• Messages already name scripts/mosaic queue. The lost-history refusal names sync when the file holds genesis alone.
• --candidate auto-detects: an existing file is a manifest, anything else is a commit reachable from refs/heads or refs/tags.
• Only --install-hook is privileged in queue-commit.sh (jason or sage). The commit itself relies on the protocol that the lead runs it.
• After the snapshot, queue-commit.sh checks the genesis entry's branch and root against the current branch and root. For --genesis it also checks that H:<map> is the map blob genesis read.
• Step 8 compares the index's two queue entries with H's before it looks for index.lock, so "someone staged a queue path" is reported ahead of a lock.

Deferred

• 8.12's test of verify-commit on a prospective tree belongs to piece D, which adds verify-commit. It is not in A1.
• A2 holds the real migration map, the QUEUE.md markers and header, the row-7 pointer, the golden render, scripts/mosaic dispatch and docs/TOOLS.md.
• Sage adds queue to the suite list when A1 lands (lead decision 20).
• Bootstrap happens after A2's map and markers land: scripts/queue-commit.sh --install-hook --by sage, then queue genesis, then scripts/queue-commit.sh --genesis -m MSG.

Verification

In /tmp/qa1-verify (HEAD 3a209eea plus the 20 files):

Suite	Result
config	24/24
task	90/90
foundation	43/43
conductor	17/17
release	14/14
auth	15/15
discord	63/63
extension-package	18/18
queue	19 checks; node --test 95/95

The queue tests take about 18 s and were stable over two runs. A combined node --test run over every package came to 474/474.

I also ran the post-genesis path in a scratch repo: install the hook, genesis, --genesis commit, then test-queue.sh. verify printed ok verify rev 1: file valid, witness matches, view current. After a hand edit to one table cell it failed with view unknown.

Mutations

Each mutation went into the verify clone, the queue tests ran, and the original was restored. Every one was caught; the number is how many tests failed.

Id	Mutation	Failing tests
M1	read H after the canary	1
M2	drop the step-7 guard recheck	2
M3	drop step 8's entry comparison	1
M4	keep NODE_TEST_CONTEXT	1
M5	drop step 1's staged-path check	1
M6	update-ref without the old value	2
M7	skip the canary	2
M8	guard hook always passes	21
M9	drop step 8's index.lock check	1
M10	drop the exec-bit check	2
M11	drop the core.hooksPath check	1
M12	drop the map-blob check	1
S1	drop the "unchanged since read" check	1
S2	swallow the directory fsync error	2
S3	drop the recheck under the lock for unlocked reads	2
S4	drop the unlock-gate check	2
S5a	release ignores the inode	1
S5b	release ignores the record bytes	1
S6	write the witness before the rename	10
S7	drop genesis's fsync	1
S8	treat a reused pid as dead	11

S5 survived at first: the delayed-release test was caught by the byte comparison alone. The inode test in lock.test.mjs closes that gap.