bench: add hnsw frontier counters

Author: arclabs561

benches/hnsw_search.rs

@@ -9,6 +9,8 @@ use rand::prelude::*;
 use std::alloc::{GlobalAlloc, Layout, System};
 use std::sync::atomic::{AtomicUsize, Ordering};
 use vicinity::hnsw::HNSWIndex;
+#[cfg(feature = "benchmark")]
+use vicinity::hnsw::{reset_search_counters, take_search_counters, HnswSearchCounters};
 
 static ALLOC_CALLS: AtomicUsize = AtomicUsize::new(0);
 static ALLOC_BYTES: AtomicUsize = AtomicUsize::new(0);
@@ -100,11 +102,25 @@ fn print_allocation_summary(
     ef: usize,
 ) {
     let mut alloc_total = AllocationProfile::default();
+    #[cfg(feature = "benchmark")]
+    let mut search_total = HnswSearchCounters::default();
     let mut result_count = 0usize;
 
     for query in queries {
+        #[cfg(feature = "benchmark")]
+        reset_search_counters();
         let (results, alloc_profile) =
             AllocationProfile::record_search(|| index.search(query, k, ef).unwrap());
+        #[cfg(feature = "benchmark")]
+        {
+            let counters = take_search_counters();
+            search_total.candidate_pushes += counters.candidate_pushes;
+            search_total.candidate_pops += counters.candidate_pops;
+            search_total.frontier_retain_calls += counters.frontier_retain_calls;
+            search_total.frontier_pruned_candidates += counters.frontier_pruned_candidates;
+            search_total.max_frontier_len =
+                search_total.max_frontier_len.max(counters.max_frontier_len);
+        }
         alloc_total.add_assign(alloc_profile);
         result_count += results.len();
     }
@@ -115,6 +131,15 @@ fn print_allocation_summary(
         alloc_total.calls as f64 / queries_len,
         alloc_total.bytes as f64 / queries_len,
     );
+    #[cfg(feature = "benchmark")]
+    eprintln!(
+        "hnsw frontier {label}: ef={ef} candidate_pushes={:.1}/query candidate_pops={:.1}/query retain_calls={:.1}/query pruned={:.1}/query max_frontier={}",
+        search_total.candidate_pushes as f64 / queries_len,
+        search_total.candidate_pops as f64 / queries_len,
+        search_total.frontier_retain_calls as f64 / queries_len,
+        search_total.frontier_pruned_candidates as f64 / queries_len,
+        search_total.max_frontier_len,
+    );
     black_box(result_count);
 }
 

docs/benchmark-results.md

@@ -1573,6 +1573,38 @@ The patch was reverted and saved locally as
 more than it saves on low-ef search, so further heap work should be driven by
 frontier-size counters or a profile, not by more unmeasured branch splitting.
 
