Module cache 

MVCC-tagged, content-addressed page cache.

Correctness by construction: every entry carries the Epoch at which its page was committed, and the key is the page’s content/identity hash. A query at Snapshot only reads entries with committed_epoch <= snapshot.epoch; a rewritten page gets a new hash and the old entry ages out by capacity — so no invalidation sweep ever runs.

Eviction is a frequency-aware CLOCK (a.k.a. second-chance): each entry has a small access counter; the clock hand sweeps and either evicts a cold (counter == 0) entry or decrements a hot one (giving it a second chance). This blends recency (the hand sweep) with frequency (the counter) — an LRU/LFU hybrid — in O(1) amortized with no linked-list moves.

An optional persistent cache under _cache/ (raw on-disk bytes — ciphertext when the table is encrypted, so no plaintext ever persists) survives restart.

Structs

CacheStats

Cumulative page-cache access counters (Priority 14: hit visibility). A hit is a lookup that returned a page visible to the snapshot; a miss is a lookup that found nothing or an entry too new for the snapshot (the caller then reads from disk).

DecodedPageCache

Bounded LRU/CLOCK cache of decoded columnar pages (Phase 15.4). The PageCache above holds raw (ciphertext) page bytes; this second layer caches the post-decompress, post-decrypt typed page so a repeat scan skips decode entirely. Pages are immutable per (run_id, column_id, page_seq) identity (keyed via [crate::sorted_run::page_cache_key]), so there is no MVCC/invalidation concern — runs never change, and a rewritten page lives in a different run (different id) and simply misses here.

PageCache

Bounded, MVCC-safe page cache with frequency-aware CLOCK eviction and an optional persistent backing directory.

Sharded

A sharded mutex wrapper for the page caches. Each key routes to one of N independent shards (each with its own lock), so concurrent rayon workers probing different keys rarely contend on the same lock. A try_lock that fails under contention is counted as a try-lock-miss. (§5.8)

Constants

CACHE_SHARDS

Default shard count — balances contention reduction against per-shard overhead. Each shard gets total_capacity / SHARDS of the budget.