perf(vector/search): no async / mmap-page prefetch for cold-cache HNSW graph

[mosuka]

Round-3 perf push sub-issue (tracked under umbrella #536).

[L] No async / mmap-page prefetch for cold-cache HNSW graph

• Where: HNSW reader uses OnDemand for Lazy storage (hnsw/reader.rs:260-313) but
  OnDemand::get does serial seek + read_exact (storage.rs:209-251). The HNSW search
  hot path falls back to get_vector for any non-Eager storage
  (hnsw/searcher.rs:586-595).
• Current behavior: In Lazy mode every neighbour load is a blocking seek+read. No
  page-cache warmup, no madvise(MADV_WILLNEED), no batched read.
• Why it might be a bottleneck / risk: Indexes that don't fit in RAM run at disk-latency
  × ef_search × neighbours.
• Reference precedent: DiskANN / Vamana beam-search batches I/O for BeamWidth
  candidates in flight; LanceDB IVF_PQ uses tokio::io::AsyncReadExt for cold scans.
• Suggested direction: (1) mmap() .hnsw in Lazy mode and madvise regions
  containing int8 payload. (2) Switch OnDemand::get to read N records in one syscall.
  (3) Beam-search variant of search_graph that holds BeamWidth candidates pending I/O.
• Risk / scope: Large. Dramatic win for disk-resident corpora.

---

ID: VS-20 — see ~/.claude/tasks/laurus/20260523_perf_round3_audit/task_list.md for the full Round-3 issue list.

[mosuka]

Batch re-triage of the Round-3 audit backlog (2026-08-02) — premise partially overtaken; remaining scope: "every neighbour load is a blocking seek+read" is stale for the default backend — mmap-backed MmapInput serves Lazy reads from memory and #522 added cached_input reuse. Remaining: (a) madvise/MADV_WILLNEED hints (none exist), (b) batched multi-record OnDemand::get, (c) DiskANN-style beam search with in-flight candidates.

[mosuka]

Supplementary findings from #656 (superseding #1148, which duplicated this issue)

While investigating #656 (HNSW two-hop prefetch lookahead), I independently rediscovered
this issue's core finding and filed it as a new issue (#1148) without checking for
existing overlap first — it duplicates this one. Closing #1148 in favor of this issue and
recording the additional detail found here instead.

Confirms and sharpens "no page-cache warmup, no madvise"

search_graph's prefetch gate is explicit and total for OnDemand, not just "no
warmup":

• HnswIndexReader::field_prefetch_index returns an empty HashMap
  unconditionally for OnDemand (laurus/src/vector/index/hnsw/reader.rs:892).
• OnDemand never has a QuantizedVectorPool, so the SQ-based sq_prefetch path
  (laurus/src/vector/index/hnsw/searcher.rs) is never populated either.
• search_graph's prefetch_enabled = sq_prefetch.is_some() || field_prefetch.is_some()
  is therefore false for OnDemand — every prefetch pass this file has (including the
  two-hop lookahead perf(vector/search): HNSW prefetch is one-hop; no lookahead via beam-search #656 just added) is skipped entirely for this storage mode, not just
  "not warmed up."

Why direction (1) (mmap + madvise) needs one more piece than stated

VectorStorage::OnDemand::get() (laurus/src/vector/index/storage.rs:233+) reads through
StorageInput::seek + a read call — an I/O abstraction, not a raw pointer into mapped
memory. Even once .hnsw is opened via an mmap-backed Storage, there's currently no way
to get a raw address out of StorageInput for a given offset to hand to madvise. That
plumbing (exposing a raw address only when the underlying Storage happens to be
genuinely mmap-backed) is a prerequisite this issue's suggested direction (1) doesn't
spell out but will need.

Task list / scope in the issue body stays as-is; this is additional technical grounding
for whoever picks it up.