Module chunkcache 

A local copy of manifest chunks, kept by content address (latency plan 2026-10-23, lever A: docs/plans/flint-lean-latency-plan-2026-10-23.md).

Every manifest load used to fetch every chunk the pointer names, one sequential GET per 4,096 entries: 49 GETs at 200k files and 220 at 1M, on every pointer move, in the consume AND the commit, and twice per UI save in the gateway. Consecutive documents differ in one or two chunks, and a chunk never changes once written (its key IS the hash of its body), so a reader that kept the bodies it already has needs to fetch only the chunks that are new.

What makes keeping them safe:

• Content, not trust. A cached body is used only after it hashes to the address the pointer names (manifest::load_from). A damaged, truncated or planted file is a miss: dropped, and fetched. A forged body would need a preimage of the 128-bit address.
• Existence is still checked. The cache can vouch for a chunk’s bytes, never for the chunk still being in the bucket. A load that served any chunk from here also LISTs the chunk prefix, once, and a chunk the live pointer names that the bucket no longer holds is decided exactly as a 404 was: the pointer moved (a sweep took a superseded generation) restarts the load, an unchanged pointer is a hole and refuses. A document is never served short, and a live hole is never papered over.
• Remote names never become local paths unchecked. An address comes from the bucket; chunk::is_chunk_address admits 32 lowercase hex digits and nothing else, so no pointer can name ../x.

Two implementations: DiskChunkCache for the syncer (a directory in its state dir, so it survives a container restart and costs no memory between barriers), and MemoryChunkCache for the gateway (no local tree; one per workspace, beside its manifest cache). Both keep only the chunks of the document loaded last (retain), so either holds about one manifest: ~277 bytes per entry, 66 MiB at 250k files.

Structs

DiskChunkCache

The syncer’s cache: one file per chunk under the state dir (.flint-sync/chunk-cache/<addr>). The state dir sits in the app-writable tree, so every access is the state dir’s discipline: no symlink is followed at the directory or the file, a FIFO or a directory at a chunk’s name is a miss, writes go through safefs::write_via_tmp_fast, and every body read is verified by its caller before use.

MemoryChunkCache

The gateway’s cache: bodies in memory, one map per workspace.

Constants

MAX_CACHED_BODY

The largest body either cache keeps. A chunk is at most CHUNK_MAX entries, a few MiB; the tombstones object is bounded by TOMBSTONE_KEEP_SEQS. Anything larger is fetched every time rather than read into memory from a file the app could have grown.

Traits

ChunkCache

Chunk bodies by content address. Every method is best effort: a cache that cannot read or write costs requests, never correctness, so nothing here returns an error.