perf: HNSW optimization sweep — batch transactions, search I/O, SIMD, and more

[aepod]

Performance Optimization Sweep

This is an ongoing PR that will accumulate multiple performance optimizations identified by a 4-agent audit of ruvector's HNSW implementation. Each optimization is investigated individually before implementation to avoid hidden regressions in this complex codebase.

Context

After running real benchmarks against hnswlib (C++), we identified several areas where ruvector-core is leaving significant performance on the table — not because the HNSW algorithm is wrong, but because of wrapper overhead, I/O in hot paths, and unused optimizations.

Current baseline (from PR #293):

Scale	ruvector QPS	hnswlib QPS	Gap	ruvector Build	hnswlib Build
10K	443	1,153	2.6x	44.0s	7.5s
100K	86	250	2.9x	855.6s	395.3s

Root Causes Identified

A team of 4 specialized performance agents audited the codebase in parallel:

1. Search path expert — Found that VectorDB::search() triggers a full REDB read transaction per result (10 results = 10 DB roundtrips). hnswlib does zero I/O during search.
2. Build path expert — Found that the benchmark uses individual db.insert() calls (1 REDB transaction per vector = 10K fsyncs at 10K scale). Also found that parallel_insert_slice() exists in hnsw_rs but isn't used.
3. Memory expert — Found triple vector storage (hnsw_rs + DashMap + REDB), Arc-heavy graph structure (~40 bytes per neighbor link vs ~8 needed), and 16-layer pre-allocation per point.
4. SIMD/distance expert — Found that hand-written NEON SIMD intrinsics exist in simd_intrinsics.rs but are NOT used in the HNSW search hot loop. Instead, every distance call crosses the FFI boundary to SimSIMD's C library, preventing inlining.

Optimization Plan (10 items, 3 phases)

Each item goes through: Investigate → Document → Implement → Test → Commit

Phase A — Quick Wins (this PR, in progress)

ID	Fix	Expected Impact	Status
OPT-4	Batch REDB transactions in benchmark	Build 1.5-3x faster (10K)	DONE ✅
OPT-1	Remove storage.get() from search path	QPS +30-50%	Investigating
OPT-2	Use native Rust NEON intrinsics instead of SimSIMD FFI	QPS +15-30%	Investigating
OPT-8	Add prefetching to search_layer	QPS +10-20%	Not started
OPT-9	Set REDB cache size limit	Memory -20-40MB	Not started

Phase B — Medium Effort (future commits)

ID	Fix	Expected Impact	Status
OPT-5	Remove/restructure outer RwLock on HnswInner	Enables OPT-3	Not started
OPT-3	Use parallel_insert_slice() for batch build	Build 2-4x faster	Not started
OPT-7	Replace HashMap visited set with bitset in hnsw_rs	QPS +10-15%	Not started

Phase C — Structural Changes (future PR)

ID	Fix	Expected Impact	Status
OPT-6	Refactor HnswInner.vectors DashMap	Memory -65MB	Not started
OPT-10	Replace Arc<PointWithOrder> with flat arrays	Memory -150MB, QPS +20-30%	Not started

Commits So Far

OPT-4: Batch REDB transactions in benchmark ✅

What changed: crates/ruvector-core/tests/bench_hnsw.rs

Before: The benchmark called db.insert(entry) in a loop for each vector. Each call opened a separate REDB write transaction → serialized the vector → wrote to B-tree → committed with fsync. At 10K vectors = 10,000 separate transactions.

// OLD — 10K individual transactions
for (i, vec) in data.iter().enumerate() {
    let entry = VectorEntry { id: Some(format!("v{}", i)), vector: vec.clone(), metadata: None };
    db.insert(entry).expect("Insert failed");
}

After: Uses db.insert_batch() which wraps all inserts in a single REDB write transaction with one commit.

// NEW — 1 transaction for all vectors
let entries: Vec<VectorEntry> = data.iter().enumerate()
    .map(|(i, vec)| VectorEntry { id: Some(format!("v{}", i)), vector: vec.clone(), metadata: None })
    .collect();
db.insert_batch(entries).expect("Insert batch failed");

Why this matters: The old benchmark was measuring REDB transaction overhead, not HNSW build performance. Production code (ruvector-server, ruvector-cli, ruvector-node) already uses insert_batch(). This change aligns the benchmark with real-world usage patterns.

No library code changed — this is a benchmark-only fix.

Investigation notes: We verified that storage.insert_batch() (at storage.rs:168-207) uses a single begin_write() / commit() pair. VectorDB::insert_batch() correctly delegates to it. The rvlite SQL path uses individual inserts by design (one INSERT = one vector), which is correct for that use case.

Target Metrics After Full Optimization

Metric	Current	Phase A Target	Full Target
QPS (10K)	443	~800	~1,000+
QPS (100K)	86	~150	~200+
Build (10K)	44s	~15s	~5-8s
Build (100K)	856s	~500s	~150-250s
Memory (100K)	523MB	~460MB	~250MB

How to Verify

# Run the benchmark (requires Rust toolchain)
cargo test -p ruvector-core --test bench_hnsw --release -- --nocapture

Compare build time before and after. QPS and recall should be unchanged since this only affects the insert path.

Test plan

• cargo test -p ruvector-core --test bench_hnsw --release passes
• Build time improves (expected 1.5-3x at 10K)
• QPS unchanged (search path not modified)
• Recall unchanged (HNSW parameters unchanged)
• All existing tests still pass: cargo test -p ruvector-core

🤖 Generated with claude-flow

[aepod]

OPT-2: Native Rust SIMD intrinsics instead of SimSIMD FFI ✅

Commit: 9d111d4

Replaced all 3 SimSIMD FFI calls in the distance hot path with native Rust SIMD intrinsics that were already in the codebase (simd_intrinsics.rs) but weren't being used for HNSW:

Function	Before (SimSIMD FFI)	After (Native Rust SIMD)
euclidean	simsimd::sqeuclidean().sqrt()	simd_intrinsics::euclidean_distance_simd()
cosine	simsimd::cosine()	1.0 - simd_intrinsics::cosine_similarity_simd()
dot product	simsimd::dot()	-simd_intrinsics::dot_product_simd()

Also optimized DistanceFn::eval (called hundreds of times per search):

• Added #[inline(always)] for compiler inlining into hnsw_rs search loop
• Removed distance().unwrap_or(f32::MAX) wrapper — now calls distance functions directly
• Eliminates: dimension check, Result construction, unwrap_or, one call indirection

Investigation notes:

• cosine_similarity_simd returns similarity, not distance — added 1.0 - similarity conversion
• Added is_finite() guard for zero-norm vectors (SimSIMD handled this internally, NEON impl does not)
• WASM path unchanged — still uses scalar fallback
• Existing distance tests verify semantic equivalence

[aepod]

OPT-8: Software prefetching in search_layer ✅

Commit: 4cc6eaa

Added prefetch hints in the hnsw_rs search_layer inner loop. When processing neighbor N's distance computation, we prefetch neighbor N+1's vector data into L1 cache.

Why this helps: Each vector is 512 bytes (128d × 4 bytes) on the heap. Without prefetching, accessing a neighbor's vector data triggers an L2/L3 cache miss (~50-100ns). By issuing a prefetch hint one iteration ahead, the memory subsystem starts fetching while the CPU computes the current distance.

Implementation:

• aarch64: inline asm `prfm pldl1keep` (works on stable Rust, no nightly)
• x86_64: `_mm_prefetch` with `_MM_HINT_T0` (stable with SSE)
• Other architectures: no-op (graceful degradation)
• Converted `for e in neighbours` to indexed loop for lookahead access
• Only prefetches first cache line (64 bytes) — hardware prefetcher handles the rest

Investigation notes:

• `std::arch::aarch64::_prefetch` is unstable (requires nightly) — used inline asm instead
• Prefetch is a hint, worst case ignored by CPU — zero correctness risk
• Vector data accessed via `point_ref.data.get_v()` returns `&[T]` (heap pointer or mmap slice)
• Multiple indirections (Arc -> Point -> PointData -> Vec) but vector data is the main miss