feat(recall): structured per-stage scores and two-level min_scores filtering

[nicoloboschi]

What

Replaces recall's single score field with a structured scores object (one score per pipeline stage) and replaces the min_score request param with min_scores, a per-stage filter that operates at two levels of the pipeline.

Response — scores on every result

field	meaning	null when
final	the score results are ranked by	—
reranker	cross-encoder normalized relevance (0–1)	passthrough reranker (rrf/interleave)
semantic	raw vector cosine similarity (0–1)	not surfaced semantically
keyword	raw keyword/BM25 score (≥0)	not surfaced by keyword search

Per-arm semantic/text scores are aggregated across retrieval arms during RRF / interleave fusion (ArmScores on MergedCandidate) — fusion otherwise keeps only the first-seen arm's score per doc.

Request — min_scores (opt-in, inclusive, AND-ed; default = no filtering)

field	level	effect
semantic	retrieval	min vector similarity, pushed into the SQL arm (overrides global similarity min for the request) — prunes before fusion
keyword	retrieval	min keyword/BM25 score, pushed into the SQL arm
reranker	post-query	min normalized cross-encoder score on ranked results
final	post-query	min final ranking score on ranked results

{ "query": "...", "min_scores": { "reranker": 0.5 } }

Why

The recall pipeline computes several scores but only exposed the final one, and only via trace. Exposing them lets callers inspect ranking and threshold on the stage they care about.

There is deliberately no default threshold. The cross-encoder's absolute scores are reliable for ordering but not calibrated across queries — e.g. for query software, the correctly-#1-ranked "Alice prefers Python over Java" scores ~0.001, while a natural-question phrasing of the same intent scores ~1.0. A fixed default cutoff would silently drop good results, so min_scores is fully opt-in.

Also in this PR

• Surfaces proof_norm in the search trace so the scoring breakdown reconciles.
• Control-plane trace view: renders scores at full precision (no rounding — rounded 0.001 hid real differences) and shows the per-stage scores breakdown; relabels the trace's "CE" → "reranker score".

Surfaces touched

Engine (response_models, fusion, retrieval, reranking, tracer, types, memory_engine), HTTP (http.py), MCP (both recall tools), control-plane proxy (recall/route.ts, lib/api.ts, search-debug-view.tsx). OpenAPI + Python/TS/Go/Rust clients + docs-skill mirror regenerated; recall.mdx + mcp-server.md updated.

Tests

tests/test_recall_min_score.py (9 tests): scores present, post-query final/reranker floors, retrieval-level semantic floor (SQL pruning), default None no-op. Fusion/scoring/trace suites pass (53). Lint + ty clean.

Notes for review

• Breaking response/request shape: score → scores.final, min_score → min_scores.final; retrieval-arm score fields are semantic + keyword. The old fields were unreleased, so no compatibility shim.
• Branch is currently a few commits behind main — will rebase before marking ready.

🤖 Draft generated with Claude Code.