Model routing

The two invariants#

Both are asserted in code, not merely documented.

A human pin is final

If you set a model explicitly it is returned verbatim and the router is never consulted. A test proves it by replacing the router with a function that raises.

Difficulty may only raise the floor

Budget pressure makes easy work cheaper. It can never hand hard or retried work to a weaker model — that would trade completion for tokens. The router asserts this and falls back to the shipped default if it is ever violated.

How a model is chosen#

1. Free modeResolved before the router is consulted at all, so a run promised to cost nothing never even reads the catalogue.
2. A human pinReturned as-is.
3. The routerScores what is available now against capability, live price, provider health and measured outcomes.
4. The shipped defaultRouting may degrade. It may never fail.

Why price and quality are not in the catalogue#

The catalogue records what models exist and what each is capable of. It deliberately does not record what they cost or how good they are.

Price joins live from the pricing table, so a vendor changing its rates does not require a release. Quality is measured from outcomes rather than asserted — ship rate as a conservative lower bound, and median spend per task, shrunk toward a per-tier prior until there are enough observations to trust.