Module format 

Wire format for the cache layer (paged-batchinvariant-v1).

Mirrors agent_docs/cache-layer.md §“On-disk format” exactly. The page manifest is serialized as JSON for human-debuggability; the per-page K/V payloads are raw bytes (zstd-compressed at the pf_core::cas::FsBlobStore layer, not double-compressed here).

Structs

CacheMeta

Static metadata describing a paged KV cache. Identical across pages of the same engine instance; embedded once in the PageManifest.

LogicalSeq

One logical request (sequence) in the cache, mapping its token positions onto a list of physical pages. Preserved across snapshot/restore so prefix-sharing (vLLM PagedAttention, SGLang RadixAttention) survives.

Page

One physical page in the cache. K and V are content-addressed independently so a fork that only mutates V (e.g. via a single-token generation step) shares its K page with siblings.

PageManifest

Top-level page manifest. Serialized as JSON; persisted as a single CAS blob whose digest goes into the .pfimg manifest’s cache.manifest field.

Enums

Dtype

Numeric dtype of cache entries. Matches the engine-side dtype 1:1 — we never convert here.

Constants

LAYOUT_V1

Schema discriminator for the v1 layout.