feat(fts): 8d — hybrid retrieval worked example (BM25 + vector)

[joaoh82]

Summary

Fourth sub-phase of Phase 8. Self-contained Rust example showing how to compose bm25_score (8b) with vec_distance_cosine (Phase 7d) via raw arithmetic (Q8) for hybrid lexical + semantic retrieval.

No new engine code — the SQL composition works out of the box once 8b ships. This PR is a worked example + narrative.

cargo run --example hybrid-retrieval

What landed

• examples/hybrid-retrieval/hybrid_retrieval.rs — 6-doc tech-blurb corpus with hand-baked 4-dim embeddings (no embedding-model dependency). Runs three rankings on the same query: pure BM25, pure vector cosine, and 50/50 hybrid via:

  ORDER BY 0.5 * bm25_score(body, 'q')
         + 0.5 * (1.0 - vec_distance_cosine(embedding, [...]))
  DESC LIMIT k

  Vectors are picked by inspection so each query's expected ranking is obvious — the example stays reproducible forever, no flaky neural-net results.

• examples/hybrid-retrieval/README.md — narrative explanation:

  • When each ranking shape wins (table comparing BM25 / vector / hybrid trade-offs)
  • The cosine-distance-vs-similarity inversion gotcha (1.0 - vec_distance_cosine(...))
  • The WHERE fts_match pre-filter caveat (Q6 design choice)
  • Weight-tuning sketches (technical-doc bias, RAG bias, recency boost)
  • Production checklist (BM25 normalization, real embeddings, cross-encoder re-rank)

• Cargo.toml — registers the example.

• examples/README.md — top-level table picks up the new sample alongside the Rust quickstart.

Test plan

• cargo run --example hybrid-retrieval — produces the expected three rankings
• cargo build --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --all-targets — clean
• cargo test --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs — 303 / 303 engine + 73 across other crates green
• cargo fmt --all -- --check — no diff
• cargo clippy --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --all-targets — no new warnings on the example

Out of scope (later sub-phases)

Concern	Lands in
MCP bm25_search tool	8e
Docs sweep (docs/fts.md, docs/file-format.md, docs/supported-sql.md, …)	8f

🤖 Generated with Claude Code