Skip to content

v0.5.5: dedicated ask ledger + run-ledger rotation contract (docs); --production-shape bench (#74)

Latest

Choose a tag to compare

@github-actions github-actions released this 09 Sep 05:22
· 2 commits to main since this release
1c8bfcc

v0.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 / sweep should use a ledger that no sitter run and 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.mdLedger 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_id dedupe, 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.