Bound repeated disk PLE row reads with an opt-in host cache #791

Before you start

• Checked the Roadmap and FAQ.
• Searched existing issues and PRs for a bounded PLE row cache.

Applies to

Engine

What problem does this solve

The disk PLE backend deduplicates rows within one fill but rereads repeated rows across fills. Keeping the complete PLE table pinned requires much more RAM: the local Qwen3.8-Flash-Next GSQ checkpoint has 320001536 packed 90-byte rows.

Proposed solution

Add an opt-in, bounded host cache of raw rows, configured by --ple-row-cache-rows and disabled by default. An eight-way cache avoids per-hit allocation; misses retain the existing batched reader. Check byte fidelity, eviction, resizing, short-read recovery and GPU/graph parity. Keep the Windows portability work in #659 separate.

Alternatives considered

The pinned backend loads the whole table. The OS page cache is not a dependable substitute when the row store uses direct I/O. Small low-hit caches can add overhead, so this should remain opt-in.

Prepared on official main 546c5fe, Windows 11 / RTX 5070 Ti 16 GB (616.56) / Ryzen 7 9700X / 64 GB RAM, Torch 2.14.1+cu130. Local Windows tests layer the patch over #659. A draft PR will include correctness checks and PLE-path microbenchmarks; full-model A/B tokens/s and TTFT remain outstanding.