Module kv_blob_cache 

KvBlobCache trait + MmapKvBlobCache impl.

Substrate-trait-adapter for the local hot tier. Algorithm code (WombatKVKvStore) holds an Arc<dyn KvBlobCache>; foyer becomes one of N adapters, not a hard dep of the algorithm crate.

The FlatFileKvBlobCache impl is the embedded-mode default: flat <puffer_dir>/<key-hash>.kv layout, std::fs::read() on read, atomic tmp-then-rename on write. Reads ride the OS page cache for free, the same mechanism that gets ds4-native to 12-15 ms warm TTFT on a 47 MB blob.

std::fs::read is safe; the workspace forbids unsafe_code. read(2) from a page-cached file streams at ~5 GB/s on M3 Max, so a 47 MB warm read costs ~9 ms vs foyer’s 18 ms.

Profile-driven: 2026-05-15 instrumented run showed foyer’s block_on(inner.get()) was 17.96 ms of the 18.36 ms total C ABI warm-read time. Flat file drops that stage to ~9 ms on page-cache hit, ~15 ms on cold OS cache (NVMe-bound).

See bench_data/2026-05-15_warm_profile_attribution/finding.md.

Structs

FlatFileKvBlobCache

Flat file-per-blob cache. The hot read path is std::fs::read(), which streams from the OS page cache at ~5 GB/s on M3 Max NVMe. For a 47 MB blob already cached by the kernel (immediately after our own write, and across process restarts), this is ~9 ms vs foyer’s 18 ms async-SSD path.

Enums

KvBlobCacheError

Cache-construction failure surface.

Traits

KvBlobCache

Sync-only cache surface used by WombatKVKvStore. Implementations must be Send + Sync because the algorithm crate holds them behind Arc<dyn KvBlobCache>.