# Milestone 12 · Vector Retrieval at Production Shape (✅ COMPLETE 2026-06-14 / 2026-06-23)

Milestone summary row: [ROADMAP · Milestone Summary, M12](../ROADMAP.md).
Primary changelog record: [CHANGELOG.md](../../../CHANGELOG.md) (`[Unreleased]`).

> **Backfilled index, not a plan.** M12 has no `## Milestone 12` prose section in
> the ROADMAP — only a (detailed) summary-table row — and shipped without a
> planning directory. These records were assembled after the fact (2026-08-30)
> from the CHANGELOG, the M12 commits, the `docs/profiling/` evidence files, and
> the shipped test suite. Unlike M4 and M6, M12's numbers **are** recorded: this
> milestone's whole thesis was that ranking-at-scale must steer on measured
> numbers, so it left measurements behind.

## What the milestone proves

The feed stays relevant *and* bounded as the corpus grows past the scan cap.
Before M12, `for_you` and `related` fell back to scanning an arbitrary low-id
slice of the universe, per-query `ef_search` was accepted and silently ignored,
and the recall/latency/memory frontier at the production embedding shape
(1536-D) was unmeasured. M12 closed **G1** (bounded, relevant candidate
generation) and **G2** (measured ANN quality), then took the result to a real
sharded, mTLS, elastic cluster.

## Phases

| Phase | Name | Record | Landed |
|-------|------|--------|--------|
| m12p1 | Read-recall harness — measurement truth | [phase-1.md](phase-1.md) | `bb21e69` 2026-06-14 |
| m12p2 | ANN candidate generation in RETRIEVE | [phase-2.md](phase-2.md) | `bb21e69` 2026-06-14, cache fix `da5d2d4` |
| m12p3 | Index tuning + recall/memory frontier | [phase-3.md](phase-3.md) | `bb21e69` 2026-06-14 |
| m12p4 | Sharded ingestion | [phase-4.md](phase-4.md) | `31ee612` 2026-06-14 |
| m12p5 | Idle-readiness convergence | [phase-5.md](phase-5.md) | `aa94fd9` 2026-06-14 |
| m12p6 | TLS scale-up + HNSW graph persistence | [phase-6.md](phase-6.md) | `8e39ee1`, `4db3f1e`, `a039955`, `727fbfc`, `44ec878` 2026-06-14→16 |
| — | Multi-vector user preference modelling | [multi-vector-preference.md](multi-vector-preference.md) | `6a937fc` 2026-06-23 |

The last item is **not** numbered `m12p7`: the ROADMAP row lists it as a peer of
the six phases without a phase number, and no commit or doc ever called it
`m12p7`. Inventing one would put a fake identifier into the planning record.

## Evidence files this milestone left behind

| Evidence | File |
|----------|------|
| HNSW parameter sweep + F32/F16/Int8 frontier at 1536-D | [docs/profiling/usearch-tuning.md](../../profiling/usearch-tuning.md) |
| Scale baselines, recall-harness section, honest labelling of mean-vs-p99 | [docs/profiling/scale-baselines.md](../../profiling/scale-baselines.md) |
| Sharded-ingestion real-cluster run (T5) | [docs/profiling/m12p4-t5-sharded-throughput.md](../../profiling/m12p4-t5-sharded-throughput.md) |
| Idle-readiness fix + elasticity under load (T4) | [docs/profiling/m12p5-idle-readiness-elasticity.md](../../profiling/m12p5-idle-readiness-elasticity.md) |
| k3s deploy + recall findings, the 3-shard bug chain | [docs/profiling/m12-cluster-deploy-findings.md](../../profiling/m12-cluster-deploy-findings.md) |
| Spec updated to shipped reality (per-query `ef_search` IMPLEMENTED, not deferred) | [docs/specs/07-vector-retrieval.md](../../specs/07-vector-retrieval.md) |
| Multi-vector preference design | [docs/research/multi-vector-preference.md](../../research/multi-vector-preference.md) |

## Tests

`tidal/tests/m12p1_vector_recall.rs` (3), `m12p2_ann_retrieve.rs` (5),
`m12p6_graph_persistence.rs` (1), `m12_reseed_term_marker.rs` (4),
`m12_preference_event_time.rs` (1), plus
`tidal-server/tests/vector_search.rs` (8) and
`tidal-server/tests/cluster_region.rs` (14).

## What M12 did NOT close — stated, not buried

The ROADMAP records the honest residue, and it should not be read as complete:

- The **≥2.5× write-scaling / ≥5,000 quorum-writes-per-second** gate remains
  Ref-A/k3s-pending. m12p4 proved with data *why*: at fixed per-pod CPU,
  full-placement sharding scales failover, not write throughput. The ≥2.5× goal
  belongs to a ≥5-node **partitioned-placement** topology (Ref-B).
- The **30-day nightly gate is parked**: 23 PASS / 32 FAIL at 200 rps with
  repeated 4 GiB OOMKills. That is not a production-readiness signal yet.
- The **Ref-A 100k/1536-D memory growth** is still unisolated under the corrected
  4 GiB request / 6 GiB canary limit.
- Deferred follow-ups: `writer_agent` u16 interning on the WAL v3 envelope, and
  the offline medoid-recluster tier for multi-vector preference.