One Writer, Atomic Audit

"The change and the record of the change must live or die together. If one can happen without the other, you'll eventually get exactly that."

The storage layer's promises

Underneath the snapshot model sits SQLite, configured for durability over throughput: WAL (write-ahead logging), full synchronous writes, foreign keys on, and a busy timeout. And one architectural choice above the database: exactly one application worker owns all writes. Not a pool of writers racing for the same rows — a single writer, so there is never a question of who wrote last. For a single-family, local-first app, throughput was never the constraint; correctness under crash was, and every one of these settings buys correctness.

Why a single writer simplifies everything

SQLite allows many readers but serializes writers, and Keep leans all the way into that: one process, one writer. This dissolves an entire category of concurrency bug. There's no write-write race, no lost update from two workers reading-then-writing the same row, no need for optimistic-locking version columns on every table. The busy timeout handles the rare reader/writer overlap gracefully. Concurrency you don't have is concurrency you don't have to defend against — and at family scale, you genuinely don't need it.

Don't buy concurrency you don't need; it's paid for in complexity forever. Multiple writers are a real requirement at real scale — and a self-inflicted wound below it. A single writer turns a distributed-systems problem into a straight line of code. Match the concurrency model to the actual load, not to the architecture diagram you imagine you'll need someday.

The atomic audit — the part that really matters

Here's the invariant with teeth: every state mutation writes a before/after audit row in the same transaction as the change itself. Not "the change, then an audit log soon after." The same transaction. Either both the mutation and its audit commit, or neither does. This means the audit trail can never disagree with reality: there is no window where a value changed but the record of the change is missing, and no window where an audit says something changed that didn't. They're welded together by the transaction boundary.

If it's not in the same transaction, it's not really an audit. A logging call after the write looks like an audit but has a gap — the process can die in between, leaving a change with no record or a record with no change. The only trustworthy audit is one that commits or rolls back atomically with the thing it audits. Same transaction, or it's just hopeful logging.

WAL and full synchronous are the crash-safety pair. WAL lets readers keep reading while a write is in progress and makes commits durable via the log; full synchronous tells SQLite not to lie about when data hit the disk. Together they mean a power cut mid-write leaves you with a consistent database — the last committed state, never a half-written row.

One Writer, Atomic Audit

The storage layer's promises

Why a single writer simplifies everything

The atomic audit — the part that really matters

Code

External links

Exercise

Progress

Comments 0