Module core 

FileStore struct and CRUD operations.

Structs

FileStore

SQLite-backed file storage with write-through cache.

ReaderPool 🔒

Connections that only read, for a file-backed store. In WAL mode a reader sees every committed write and never waits for a writer, so reads taken through these don’t queue behind the writer’s mutex — which, on the global transcript store, every agent’s appends share, and which a write holds while it waits up to busy_timeout for another srv instance’s write lock (REPORT_AGENT_OPEN_STALL_RCA_2026_10_05.md). Opened on demand and kept for reuse, at most READERS_KEPT idle.

TimedConn 🔒

The store’s connection, held: logs on drop when it was held for SLOW_CONN or longer, naming where it was taken. Every store operation in the process waits for this one lock — on the global transcript store, every agent’s appends and every pane’s history reads — so a long hold stalls them all (REPORT_AGENT_OPEN_STALL_RCA_2026_10_05.md).

Constants

CACHE_TTL_SECS

Clean cache entries idle longer than this are evicted during flush.

DEFAULT_FLUSH_SECS

Default flush interval in seconds.

MAX_CACHE_BYTES

Hard cap on the total byte size held in the metadata cache (128 MB). When this is exceeded, LRU eviction removes the oldest entries first.

PART_DATA_SIZE 🔒

Default part size: 64KB (matches Go’s DefaultPartDataSize).

READERS_KEPT 🔒

Idle reader connections kept for reuse; more may be open at a busy moment.

SLOW_CONN 🔒

Waiting this long for the connection, or holding it this long, is logged with the call site (FileStore::lock_conn).