SQLite storage

Store owns one SQLite connection. New empty databases are initialized with an application ID and schema version. Existing nonempty foreign databases and unknown versions are rejected rather than silently repurposed.

The current application ID is 0x53555043, and database schema version is 1. Crate release versions and protocol versions are separate. A code update must not assume that changing a package version authorizes an on-disk migration.

Tables and ordering

events uses the composite primary key (question_id, version, sequence). Each row contains a local commit timestamp and JSON event payload. Sequence one contains the question contract; later events are forecasts or resolutions. receipts maps a successful request ID to its decoded command and result.

Both tables are WITHOUT ROWID. Their primary keys support journal lookup and request replay. Update/delete triggers reject accidental edits to existing events and receipts. There is no cryptographic claim against a database administrator who can drop those triggers or rewrite the file.

Write transaction

For a mutation, the adapter:

1. Begins an immediate transaction and checks for an existing receipt.
2. Returns an exact matching receipt or rejects mismatched reuse of its ID.
3. Checks the connection-local data_version. Reuses a matching validated journal or loads and fully replays its history.
4. Validates the new event, including its predecessor and evidence.
5. Inserts the event and receipt.
6. Commits both together, then retains the validated state only if exactly the expected two SQL row changes occurred.

The lock covers the read/validate/write sequence, so two writers cannot independently validate the same predecessor and both create competing branches. A five-second busy timeout handles transient contention; callers still need a bounded backoff policy.

Replay validation

Reloading checks question identity and sequence continuity, reconstructs the core ledger, and applies every lifecycle rule. For calculated Bayesian revisions it also verifies the recorded prior, recomputes the posterior, checks evidence correspondence, and rejects origins already incorporated.

Origin tracking uses one running set across replay and subsequent cached mutations. Each Store retains at most one question history, with O(history plus evidence) memory. It moves that state into a tentative mutation rather than cloning the entire ledger. Any validation, insertion or commit error after taking the state discards it; only a successful commit can restore it.

The cache token is read inside the immediate transaction. SQLite changes data_version when another connection commits, so even an external change to an earlier event invalidates the cache. Any external commit conservatively invalidates it, including an unrelated question’s write. Extra same-connection trigger changes suppress cache retention. Reads and evaluation always perform full replay; restart and question switches also take the cold path. There is no persistent checkpoint and no schema change.

See storage profiling and results for the measured gain, cache tests and remaining limits. Do not describe database writes using the core’s nanosecond arithmetic benchmark.

Durability

Connections use rollback journaling with synchronous=FULL. A successful response follows the SQLite commit. Durability still relies on SQLite, the filesystem, and storage hardware honoring their contracts. Local filesystems are the tested context; shared network filesystems are not part of the validated deployment model.

The implementation is based on SQLite’s transaction semantics and synchronous setting. Tests cover reopening, competing connections, numerical replay, protected rows and failed-write rollback. They do not emulate power loss.

For backups, stop writers before copying the database or use SQLite’s backup facilities. Do not copy only one file from an active database state without understanding its journal. Treat restored records as needing the same replay validation as ordinary reads.