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.
• Maintenance must be selected explicitly for background scanning, reconciliation, compression, migration/backfill, 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.

Do not classify work from actor kind, repository method, SQL text at the call site, or an arbitrary timeout. Do not promote background work to interactive or critical to make a test or latency symptom disappear.

Never Hold Database Capacity During Other Work

A writer reservation, write transaction, read transaction, query stream, or maintenance-read permit may be held only while performing the immediate, necessary database operation.