+Benchmark-only HNSW frontier counters were then added behind the `benchmark`
+feature. They report candidate heap pushes, pops, frontier-retain calls,
+stale candidates removed by retain, and maximum frontier length during the
+existing allocation-summary prepass. The counters are diagnostic only; the
+timed Criterion rows from this short run should not be used as throughput
+evidence.
+
+```bash
+CARGO_TARGET_DIR=/tmp/vicinity-hnsw-counters-bench CARGO_INCREMENTAL=0 \
+  RUSTC_WRAPPER= cargo bench --bench hnsw_search --no-default-features \
+  --features hnsw,benchmark -- hnsw_search_ --sample-size 10 \
+  --warm-up-time 0.1 --measurement-time 0.1
+```
+
+| Workload | Candidate pushes/query | Candidate pops/query | Retain calls/query | Pruned/query | Max frontier |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| `hnsw_search_only/ef/10` | 36.7 | 14.5 | 0.0 | 0.0 | 35 |
+| `hnsw_search_only/ef/50` | 185.2 | 59.7 | 0.0 | 0.0 | 164 |
+| `hnsw_search_only/ef/100` | 351.2 | 108.3 | 1.0 | 212.0 | 291 |
+| `hnsw_search_only/ef/200` | 656.6 | 203.6 | 1.0 | 299.9 | 464 |
+| `hnsw_search_mmax32/ef/10` | 44.6 | 15.2 | 0.0 | 0.0 | 46 |
+| `hnsw_search_mmax32/ef/50` | 208.4 | 55.2 | 0.0 | 0.0 | 189 |
+| `hnsw_search_mmax32/ef/100` | 392.4 | 103.5 | 1.0 | 265.8 | 347 |
+| `hnsw_search_mmax32/ef/200` | 711.4 | 201.9 | 1.0 | 405.0 | 587 |
+
+The next HNSW frontier experiment should use these counters as a guard. The
+current prune path already fires only once per high-ef query on this fixture
+and removes many stale candidates, while low-ef rows never call retain. That
+makes another low-ef branch split unlikely to pay off. A custom frontier or a
+different prune trigger needs counters showing fewer pops or a smaller maximum
+frontier without hurting the `ef=10` rows.
+
 A follow-up finalization experiment tried to remove the intermediate top-k
 `Vec` allocation in `HNSWIndex::search` by chaining `take(k)` directly into
 the tombstone/doc-id conversion. The intended invariant was unchanged

docs/review-status.md

@@ -309,7 +309,7 @@ benchmarking, persistence, Python bindings, and performance work.
 | 13 | LSH/sketch boundary | The `lsh` feature uses `sketchir` for cross-polytope hashing primitives. Keep `sketchir` focused on MinHash/SimHash/LSH sketches and durable sketch sidecars; keep vicinity focused on ANN storage, exact reranking, persistence modes, and fixed-recall benchmark rows. Benchmark sharing is useful, but PRT, RP-tree/RP-forest, SparseMIPS, and LEMUR should stay in vicinity unless their role becomes pure sketch generation. |
 | 14 | External research claims | New implementation-scouting evidence points to Qdrant's mmap/residency model, Weaviate sparse visited sets, Qdrant/Vespa selectivity-gated ACORN, Faiss FastScan layout validation, DiskANN provider boundaries, and Qdrant-style private SIMD kernels as the most actionable prior art. Still verify newer roadmap claims before implementation: Extended RaBitQ, VSAG layout tricks, IP-DiskANN, PAG, SAQ, and ARM/SVE2 kernels. Keep `innr` as the optional dense-distance SIMD dependency; use local `pq_simd` work for PQ-code/LUT kernels that `innr` does not cover. |
 | 15 | Dataset difficulty metadata | First sampled profile script exists for VEC1/NBR1 datasets, and local profiles now cover SIFT, GloVe-25/50/100/200, Deep Image, NYTimes, Fashion-MNIST, MNIST, and GIST. Optional generated split labels are reported when present, and `scripts/summarize_dataset_profiles.py` renders profile JSONs into the docs table shape. `scripts/summarize_ann_results.py --profile-dir PATH` now joins exact profile metrics into ANN coverage rows while leaving capped dataset labels unlinked unless an exact profile exists. |
