Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

docs(core): the outbox keeps each move's rows, not a board image [H21]

Corey Olson1cf85e5fb273
diff --git a/docs/formats.md b/docs/formats.md
index 64e5d715..372907b0 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -194,7 +194,7 @@ Engine 66 (`REOPEN_FIRST_REFUSAL_ENGINE`) holds a reopened item for its builder.
Engine 67 (`GATE_RUN_ENGINE`) records gate runs and the flake quarantine they prove. The gate writes a receipt for each real run of the accepted gate command on a clean, committed tree, under the common git directory at `pullboard/gate-receipts/<id>.json`: its id, kind (`gate`, `submit` or `land`), tree, head, accepted main, the command's SHA-256, its result, the committed file and name of each test that failed, the host load and the time. The writer is private to the gate and takes the result from the process it just ran; a run of any other command, or one whose checkout was dirty or moved, leaves no receipt. The coordinator's gate runs, from the main checkout and the landing, go on the board as `recordGateRun`; a seat's run keeps only its receipt. `recordGateRun` carries that receipt, and both a direct call and a sealed move are refused (`GATE_RUN_UNBOUND`) unless the store beside the board holds the same receipt byte for byte, so a run made up by hand is never recorded. A replayed move is applied as its origin checked it. When the coordinator's runs have found one tree both red and green for the same test, the board files one ordinary repair item for that test, with the runs as evidence, and records a `test-quarantine` event; a run any other seat recorded proves nothing. Quarantine itself is the coordinator's `flakes.quarantine` setting in pullboard.json, read from accepted main and off by default: with it off, runs and the repair item are still recorded, but nothing stops blocking a landing. With it on, a quarantined test still runs and reports, but a landing treats it as covered, like a waiver naming that file and test, as long as every run that proved it is a receipt on the landing machine and its repair item is not verified or withdrawn; it then blocks again, and only a newer red-and-green proof files a new item. A different red in the same run is never covered. An older engine refuses the move with `ENGINE_VERSION`.
-The relay outbox (#922, opt in with `relay.outbox`) lives beside `relay.json` as `relay-outbox.sealed`, mode 0600, sealed with the board key under the `outbox` seal kind at sequence 0. Inside is gzip JSON `{version: 1, base, baseSequence, restored, moves}`: `base` is the native board image as the relay last ordered it, at `baseSequence`, and each move is `{move, intent, queuedAt, after}` with the prepared engine move and the relay sequence this machine had seen. Its key-free summary, the list `pullboard status` shows, is `relay-outbox.summary.json` beside it, and `relay-outbox.generation` counts every move ever queued there; `relay.json` keeps the last twenty `outboxRefusals` and `outboxRenumbered`, never the summary. A replay reads every record the relay ordered after `base` (or the relay's checkpoint when it compacted them), then rebuilds the board in one step: it restores `base` (keeping each seat's newer shout-read position), applies those records, settles each queued move whose receipt is now on the board, seals the result as the new `base`, and applies the moves still queued on top. Only then does it send the moves still queued, each at the next sequence, and read again. The outbox adds no engine version: every move still replays through the relay's order.
+The relay outbox (#922, opt in with `relay.outbox`) lives beside `relay.json` as `relay-outbox.sealed`, mode 0600, sealed with the board key under the `outbox` seal kind at sequence 0. Inside is gzip JSON `{version: 3, baseSequence, restored, moves, results}`: `baseSequence` is the relay sequence the queued moves sit on, and each move is `{move, refs, intent, queuedAt, after, sequences, changes}` with the prepared engine move, the relay sequence this machine had seen, the board's `sqlite_sequence` rows just before the move, and the base64 SQLite changesets of the rows it changed here. An outbox written before #1013 is version 1 or 2 and also holds `base`, the native board image at `baseSequence`, and is replayed from that image until it empties. Its key-free summary, the list `pullboard status` shows, is `relay-outbox.summary.json` beside it, and `relay-outbox.generation` counts every move ever queued there; `relay.json` keeps the last twenty `outboxRefusals` and `outboxRenumbered`, never the summary. A replay reads every record the relay ordered after `baseSequence`, then rebuilds the board in one step: it takes the queued moves back by their inverted changesets, newest first, with the lifecycle triggers lifted in that transaction only, and puts `sqlite_sequence` back (keeping each seat's newer shout-read position); applies those records; settles each queued move whose receipt is now on the board; and makes the moves still queued again on top, capturing their rows afresh. When the moves cannot be taken back row for row, the relay's checkpoint stands in, if it is no older than `baseSequence`. Only then does it send the moves still queued, each at the next sequence, and read again. The outbox adds no engine version: every move still replays through the relay's order.
Local first (#1013, H21): on a board with `relay.outbox` on whose baseline the relay accepted, every move except a registration, a takeover, a person's request and landing authority queues itself in the outbox and is made on this machine at once, with no network call. `relay-outbox.guard.sqlite`, beside the link, is held in an exclusive SQLite transaction while a move queues and while a replay rebuilds the board, never across a network call. A refusal found at replay is also left for the worktree of the agent that made the move, as one JSON string per line in `relay-conflicts/<digest>.txt` (the first 32 hex of the SHA-256 of the worktree path), which that worktree's next command prints and removes. One background sender per machine does the relay's work, under `relay-sender/` in the machine's pullboard home: `sender.pid` is its claim (refreshed while it runs), `sender.starting` marks one being started, `sender.log` is its short log, and `boards/<digest>.json` is `{root, file, due}` for each board a command nudged, named by the first 32 hex of the SHA-256 of the link file's path.