docs(adr): 0004 — Retriever contract (v1)

[EmersonBraun]

Summary

Fourth ADR of Phase 0 — formalizes the Retriever contract: a single, narrow interface that serves RAG, BM25, hybrid search, web search, code search, and conversational memory recall through composition, not per-variant types.

Builds on #267 (Adapter), #270 (Tool), #271 (Memory).

Merge order: #267 → #270 → #271 → #272 (each rebase on main as merged; conflicts only on the ADR README index).

Highlight invariants

• R1 Read-only — retrieval is observation, not transaction
• R2 query vs messages — focused string + surrounding context; retrievers ignore what they don't need
• R3 [] is success — empty results, not error
• R4 Errors throw — intentional asymmetry vs Adapter (chunks) / Tool (status). Retrievers are called once per turn; chunked errors would be ceremony.
• R6/R7 Optional but ordered scores — accommodates ranked + unranked backends without forcing fakes
• R10 No per-call options — config at construction; preserves substitutability for composers
• R11 Composition is transparent — composite retrievers satisfy R6/R7 even when fusing heterogeneous score scales

Key decision: indexing is NOT in the contract

RAG.ingest lives on the RAG type, not Retriever. This keeps Retriever substitutable across indexed (RAG over pgvector) and non-indexed (web search API) backends. Forcing an ingest method would either be a no-op for half the implementations or block them from satisfying the contract.

Trade-offs accepted

• No per-call topK/threshold — must hold multiple configured retriever instances if needed (rare)
• Score normalization is implementation burden for composite retrievers — known cost
• No streaming retrieval — most consumers want full ranked list before reasoning; can be added if real use case emerges

Unlocks

• [F2] #41 — Auto-summarization when context fills #154 RAG with reranking (composite Retriever)
• [F2] #42 — RAG with re-ranking and hybrid search #155 Hybrid search (BM25 + vector + reranker, all composed)
• [F3] #59 — Tools: web scraping and parsing #172 Web search as a tool — its execute holds a Retriever internally
• Long-term memory recall as a Retriever over chat memory (no new contract needed)
• Multi-source agents that mix vector RAG + web search + code search transparently

Test plan

• Doc renders on GitHub
• ADR index updated
• No code changes — pure documentation
• Reviewer: does narrow single-method contract hold up against your imagined retrievers?
• Reviewer: any case where R4 (throw, no sentinel) becomes painful?

Refs #214 #211