-| 16 | Profiling depth | Runtime profiles now cover HNSW search, ACORN filtered search, DiskANN direct-file rows, IVF-PQ ADC/allocation paths, dataset difficulty, and a same-binary `m_max=16` versus `m_max=32` HNSW search-only comparison. The ledger also records a build-path sample where `rustc` stalled in `readdir` over a large `target/debug/deps`; use isolated `CARGO_TARGET_DIR` values for future profile targets. HNSW binary inspection confirmed an indirect `blr x7` in `flush_batch`, and the new `distance_dispatch` Criterion group shows function-pointer dispatch costs on low-dimensional `innr` kernels, but the broad, `flush_batch`, and cosine-only HNSW dispatch rewrites all regressed or missed the keep threshold. The latest plain-HNSW symbolized sample still puts the largest leaf bucket inside `innr::dense::dot`; the ACORN samples first put the largest buckets in `HashMap::insert` and `reserve_rehash`, then shifted after dense tracking to inlined ACORN loop work plus `innr::dense::dot`. The kept ACORN fix is a safe visited-tracker change, not unsafe SIMD. The graph prefetch experiment removed a product unsafe surface and improved or held controls, so do not add local HNSW unsafe before safe heap/frontier/layout experiments. Next actual performance change should still record baseline, profiler target, negative controls, before/after, and rejected hypotheses in `docs/benchmark-results.md`. |
+| 16 | Profiling depth | Runtime profiles now cover HNSW search, ACORN filtered search, DiskANN direct-file rows, IVF-PQ ADC/allocation paths, dataset difficulty, and a same-binary `m_max=16` versus `m_max=32` HNSW search-only comparison. The ledger also records a build-path sample where `rustc` stalled in `readdir` over a large `target/debug/deps`; use isolated `CARGO_TARGET_DIR` values for future profile targets. HNSW binary inspection confirmed an indirect `blr x7` in `flush_batch`, and the new `distance_dispatch` Criterion group shows function-pointer dispatch costs on low-dimensional `innr` kernels, but the broad, `flush_batch`, and cosine-only HNSW dispatch rewrites all regressed or missed the keep threshold. The latest plain-HNSW symbolized sample still puts the largest leaf bucket inside `innr::dense::dot`; the ACORN samples first put the largest buckets in `HashMap::insert` and `reserve_rehash`, then shifted after dense tracking to inlined ACORN loop work plus `innr::dense::dot`. Benchmark-feature HNSW frontier counters now report candidate pushes, pops, retain calls, pruned candidates, and max frontier length for the search-only bench; they show high-ef rows prune many stale candidates once per query while low-ef rows never call retain. The kept ACORN fix is a safe visited-tracker change, not unsafe SIMD. The graph prefetch experiment removed a product unsafe surface and improved or held controls, so do not add local HNSW unsafe before safe heap/frontier/layout experiments. Next actual performance change should still record baseline, profiler target, negative controls, before/after, and rejected hypotheses in `docs/benchmark-results.md`. |
 
 ## Guardrails
 

src/hnsw/mod.rs

@@ -152,6 +152,8 @@ mod search;
 pub use graph::{
     HNSWBuilder, HNSWIndex, HNSWParams, NeighborhoodDiversification, SeedSelectionStrategy,
 };
+#[cfg(all(feature = "hnsw", feature = "benchmark"))]
+pub use search::{reset_search_counters, take_search_counters, HnswSearchCounters};
 
 // Filtered search (ACORN-style)
 #[cfg(feature = "hnsw")]

src/hnsw/search.rs

@@ -5,6 +5,89 @@ use std::collections::{BinaryHeap, HashSet};
 
 pub(crate) use crate::prefetch::prefetch_read_data;
 
