Prepare bounded speech diagnostics and document mixed routing risks

docs/RETRIEVAL-ROUTING.md

@@ -0,0 +1,57 @@
+# Mixed query routing audit
+
+Read-only implementation audit, 2026-10-13, source revision `5d9cfc4`.
+These findings describe current behavior; they are not a retrieval-quality
+measurement or an implemented ranking change.
+
+## Current behavior
+
+`HybridSearch::query_vector` selects Google's CodeRetrieval task only when
+`SearchOptions::code_only` is true. All-files searches use the general task,
+including natural-language queries asking for an implementation. The bounded
+query-vector LRU distinguishes tasks, so vectors cannot be reused across them
+accidentally. See `crates/searchi-service/src/lib.rs`.
+
+The audio preference in `crates/searchi-service/src/routing.rs` recognizes words
+such as speech, sound and music. Document and image cues veto that preference;
+code cues currently do not. If the preferred audio search returns any qualifying
+candidate, it becomes the exclusive semantic lane. Consequently a query such as
+"code that detects speech" can exclude semantic code candidates in All files.
+Lexical candidates still participate in hybrid fusion, and explicit Code scope
+bypasses this audio preference. This is a risk to evaluate, not proof that every
+such query fails.
+
+## Cost of adding lanes
+
+`crates/searchi-service/src/store.rs` retains one eligibility-cache entry.
+Its key includes the generation, user filters, source type and code scope.
+Changing a filter replaces the entry and scans/hashes matching passage metadata
+again. Alternating general and code lanes would therefore perform repeated
+eligibility work even when query vectors and the ANN graph are warm. The existing
+empty-audio fallback can also alternate audio and general filters.
+
+Incremental dirty-path updates apply when the cached filter matches and the
+revision is still within the dirty-history floor. A replacement cache design
+must preserve those freshness checks, generation invalidation, strict filtering
+before candidate limits, and the total allocation budget.
+
+## Next experiment
+
+First complete the unchanged frozen mixed baseline described in
+[MIXED-QUALITY.md](MIXED-QUALITY.md). Keep its labels and source bytes unchanged.
+Then compare soft audio preference and task-specific rank fusion against that
+baseline, retaining exact filename/symbol priority. Different task scores must
+not be treated as calibrated probabilities or compared blindly.
+
+Before introducing multiple lanes, measure a bounded multi-entry eligibility
+cache against a shared validated snapshot with derived code/origin views.
+Bound memory across all entries, rather than giving each the full chunk budget.
+Reuse the existing worker and prepared ANN graph.
+
+Report All-files and Code scope separately: top-1, recall@5, hard negatives and
+no-answer behavior, plus query-vector cache misses, inference time, eligibility
+scans/hash calls, memory and warm p95. Include mutation/deletion regressions.
+The existing `semantic.eligibility` and
+`semantic.eligibility_filtered_scan_and_hash` traces expose eligibility cost.
+Use an independently reviewed held-out corpus for acceptance; the frozen
+diagnostic alone must not become the optimization target.