Module source_cache 

Content-hash LRU cache for parsed source artifacts. ROADMAP L2 / E2 substrate; language-specific parse pipelines opt in via ParsedSourceLru::get_or_parse. ROADMAP L2 / E2 - content-hash LRU cache for parsed source.

Substrate that any language’s parse pipeline can opt into without plumbing a cache through every layer of the parser. The cache is keyed by the BLAKE3 content hash of the source bytes (or any caller-chosen extra-key extension), so two callers with the same source share the parsed artifact even if they hold distinct string allocations.

Why content hash, not string identity

In the downstream analyzer scan loop the same .h header is included from many translation units. Identity-keyed memoisation misses every caller because each caller holds its own String. Content-hash lookup lets every translation unit share a single parse.

Why LRU, not unbounded

Workspace scans touch tens of thousands of distinct files. An unbounded cache grows without bound; an LRU bounded by entry count keeps the working set in memory and evicts cold entries deterministically. Hits refresh recency in O(1); eviction scans only the bounded live set on insert.

Thread safety

The cache is Send + Sync - backed by a Mutex<...> so the parse work proceeds outside the global cache lock and only the lookup / insert / eviction touches it. Concurrent callers asking for the same key coalesce through a per-key in-flight slot, so the expensive parse closure runs once and every waiter receives the same Arc<T>.

Structs

ParsedSourceLru

Bounded LRU cache mapping SourceHash to Arc<T>. Eviction is LRU by last-touched order. Hits are O(1); eviction scans the bounded live set only when an insert needs space.

SourceHash

32-byte BLAKE3 content hash used as the cache key.

Functions

source_len_u32_nonzero

Convert source byte length to the non-zero u32 extent used by generated parsing Programs.