+#[cfg(feature = "benchmark")]
+thread_local! {
+    static SEARCH_COUNTERS: RefCell<HnswSearchCounters> = const {
+        RefCell::new(HnswSearchCounters::new())
+    };
+}
+
+/// Diagnostic counters for HNSW search benchmarks.
+#[cfg(feature = "benchmark")]
+#[derive(Clone, Copy, Debug, Default)]
+pub struct HnswSearchCounters {
+    /// Number of candidate-frontier heap pushes.
+    pub candidate_pushes: u64,
+    /// Number of candidate-frontier heap pops.
+    pub candidate_pops: u64,
+    /// Number of frontier-pruning retain calls.
+    pub frontier_retain_calls: u64,
+    /// Number of candidate entries removed by frontier pruning.
+    pub frontier_pruned_candidates: u64,
+    /// Maximum candidate-frontier heap length observed.
+    pub max_frontier_len: usize,
+}
+
+#[cfg(feature = "benchmark")]
+impl HnswSearchCounters {
+    const fn new() -> Self {
+        Self {
+            candidate_pushes: 0,
+            candidate_pops: 0,
+            frontier_retain_calls: 0,
+            frontier_pruned_candidates: 0,
+            max_frontier_len: 0,
+        }
+    }
+}
+
+/// Reset the current thread's HNSW search benchmark counters.
+#[cfg(feature = "benchmark")]
+pub fn reset_search_counters() {
+    SEARCH_COUNTERS.with(|cell| {
+        *cell.borrow_mut() = HnswSearchCounters::new();
+    });
+}
+
+/// Return and reset the current thread's HNSW search benchmark counters.
+#[cfg(feature = "benchmark")]
+pub fn take_search_counters() -> HnswSearchCounters {
+    SEARCH_COUNTERS.with(|cell| {
+        let mut counters = cell.borrow_mut();
+        let out = *counters;
+        *counters = HnswSearchCounters::new();
+        out
+    })
+}
+
+#[cfg(feature = "benchmark")]
+#[inline]
+fn record_candidate_push(candidates_len: usize) {
+    SEARCH_COUNTERS.with(|cell| {
+        let mut counters = cell.borrow_mut();
+        counters.candidate_pushes += 1;
+        counters.max_frontier_len = counters.max_frontier_len.max(candidates_len);
+    });
+}
+
+#[cfg(feature = "benchmark")]
+#[inline]
+fn record_candidate_pop() {
+    SEARCH_COUNTERS.with(|cell| {
+        cell.borrow_mut().candidate_pops += 1;
+    });
+}
+
+#[cfg(feature = "benchmark")]
+#[inline]
+fn record_frontier_retain(before: usize, after: usize) {
+    SEARCH_COUNTERS.with(|cell| {
+        let mut counters = cell.borrow_mut();
+        counters.frontier_retain_calls += 1;
+        counters.frontier_pruned_candidates += before.saturating_sub(after) as u64;
+    });
+}
+
 // ─── Visited set ─────────────────────────────────────────────────────────────
 
 /// Threshold below which we use a dense generation-counter array instead of HashSet.
@@ -280,6 +363,8 @@ fn flush_batch(
                     id: batch_ids[i],
                     distance: dists[i],
                 });
+                #[cfg(feature = "benchmark")]
+                record_candidate_push(candidates.len());
             }
         }
         return;
@@ -300,6 +385,8 @@ fn flush_batch(
                     id: batch_ids[i],
                     distance: dists[i],
                 });
+                #[cfg(feature = "benchmark")]
+                record_candidate_push(candidates.len());
             }
             worst_dist = if results.len() < ef {
                 f32::INFINITY
@@ -372,7 +459,11 @@ fn prune_unpromising_candidates(
         return;
     };
     let worst_dist = worst.distance;
+    #[cfg(feature = "benchmark")]
+    let before = candidates.len();
     candidates.retain(|candidate| candidate.distance <= worst_dist);
+    #[cfg(feature = "benchmark")]
+    record_frontier_retain(before, candidates.len());
 }
 
 // ─── Search functions ────────────────────────────────────────────────────────
@@ -413,6 +504,8 @@ pub fn greedy_search_layer(
                 id: entry_point,
                 distance: entry_distance,
             });
+            #[cfg(feature = "benchmark")]
+            record_candidate_push(candidates.len());
             results.push(MaxResult {
                 id: entry_point,
                 distance: entry_distance,
@@ -424,6 +517,9 @@ pub fn greedy_search_layer(
             let should_prune_frontier = ef >= FRONTIER_PRUNE_MIN_EF;
             let mut pops_since_prune = 0usize;
             while let Some(candidate) = candidates.pop() {
+                #[cfg(feature = "benchmark")]
+                record_candidate_pop();
+
                 // Stopping condition: if best candidate is worse than worst result
                 // and we have enough results, we're done
                 let worst_dist = results.peek().map(|r| r.distance).unwrap_or(f32::INFINITY);