# m12p3 — Index tuning + recall/latency/memory frontier (✅ COMPLETE 2026-06-14)

Landed in `bb21e69`. Changelog: [CHANGELOG.md](../../../CHANGELOG.md).
Milestone index: [README.md](README.md). Backfilled record. This is the **G2**
work.

## What shipped

1. **Per-query `ef_search` — now actually honored.** `UsearchIndex::search` /
   `filtered_search` respect a per-request `ef_search`
   (`tidal/src/storage/vector/usearch_index.rs`). Pre-m12p3 the parameter was
   accepted for trait compliance, logged a warning, and **ignored**, because
   USearch 2.24 has no per-call beam argument. The override is race-free via an
   `RwLock` epoch guard (`with_expansion`): searches that agree on `ef_search`
   run in parallel under a shared guard, and only a query that changes the live
   beam width takes the exclusive guard for its `(set, search)` window — not a
   per-search mutex. `ef_search = 0` selects the slot default. The knob had been
   plumbed end-to-end in m12p1; m12p3 is what makes it move recall.
2. **Dimension-aware brute-force → HNSW crossover.** The exact `BruteForceIndex`
   scans every vector under a read lock at `count × dim` cost, so a fixed 10,000
   crossover meant a 15.4M-FMA scan at 1536-D — tens of milliseconds, blocking
   writers. `usearch_min_vectors(dim)`
   (`tidal/src/storage/vector/registry.rs`) now keeps a brute-force scan within
   ~4M FMAs: ≈10,000 at or under 128-D (byte-compatible with pre-m12p3
   behaviour), ≈2,600 at 1536-D. High-dimension mid-size slots flip to HNSW
   *before* the scan blows the SLA rather than after.
3. **`memory_usage()`** on `UsearchIndex` — the true graph + vector footprint
   reported by USearch, not the `index_stats` lower bound, so pod sizing uses a
   real number.
4. **A grid-search harness.** `cargo run --release --example ann_grid_search`
   (`tidal/examples/ann_grid_search.rs`) builds a `UsearchIndex` plus an exact
   `BruteForceIndex` oracle over the same deterministic id-keyed corpus and
   reports, per `(M, ef_construction, ef_search, quantization)` point: measured
   recall@10 vs the oracle, mean and p99 search latency, build time, and true
   footprint.

## Measured frontier (1536-D, 100k clustered corpus, real exact oracle)

The production default **M=16, ef_construction=400, F16 clears G1 and G2**:
recall@10 **0.997** at p99 ≈ 1.4 ms raw ANN. `ef_search` is the latency lever —
recall saturates by `ef_s=128`, where p99 ≈ 1.0 ms. **F16 costs 0.25% recall vs
F32 for half the RAM** (≈5.2 GB per 1M true footprint including the graph).
**Int8 is rejected** at 1536-D: recall 0.715, a 28% loss. Live
`tidal-stress --verify-recall` against a real server measured recall@10 = 1.0000
at 20k/1536-D at both the default beam and `--recall-ef-search 400`.

Full table: [docs/profiling/usearch-tuning.md](../../profiling/usearch-tuning.md).
1M command and baselines: [docs/profiling/scale-baselines.md](../../profiling/scale-baselines.md).

## The measurement artifact this phase caught

The recall corpus is now **clustered** (a Gaussian mixture) in both the grid
harness and `tidal-stress` (`recall::embedding_for`). Uniform-random high-dim
vectors are pathological for recall@k: under uniform data recall@10 fell from
≈0.97 at 10k to ≈0.54 at 100k. That was a **measurement artifact, not an index
regression** — at high dimension in a uniform shell, recall@10 measures
impossible tie-breaking rather than index quality. Every number above uses the
clustered corpus.

## Spec follow-through

[docs/specs/07-vector-retrieval.md](../../specs/07-vector-retrieval.md) was
updated in the same wave: per-query `ef_search` is IMPLEMENTED, not deferred.