pioneer: Instructions file for Codex

Database Architecture

These rules apply to the whole repository. More specific AGENTS.md files may add crate-local rules, but must not weaken the database invariants below.

Runtime Model

The Gateway SQLite runtime has two independent contours:

• a read-only reader pool, protected with PRAGMA query_only=ON;
• one serialized writer executor, because SQLite still has only one effective writer.

All database access must go through SqliteDatabase, CrudStore, and the existing repositories. Do not open ad hoc SQLite connections, use the writer pool directly, acquire scheduling permits manually, or bypass the writer executor.

Row-returning SQL is routed from the actual statement. Ordinary reads use the reader pool; writes, write transactions, and mutating ... RETURNING statements use the writer. A SELECT that invokes a mutating SQLite extension must use the explicit writer query API.

Scheduling Classes

Database handles carry their scheduling class. Queries and repositories must inherit the class from the scoped handle instead of classifying individual call sites.

• Interactive is the default for request work whose result a client is waiting for.
• Interactive also applies to history checking, preparation and necessary compaction that block the start of a user turn, including registration of legacy history metadata needed by that operation. Its ordinary reads and writes use the request's interactive scope.
• Maintenance must be selected explicitly for post-turn history checks and possible compression, independent background preparation, backfill, reconciliation, cleanup, indexing, and periodic work. Use CrudStore::with_maintenance_access() so both reads and writes are scoped correctly.
• Critical writes are reserved for narrowly defined control-plane or correctness work that must outrank ordinary writes. Background discovery that needs critical commits must use with_maintenance_reads_and_critical_writes(); it must not turn its reads interactive.