The Ledger: What Happened

A guarantee enforced by the database, not just application code

Every ledger event carries a strictly monotonic sequence number scoped to its run — and that ordering isn't just application discipline, it's backed by a real unique index at the database layer, so a bug that tried to write two events at the same sequence number for the same run would fail loudly at the SQLite layer rather than silently corrupting replay order. Reads are cursor-paginated in sequence order deliberately, avoiding the classic offset/limit correctness trap where new writes between two paginated reads can skip or duplicate rows.

A fast path that still falls back safely

Every append also fans out as a realtime ledger.event envelope, which is what lets the dashboard's Ledger Strip show new events the instant they happen without polling. For performance, an in-memory high-water-mark cache tracks each run's latest sequence number so appending doesn't need a round-trip query on the hot path — but on a cache miss (a fresh process, an eviction) it safely falls back to computing MAX(sequence) directly, so a cold cache degrades to "slightly slower," never to a wrong sequence number.

Continue