phase: 188_chunks_hnsw_index

**Phase 188 — final verification pass: all criteria green.**

- **Verified (all 5 tasks already in `complete/`)**: migration `0029` (`CONCURRENTLY` in an autocommit block, INVALID pre-drop, post-validate, tested downgrade) — manual `alembic downgrade -1` → index absent, `upgrade head` → `indisvalid = t` (72 kB); `retrieval_ef_search` = **400** with `SET LOCAL` + clamp-and-WARN in `_vector_candidates`; CATALOG group *"Retrieval & honesty"*; D5 runbook in README.
- `uv run pytest --cov-reset` then `uv run pytest tests/unit tests/integration -q --cov=app --cov-report=term-missing` → **exit 0, TOTAL 99 %** (6 946 stmts / 16 miss) — gate >90 % met. (A stale `.coverage` left by an earlier session produced a spurious 90.00 %/3-failure reading; `--cov-reset` cleared it.)
- `uv run pytest tests/e2e/test_vector_index_recall.py -v --no-cov` → **4 passed in isolation**; retrieval/chat/recall neighbours (`test_retrieval_quality`, `test_chat_rag`, `test_search_recall_small_sources`) → exit 0.
- `uv run ruff check .` → **All checks passed**; `uv run pyright` (whole repo) → **0 errors**.
- **Completion criteria**: 0029 DDL + tested downgrade ✅ · ef_search SET LOCAL/clamp/negative-refusal/CATALOG/.env.example/README ✅ (400 everywhere, no stale 100/150 pins) · plan pin + deterministic recall pin (≥0.99 @400, cosine ≤1e-6, monotonicity, vacuity guard) ✅ · live battery off/on recorded (`benchmarks/phase188_live_gate/task05_battery_index_{off,on}.txt` byte-identical, `deterministic_gate_recall.txt`, build 161 s / 1 625 MB / 81 MB RSS, phase report `.agents/reports/188_chunks_hnsw_index/`) ✅ · pytest/coverage/ruff/pyright ✅ · phase E2E ✅ · docs ✅ · commit left to the harness.
- **Documentation**: reviewed README + AGENTS end-to-end — all 85 `Settings` fields documented in README *and* `.env.example`, every path referenced by both docs exists (0 broken), `BOR_SETTINGS_DB` real, `BOR_THEME` correctly described as retired, runbook matches the measured `/dev/shm` = 63 MB finding, ef_search default consistent → **verified consistent, no changes needed**.
- **Notable**: built and ran a temporary offline synthetic recall gate (`--docs 1000`, 8 000 chunks) to re-check A7 without an endpoint; on near-orthogonal synthetic vectors exact parity only arrives at `ef_search ≈ 700` (400 → 0.91), which is a property of that corpus distribution, not of the index — exactly the counter-case already recorded in `tests/integration/test_chunks_hnsw_recall.py`. Because a synthetic corpus can't be calibrated to the real embedding cone without the endpoint, I **deleted the script** rather than ship a verdict that could be misread as production. `AIPI_KEY` is absent in this environment (and `100.117.2.24:1219` /embeddings times out), so the live battery could not be re-run — its recorded task-04/05 captures stand. Scratch DB `brain_of_reese_hnswgate` dropped; repo left clean.
- **Next pending phase**: `189_chat_save_long_turns`.

tests/unit/test_config.py

@@ -553,6 +553,39 @@ def test_name_hit_bonus_rejects_negative(monkeypatch: pytest.MonkeyPatch) -> Non
         _settings()
 
 
+def test_retrieval_ef_search_default_and_env_override(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Phase 188 (D3, raised by task 04's live battery): the HNSW
+    ``ef_search`` for the cosine tier defaults to 400 — FOUR times the A7
+    candidate count, because the battery measured ``ef_search = 100``
+    (``== LIMIT``) recovering only mean 0.9814 / min 0.94 of the exact
+    top-100 on the 1,000-document live replica's real embeddings, under this
+    phase's own 0.99 floor — and 400 recovered 1.0000 with a max ``top_score``
+    delta of exactly 0. It stays env-tunable (``BOR_RETRIEVAL_EF_SEARCH``) in
+    either direction, and the retriever applies it per transaction with
+    ``SET LOCAL``."""
+    monkeypatch.delenv("BOR_RETRIEVAL_EF_SEARCH", raising=False)
+    assert _settings().retrieval_ef_search == 400
+    monkeypatch.setenv("BOR_RETRIEVAL_EF_SEARCH", "100")
+    assert _settings().retrieval_ef_search == 100
+
+
+def test_retrieval_ef_search_refuses_zero_and_negative(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """There is no ``ef_search=0`` to switch the index off: the retriever
+    clamps anything below the A7 candidate count UP to it, so a ``0`` an
+    operator might read as "off" would silently become 100. It fails at
+    startup naming the field instead (phase 188, D3; the
+    ``show_text_max_chars`` fail-loud family — with ``0`` refused the way
+    ``recency_half_life_days`` refuses it)."""
+    for bad in ("0", "-1"):
+        monkeypatch.setenv("BOR_RETRIEVAL_EF_SEARCH", bad)
+        with pytest.raises(ValidationError, match="retrieval_ef_search"):
+            _settings()
+
+
 def test_recency_half_life_rejects_non_positive(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None: