v0.5.5: dedicated ask ledger + run-ledger rotation contract (docs); --production-shape bench (#74)
Latestv0.5.5 — dedicated ask ledger + run-ledger rotation contract (docs); --production-shape bench
No behaviour change in sitter. This release ships a norm for operators and the evidence behind it.
Docs (the contract)
- Run the expect family on its own ledger.
expect/ack/ask/watch/sweepshould use a ledger that nositter runand no foreign writer appends to. Sharing stays supported, but every sweep or watch pass stages and replays the whole file, so its cost grows with the run supervisor's history rather than with live asks. (docs/reference.md→ Ledger placement and rotation;docs/reference.ja.md→ 台帳の配置とローテーション.) - Rotate run ledgers by rename, under the ledger lock, only when nothing in the expect family reads them. Two pre-rotation checks (no reference to the path from any expect-family caller; the
"expect_id"row count equals the record kept in<ledger>.expect-count, never re-derived from the file). A missing record on a file that carries expect rows is an unknown state and blocks both rotation and rescue. Never rotate a ledger the family reads — the next pass stages a fresh file and every active ask disappears silently. docs/specs/ledger-separation.md(new): the measured production shape (14,170 rows, 6 of them expect-family), why compaction was rejected at design review, contracts A1–A5 / B1–B5, and three runbooks exercised on macOS during review — one-time placement of live asks (drain every caller, copy and prove the copy byte-for-byte under the lock, repoint, re-prove), rescue of stranded asks (snapshot count,event_iddedupe, id-collision check and append in one lock hold, fail closed), and rotation with the count check and the rename in one critical section.
Bench
tests/fixtures/gen-ledger.sh --production-shape <lines> <out>: production-shaped ledger (run-family and foreign rows ≈ 5:3, the same six expect rows last). The two-argument mode is byte-identical to v0.5.4.tests/bench-ledger.sh --production-shape [--repeat N] [--lines N]: shared vs dedicated, median of N.
| ledger | rows | sweep --once |
watch --once |
|---|---|---|---|
| shared, production shape | 13,884 | 2.627 s | 1.412 s |
| dedicated ask ledger | 6 | 1.212 s | 0.076 s |
(macOS arm64, median of 3; the discarded rows cost ≈ 1.4 s per pass for either verb.)
Review
PR #83 — 12 rounds with Opus 5 / Qwen 3.8 Max / Gemini 3.8 Flash; every blocking finding was reproduced by the seat and adopted the same round; 3/3 GO at 6bd477a. Non-blocking leftovers are tracked in #84. Operator wiring (the maintainer's sitter-ask wrappers, launchd jobs and dashboard) is tracked outside this repository via #74.