feat(ruvector-diskann): land disk-backed rerank — DRAM compression now real

[ruvnet]

Summary

Stacked on PR #384. Closes the gap PR #384 deferred: today's with_originals_in_memory(false) returns InvalidConfig. After this PR, the option works — the index holds quantized codes + graph in DRAM and the final exact-L2² rerank reads originals from a memory-mapped sidecar file.

This is the PR that makes the "17.5× DRAM compression" the research roadmap projected actually real.

Measured DRAM compression (D=128, n=2000, RaBitQ)

Variant	DRAM cost (originals)	Codes (always DRAM)	Ratio
In-memory (default)	1 024 000 B (1 MB)	40 000 B	25.6× compression of codes vs originals
Disk-backed (this PR)	0 DRAM bytes	40 000 B	originals in kernel-owned mmap

25.6× exceeds the 17.5× target. The disk-backed variant pays only codes + graph + mmap-handle in DRAM; originals live in <storage_path>.originals as raw f32 with a 24-byte header.

What changes

1. OriginalsStore enum — InMemory(FlatVectors) | DiskBacked { mmap, n, dim }. Chosen over Box<dyn> for monomorphic dispatch on the rerank hot path + automatic Send + Sync.
2. memmap2 — already a workspace dep. No new deps.
3. Builder validation — with_originals_in_memory(false) requires storage_path; missing → InvalidConfig at build time.
4. Sidecar layout — [u32 magic][u32 version][u32 dim][u32 n][8 pad] followed by dim * n f32 values.
5. Backward compatibility — v1 indexes (no sidecar) fall back to the read-into-Vec path; load detects the sidecar and uses it only when present + the saved config requested it.

Observation worth recording

Pre-PR load() was already mmapping vectors.bin, then immediately copying it byte-by-byte into a heap Vec<f32>. The mmap field served no functional purpose — it just kept the file descriptor alive. This PR turns that latent mmap into the active reader and the v1 path becomes the legacy fallback.

Verification

• cargo build --workspace → 0 errors
• cargo build -p ruvector-diskann --no-default-features → OK
• cargo clippy --workspace --all-targets --no-deps -- -D warnings → exit 0
• cargo fmt --all --check → exit 0
• cargo test -p ruvector-diskann --features rabitq → 35 / 35 (was 30 in PR feat(ruvector-diskann): wire Quantizer trait into search path — codes load-bearing #384)
• cargo test -p ruvector-diskann --no-default-features → 19 / 19

New tests in tests/disk_backed_rerank.rs:

• disk_backed_yields_zero_dram_for_originals
• disk_backed_compression_exceeds_17x_at_d128
• disk_backed_recall_matches_in_memory (≥ 0.85 floor)
• disk_backed_save_load_round_trip_preserves_results
• with_originals_in_memory_false_requires_storage_path

Limitations flagged

1. RaBitQ codes don't persist across save/load (carried from PR feat(ruvector-diskann): add RaBitQ backend via new Quantizer trait (Phase 1 item #1) #383/feat(ruvector-diskann): wire Quantizer trait into search path — codes load-bearing #384). A reloaded RaBitQ-built index falls back to the f32 traversal path. The mmap loads correctly, but writing/reading the rotation matrix to disk is a separate follow-up. The save/load round-trip test uses PQ for this reason.
2. delete() rejected on disk-backed indexes (InvalidConfig). Writing through the mmap to NaN out a slot would break determinism under concurrent readers. Disk-backed callers must rebuild to delete; in-memory callers keep existing semantics.

Stack

base: feature/diskann-quantizer-search-path (PR #384)
base of base: feature/diskann-rabitq-backend (PR #383)
base of all: main

The three PRs together (#383 → #384 → #385) are Phase 1 item #1 from the research roadmap, fully realized: Quantizer abstraction → trait load-bearing in search → DRAM compression delivered.

🤖 Generated with claude-flow