Collection selection, and the config route the data model got wrong

[adamjohnwright]

The machinery for spec 009 collection routing. Behaviour is unchanged — nothing sets a selection yet, so every question still searches every collection. Wiring the classifier is the next task.

resolve_collections, with the asymmetry that matters

selection	result
empty or absent	all collections
every name known	just those, in bundle order
any name unknown	all collections, and a WARNING naming them

Every failure widens; none narrows. An unrecognised name means the classifier's prompt and the installed bundle disagree about what exists — narrowing on that disagreement drops a collection the question needed, while widening only costs latency. That is Principle IV, and it is why an empty list is the safe default for an omitted field, an older prompt and a parse failure alike.

The data model describes a route that does not exist

It sends the selection through RunnableConfig["configurable"]["collections"] into HybridRetriever.retrieve_documents. Measured against langchain-core 0.2.14, the pinned version:

• config is not passed to _get_relevant_documents as a kwarg — a retriever declared with **kwargs receives an empty dict
• var_child_runnable_config is unset inside a retriever run, so the ambient config cannot be read either

Two alternatives rejected: a per-request attribute on the retriever races, because it is built once at startup and shared by every request; rebuilding a filtered retriever per request throws away the constructed BM25 indexes.

So the selection travels in a ContextVar, which asyncio copies per task. That isolation is the entire justification, so it is pinned rather than assumed — a test runs a narrow request and a wide one concurrently and asserts neither sees the other's selection.

Recorded in research.md, with the data model's diagram left as the intent.

Characterization first

A test records today's behaviour — every collection searched, always — so that narrowing becomes a visible change rather than a silent one. If it starts failing without a selection being set, something narrowed retrieval by accident, which is the failure that costs answers rather than time.

12 tests. ruff, mypy (134 files), full suite with no API keys set.

🤖 Generated with Claude Code

[adamjohnwright]

Adversarial review

Three things checked, all on the real code rather than the fakes the unit tests use.

Does the ContextVar actually reach the retriever? This is the risk that would make the feature silently not work. LangChain may run a sync retriever in an executor, and loop.run_in_executor does not copy contextvars. Tested all three paths:

path	contextvar seen
sync-only retriever via ainvoke (executor)	✓
async retriever via ainvoke	✓
sync retriever via invoke	✓

Are the two edits correct? They were made programmatically on two functions and only exercised by a fake class. Read both: indentation correct, retrievers bound from the dict, loop over the chosen list.

Does the real HybridRetriever narrow? The decisive one:

selection	time	docs	collections searched
none	8.2s	50	all five
["reactions"]	2.5s	10	reactions only
["not_a_collection"]	6.7s	50	all five — widened correctly

The caveat that goes with those numbers

Narrowing drops the context from 50 documents to 10. The time saving is real and large, but fewer documents in context can cost answer quality, and that is precisely what this spec's before/after comparison exists to measure. I am not claiming routing is a win on the strength of a latency number.

The timings are one sample each. The collection sets and document counts are deterministic and are the part worth trusting; the seconds are directional only.

So the next task is not more plumbing — it is re-capturing against before.json and comparing recall, before anything sets a selection in production.