6krrt/docs/routing.md

> Deep dive into routing internals. Back: [README](../README.md).

## Quality-First Selection

Seven hard filters are applied **before** scoring (not weighted — outright disqualification):

1. `effective_context_window ≥ required_context_tokens`
2. `tier ≥ required_tier` (from classifier)
3. Serving class compatible with request's `latency_tolerance`; `access_level` reachable
4. `tool_use_agentic` proficiency ≥ `routing.min_tool_proficiency`, **only when
   the request carries a `tools` array** (ships disabled — `null`)
5. `supports_vision = 1` when the request carries `image_url` parts; `NULL`
   fails closed (an unknown flag means the capability cannot be confirmed)
6. `supports_json_mode = 1` when `response_format.type` is `json_object` or
   `json_schema`; `NULL` also fails closed
7. `eligible_categories` restricts only when set: a row with a non-empty
   category list is admitted only when the task's category is in that list;
   `NULL`/absent means unrestricted (all cloud rows today)

Filters 4–6 are read from the request body rather than inferred. A `tools`
array states whether tool definitions are on the table, `image_url` parts state
whether vision is needed, and `response_format` states whether JSON mode is
needed. Local classifiers identified unambiguous tool-use prompts only 1-2
times in 6, so inferring capability requirements does not work; the request
states them exactly and for free.

The tool gate is a **quality measurement** filter: a model with no measured
`tool_use_agentic` score is admitted, because "unproven" is not "proven bad".
Only a measured score below `routing.min_tool_proficiency` is dropped. The
vision and JSON-mode gates are **capability flag** filters. There every
routable catalog row has `supports_tools = 1`, so a flag gate would be inert;
vision and JSON mode are not universal, and an absent or `NULL` flag means
"cannot confirm the capability", so the model is dropped. A wrong guess on a
capability flag is a guaranteed provider 400.

The tool filter ships **off** (`null`), because agent clients send `tools` on
nearly every request, so enabling it excludes the cheapest model from ordinary
agent traffic. Whether that trade is worth it is an empirical question best
settled with `POST /outcome` data rather than a 3-task benchmark score. Set it
to `0.5` to turn it on. The vision and JSON-mode gates ship **on**, because a
wrong guess is a guaranteed 400.

### Local Vision Fallback

Cloud vision is not universal in the catalog, and the most economical coding
rows do not declare `supports_vision`. Routing an image request through them
would earn a provider-side 400, so when `routing.require_vision` is true only
rows with `supports_vision = 1` survive the hard filters. If **no** cloud
candidate survives, the router can fall back to a local vision model instead
of returning 422.

`local_vision:` in `config/config.yaml` controls this path:

| Key | Default | Purpose |
|---|---|---|
| `enabled` | `true` | Whether the fallback runs at all |
| `base_url` | `http://localhost:11434/v1` | OpenAI-compatible Ollama endpoint |
| `api_key_env` | `null` | Env var holding an API key, if the endpoint needs one |
| `model` | `qwen3-vl:4b` | Vision model on that Ollama |
| `timeout_seconds` | `60` | Request timeout |
| `max_images` | `4` | Refuse requests with more image parts |
| `max_image_bytes` | `9437184` (9 MiB) | Refuse requests whose image payload exceeds this |

The fallback is **enabled by default** both in `config/config.yaml` and in
`LocalVisionConfig`, so omitting the section still turns it on. Disable it
explicitly (`enabled: false`) on a host with no local Ollama or one that has
not pulled the vision model.

When enabled and no cloud candidate is selected, `_run_local_vision` sends the
original message list — with `image_url` parts intact — to the configured
Ollama model. The local answer then **replaces** the cloud completion:
`_local_vision_response` returns a normal OpenAI-shaped response, including a
stream-wrapped version when the client asked for `stream: true`. It does *not*
inject a caption into a cloud call, because the streaming proxy cannot rewrite
bytes mid-stream.

Security and budget guards:
- **Only inline `data:` URIs are accepted.** A remote `http(s)` image URL is
  declined, because pointing a local model at an arbitrary URL would let an
  unauthenticated caller make the router fetch internal resources (SSRF).
- Image count and total payload size are bounded by `max_images` and
  `max_image_bytes` before the local call is made.
- If the local call fails for any reason, the request falls through to the
  ordinary `422 No model satisfies the hard filters` rather than returning a
  silent empty response.

Pull the model on whichever Ollama the fallback points at:

```bash
ollama pull qwen3-vl:4b
```

Config is strict (`extra="forbid"`): a misspelled or misplaced key fails at
load instead of being silently ignored.

### Local dispatch branch

Tasks in a local model's `eligible_categories` (for example `file_summarization`
and `diff_checking` for the shipped `qwen2.5-coder-router:14b`) survive the hard
filters the same way cloud rows do. Once selected, the request is sent to the
configured Ollama endpoint (`provider='ollama-local'`) instead of to
`dispatch_providers`. A local 502 trips the circuit breaker, so the next request
sees the local row as excluded and reroutes to a cloud candidate.

Local dispatch is **quality-gated and dormant under the default profile**.
The local row competes in the same ranking as every cloud row and must score
within `objective.quality_tolerance` of the category's cloud leader before its
price advantage is even consulted. Measured on 2026-09-02/03,
`qwen2.5-coder-router:14b` scores **0.767** on `file_summarization` against the
cloud leader's **0.95** — a 0.183 gap against a 0.10 tolerance — so under the
default profile the local row is dormant **by design**, today, until a local
model scores within tolerance. This is not a bug: quality is the objective,
and the local model has not yet earned the tiebreak (its 9.1x cost advantage
applies mainly to prompt tokens, so it wins most where large-context
summarization dominates — and it is assigned to summarization precisely
because it is not good enough at code).

Do NOT widen `objective.quality_tolerance` to fix this: the tolerance
describes measurement noise (bench sample sizes are small enough that a
smaller gap is genuinely indistinguishable), not preference. The project's
direction is named profiles (`auto:batch` is already one — a named widening
of the candidate set), and a `locality` profile is the right future home for
a per-category local preference, not a global tolerance change.

When every cloud candidate is exhausted, or the upstream returns an
account-level 4xx (any 4xx except 400/404/422 — those mean the request
itself is malformed and would fail locally too), an eligible routed
request degrades to the local dispatch model instead of surfacing the
cloud error. The trigger is deliberately conservative because the
upstream's exact credit-exhaustion signature is not yet observed
(full-body upstream-failure logging is in place to capture it); the
remaining cloud rows share one account, so no time is wasted walking
them after an account-level refusal. The fallback respects
`eligible_categories` even here: for everything else, the cloud error
fails loudly rather than handing a code task to a summarization-grade
model. The degraded answer is recorded as `kind='local_dispatch_fallback'`
in `route_decisions` so the proficiency loop never mistakes it for local
winning on merit, and if the local call itself fails the original cloud
error surfaces (the same fail-through contract as the local vision
fallback). There is no separate config knob — the fallback is armed
exactly by a `local_dispatch_models` entry listing the category in its
`eligible_categories`.

```
1. drop candidates whose measured energy exceeds objective.max_energy_per_request
2. rank by expected pass rate for the task's category (proficiency.blended_score)
3. treat differences smaller than objective.quality_tolerance as equal
4. among equals, pick the cheapest
5. on a small share of eligible requests, explore the least-evidenced candidate
```

| Setting | Value | Notes |
|---|---|---|
| `quality_tolerance` | 0.10 | % of real success rate, not an abstract quality unit: a candidate must beat the best by more than this to outrank a cheaper alternative |
| `assumed_cache_rate` | 0.917 | Share of prompt tokens served from the provider's prefix cache. Agent clients resend the conversation each turn, so most of it hits. Measured token-weighted over 40.7M tokens; measure your own against the provider's session view |
| `assumed_completion_tokens` | 500 | Completion length assumed when pricing a candidate |
| `max_energy_per_request` | null | Per-request kWh ceiling — a wall, not a bill. Null disables it |
| `plan_kwh_per_period` | 6.25 | **Set this to your own plan's quota.** Reported in `/health` as burn against the allowance; it does not gate anything |

This replaced a weighted blend (cost 0.4 / eco 0.2 / proficiency 0.4).
Measurement retired it: turning the cost weight from 0.4 to **zero** changed
the winner in only 2 of 6 categories, so the blend was never steering on
quality — while 60% of every decision adjudicated fractions of a cent.

### What the proficiency score means now

`proficiency.blended_score` is an **expected pass rate on your traffic**, not a
raw benchmark quality level. The benchmark (leaderboard + self-eval) provides a
prior. Client-reported outcomes from `POST /outcome` provide the per-model
signal. The two are combined through empirical-Bayes shrinkage:

- A category with no outcome traffic keeps the benchmark score verbatim.
- A trafficked category row with no own outcomes inherits a peer prior.
- A row with its own outcomes blends the observed rate with that prior;
  `outcome_prior_strength` (default 20 pseudo-observations) pulls thin data
toward the category mean so one lucky sample cannot dominate.

So `quality_tolerance` asks "is this candidate's expected real success rate at
least 10% better than the cheaper one?" If not, cost breaks the tie. The score
is calibrated against the same client reports that `feedback.py` folds in, so
routing learns from traffic rather than from the benchmark alone.

**Cost is priced per request, from catalog token prices scaled to the
request's shape** — prompt size, `assumed_completion_tokens`,
`assumed_cache_rate`. It is deliberately *not* a benchmark average.

Neuralwatt bills flat per-kWh rather than per-token, so list price is not what
gets charged. Scoring used measured billed cost from a fixed 400-token
reference sweep for exactly that reason — and that was wrong for real traffic,
because the ranking depends on the workload's *shape*, not just the model. On
a 400-token prompt one model looked 3.2× cheaper than another; on a realistic
70k-token prompt the same pair inverted and the second was 5.0× cheaper. The
provider's attribution ratio moves with prompt size, so a fixed-shape
benchmark cannot rank models for a workload of a different shape.

List price is still not what is billed, but billing is capped at a multiple of
it, so it tracks the real ordering and bounds it — and it is free, needs no
sweep, and refreshes whenever the poller runs.

**Why cost ≠ eco:** Cost tracks energy (kWh), but carbon is energy × grid
intensity. Grid intensity spanned ~49 gCO2/kWh (`FI`) to ~442
(`US-MIDA-PJM`) when measured — and it moves with time of day. The models
disagree: `glm-5.2-fast` is
2nd cheapest but 6th cleanest; `kimi-k3-flex` draws 3.7× less energy than
`kimi-k2.7-code` while emitting 3.6× more carbon. Collapsing them picks a
side.

### Exploration

Routing runs an epsilon-greedy exploration pass after ranking. If enabled
(`exploration.enabled: true`, default), a random share `ε = 0.03` of eligible
requests replaces the winner with the hard-filter-eligible candidate that has
the fewest `outcome_samples`, tie-broken by lowest cost. The alternative is
skipped if its cost exceeds `max_cost_ratio ×` the winner's cost (default 4×).
Only tier 1 and tier 2 requests explore (`max_tier: 2`); tier 3 stays
exploitative so frontier work gets the best expected rate.

`was_exploration` is persisted to `route_decisions.exploration` so metrics can
tell real preference from forced discovery. This is the mechanism that breaks
the exposure-bias loop: without it, the router would send most requests to the
models already richest in outcome samples and the least-sampled rows would
never catch up.

### Incumbency and cache pricing

The ranking above treats every candidate as if its prompt were fresh. On a real
session it is not: the provider caches the conversation prefix, so the model
that served the last turn re-serves it with most of its prompt tokens billed at
the cached rate, while a different model pays full price for the entire prefix
on its first turn. `assumed_cache_rate` already prices that discount uniformly
for every row. Incumbency pricing makes it per-row: the incumbent keeps its
measured cache rate, challengers are priced toward cold, and a challenger now
has to beat the incumbent by more than the cache it is about to discard, which
on a long prompt is most of the prompt. This is the first place the
router's own past decision feeds back into its cost model, and it is
deliberately narrow: it changes only the cost key, never the sort.

The incumbent is **per conversation** when the client sends
`X-Router-Conversation`: `session_key` is then the namespaced conversation id,
so each conversation tracks its own incumbent. Without that header the
incumbent is per system-prompt fingerprint, and the fingerprint's hashing
merges concurrent same-prompt agents into one incumbent so they share the
cache discount.

Four knobs under `objective:`, all shipping **off**
(`incumbent_cache_pricing: false`, dial `null`; enable only after the Wave 1
post-restart baseline day, the Wave 2 gate in `plans/token-waste-waves.md`):

| Knob | Default | Purpose |
|---|---|---|
| `incumbent_cache_pricing` | `false` | The gate; off means byte-identical ranking (pinned by test) |
| `incumbent_challenger_cache_rate` | `null` | The challenger dial: `null` follows `assumed_cache_rate`; `0.0` is fully cold; between is a partial penalty |
| `incumbent_rate_refresh_seconds` | `300` | TTL on the measured per-(provider, model) rate table |
| `incumbent_rate_min_observations` | `25` | Observations before a measured rate is trusted **for pricing**; independent of the warning floor |

**What the incumbent is.** The model that served the session's last chat turn,
read back from `route_decisions` by `_session_incumbent_lookup` in
`dispatcher.py`: the most recent row for the session key with a selected model.
The query is an allowlist (`kind IN ('chat')`, never a `!=` denylist), so a
one-request `model` pin (passthrough), a `local_dispatch_fallback` row, or a
`route` probe can never set the incumbent, and neither can any future `kind`
until it argues its way in. The reason is that incumbency is a statement about
*preference*: this session, with its own history, chose that model
repeatedly on merit. A single pinned request says nothing about the session
and a degraded fallback is the opposite of a preference; letting either become
sticky would convert an escape hatch into a rut.

**The rate ladder.** When the feature is on and an incumbent is present, the
incumbent is priced at its measured per-(provider, model) cache rate whenever
that series has at least `incumbent_rate_min_observations` observations
(default 25); below that trust threshold it falls back to `assumed_cache_rate`.
The rates come from `metrics.cache_rate_series` through
`_measured_cache_rates()` in `dispatcher.py`, cached for
`incumbent_rate_refresh_seconds` (the TTL runs on `time.monotonic()` from the
first call after process start, so a brief post-restart cold period is
expected). The pricing floor is deliberately a different knob from the
alerting floor `cache_rate_warn_min_observations`: pricing would rather fall
back to the assumed rate on thin data than steer money on a thin measurement,
alerting wants the opposite trade, and coupling the two would couple operator
intents that should stay separate. Any failure in the measured-rate path fails
open to an empty table and every row prices at `assumed_cache_rate`;
incumbency pricing must never block routing.

**The challenger dial.** `objective.incumbent_challenger_cache_rate` is the
rate every non-incumbent row is priced at. Neutral is decided by **semantic
equality**, not identity: `null` follows `assumed_cache_rate`, and any dial
equal to `assumed_cache_rate` is the same neutral, so at a neutral setting
every row *including the incumbent* prices at `assumed_cache_rate` and the
ranking is byte-identical to today's, even with the flag on (config resolves
`null` to a concrete float at load; downstream code never sees both
representations). `0.0` prices challengers as fully cold prompts, the maximum
incumbent advantage; any value between is a partial cache penalty. The whole
feature tunes from off to full by moving this one config value, never by a
revert: if the switch gap does not narrow, the move is toward cold, then
re-measure.

**The clamp, and why it is load-bearing.** The challenger rate is
`min(dial, incumbent_rate)`, and the invariant it buys is: **the incumbent's
cache rate is always >= every challenger's cache rate.** Without it, the dial
is denominated in an absolute cache rate, so any dial above the incumbent's
measured rate prices the challenger as having a *better* cache than the
incumbent: the feature inverts and penalises the incumbent for being the
incumbent. Because several routed models measure below the assumed rate (a
model measured at ~0.73 against an assumed 0.917, for instance), that inverted
zone is not a corner case: for such a model it spans essentially the whole walk
from neutral down toward full penalty, which is exactly the range an operator
is told to tune through, and from inside it the counterfactual report looks
like "the penalty does not pay here" when in fact the penalty is running
backwards. Do not remove the clamp as redundant. An alternative dial
denominated as a relative penalty (`incumbent_rate * (1 - penalty)`) cannot
invert by construction and was deliberately deferred rather than adopted (see
the wave's second review, `wave2-review-2.md`); until that redesign exists,
the clamp is what makes the absolute form safe, and a property test pins it:
for every dial and every measured rate, the incumbent's priced rate is >=
every challenger's.

**How it composes.** Cache pricing happens inside `estimated_cost`: the
ranking loop simply passes each row a different `cache_rate` argument, so
every consumer of cost, from the band tiebreak to `cost_score` to the
flex-twin swap (a distinct serving endpoint, so it prices as a challenger at
the same dial), sees one coherent number per row. `provider_cost_multipliers`
composes multiplicatively on top of the cache-adjusted estimate, exactly as
before: it inflates the comparison cost inside the quality-band tiebreak and
can never override a genuine quality gap, because the quality band is
computed before the cost key and the incumbent gets no quality advantage. A
model that is genuinely better still wins outright.

**Eviction.** The incumbent is a pricing fact, not a reservation.
`_resolve_incumbent` re-runs the incumbent's catalog row through
`rejection_reason` with this request's actual filters and checks the profile's
`restrict_to`: if a hard filter would drop it (the session outgrew its
context window, a profile switch restricts the candidate set, a circuit is
open), it simply loses incumbency for that turn, no error, and the turn prices
exactly as it did before the feature: every row at `assumed_cache_rate`.

**Exploration becomes session-scoped.** The coin described above now flips
only when no incumbent is present: `route()` adds `incumbent is None` to the
exploration condition, and `exploration.py` itself is unchanged (injected RNG,
no mutable state, per its module contract). The coin flips at session start
only, so one exploratory session costs one cold prompt instead of one per
turn; incumbency pricing then pins the explored model for the session's
remaining turns, which is tiebreak protection without new state. Re-exploring
per turn with an incumbent present would dump the cache every few turns, the
exact leak the feature exists to stop (`plans/token-waste-waves.md` item 2.3).

**Expiry checks.** Both premises carry their own. The `assumed_cache_rate`
fallback is checked by `cache_rate_warnings` in `/metrics`, which compares the
measured aggregate and per-(provider, model) rates against the assumed
constant and warns beyond `cache_rate_warn_margin`. A deployment whose real
rate has diverged is mispriced, not broken, and the fix is to re-measure. The
dial's own premise, "the penalty is paying," is evaluated offline rather than
assumed: `baseline_report.py --incumbent-challenger <rate>` replays recent
`route_decisions` against a cold-challenger ranking and reports what the
penalty changed and what other dial settings would have changed, and the
operator re-measures the same-model/switched cache-rate gap and billed µ$ per
prompt token each re-measurement window after enabling. When the penalty
stops paying, the named move is toward neutral on the dial. No hardcoded
expiry duration: the check is the measurement.

**Shipping state.** Off, as shipped: behavior is byte-identical to
pre-feature traffic (pinned by test). When on, every switch decision is
explainable post-hoc: the rank debug log carries the incumbent identity, its
rate and source (measured or assumed), and the dial; the incumbent row itself
carries an `incumbent_pricing` stamp in the ranked output.

### What routing actually returns, and why it moves

Sweeping `/route` across every category and tier is the fastest way to see
whether your data is doing anything. On the deployment this was written
against, 9 categories × 3 tiers currently yields **5 distinct winners**
(`qwen3.6-35b`, `gemma-4-31b`, `deepseek-v4-flash`, `kimi-k3`,
`kimi-k3-fast`).

That number is a diagnostic, not a target, and it is worth knowing what each
outcome means:

- **One winner everywhere** is a legitimate answer, not a misconfiguration.
  It happened here: with cost, eco and proficiency all populated, one model
  was Pareto-dominant — cheapest *and* cleanest in the routable set while
  scoring within `quality_tolerance` of the best. No defensible weighting
  picks anything else. If you see this, check whether the leader really is
  dominant before reaching for the config.
- **Winners that change with context size** are the hard filters working.
  A model is dropped once `required_context_tokens` exceeds its window, so a
  long session can change model mid-conversation. Past the largest window,
  `/v1/chat/completions` returns 422 naming the constraint rather than
  silently truncating.
- **Winners that change by category** mean proficiency is live. That is the
  only category-dependent term, so until the `proficiency` table has data,
  `task_category` cannot change a decision at all — the classifier computes
  it and the router pays for it for nothing. The score is now
  outcome-calibrated, so category-level client reports are the fastest way to
  shift these choices.

The spread here widened for two reasons worth copying: cost became a
per-request estimate rather than a benchmark average, and tier stopped being
inferred from price alone. Both had been quietly excluding a cheap
large-context model from every request above tier 1. Outcome samples are now
arriving too; `deepseek-v4-flash` gained substantial samples in
`coding_general`, `coding_refactor`, and `general_chat` from post-stream
`POST /outcome` reports.

If you want a different balance, the levers are `objective.quality_tolerance`
(how big a quality gap must be before it outranks cost) and
`objective.max_energy_per_request` (a hard ceiling). There is no weight to
tune — quality is the objective and cost is the tiebreak, which replaced an
earlier weighted blend.

### Circuit Breaker — `circuit_breaker.py`

A seventh, dynamic filter sits alongside the six hard filters above: a model
that 5xx'd recently is passively excluded from the candidate set. On by
default (`circuit_breaker.enabled: true`).

It records nothing until a model actually fails — a 5xx from the upstream
call marks `(model_id, provider)` down for `initial_cooldown_seconds` (30s
default), doubling on each further failure (`backoff_multiplier`, capped at
`max_cooldown_seconds`, 600s) and clearing on the next success. Recovery is
**passive by design** — no background poller, no health-check loop. The next
real request that would have picked the down model becomes its own recovery
probe once the cooldown has passed.

Two call sites: candidate selection excludes down models outright, and the
dispatch retry loop (see the retry budget in [verification.md](verification.md))
records the failure/success on every upstream call and fails over to the
next-ranked candidate on a 5xx — but only for `auto`-routed requests, since a
pinned request has no alternative to fail over to.

`eval_proficiency.py` deliberately calls providers directly, bypassing both
the circuit breaker and the retry loop — a transient eval-harness failure
against one model's edges shouldn't be able to trip the breaker against real
production traffic.

### The classifier's own circuit breaker

Separate machinery, same idea, different table: `circuit_breaker.py` guards
*upstream models*, while `_last_classifier_failure` in `dispatcher.py` guards
the **local classifier** — the one blocking LLM call on the request path.

For its first release that timestamp was written by `_record_failure()` and
read by nothing: `_classify_cascade` gated only its *cloud* step, and on a
different timestamp (`_last_account_refusal`). So the router re-dialled a
known-dead local classifier on every request. A *stopped* Ollama refuses the
connection immediately and costs little; a **hung** one — or a VPN-bound one
that black-holes — costs the full `classifier.timeout_seconds`, 120s on this
deployment, per request for as long as the outage lasts.

`_classifier_backoff_active()` is the read, consulted in `classify()`
**before** `_classifier_client()` is constructed, because constructing it and
waiting out the timeout is the expensive part.

One detail is load-bearing and easy to undo by accident: recording the failure
lives in `_classify_via_local_llm`'s own exception handlers, **not** in
`_classify_cascade`. The cascade is walked for reasons other than a fresh
failure — a skipped attempt inside an already-open window, or gaming mode —
and if those re-stamped the clock then every request during an outage would
push the deadline forward and the local classifier would never be re-probed
while traffic flowed. That is a permanent outage wearing a circuit breaker's
clothes. `tests/test_classifier_backoff.py` pins it directly, and asserts on
whether the client was *constructed* rather than on the value returned — a
test that only checked the result would pass even if the router had waited
out the timeout first.

A skip and a real failure both reach the classifier's fallback cascade, but
they are logically distinct and `dispatcher.py` keeps them that way: a skip
raises `_ClassifierSkipped` (logged once, specifically, as
`classify_local_skipped`) while a real failure raises the underlying
exception (logged as `fallback`). Conflating the two would tell an operator
reading raw logs that the local classifier is failing when gaming mode simply
turned it off.

### Which classifier is PRIMARY — `classifier.mode`

Separate machinery from the circuit breaker above: that guards *upstream
dispatch models* once a category has already been classified. This guards
*which implementation does the classifying in the first place*.

`classifier.mode` (`local_llm` default, `cloud_llm`, `local_encoder`) picks
the primary attempt. It is a peer to the classifier's own fallback cascade
(local → stale session cache → session history → optional `cloud_fallback`
→ static guess), not a replacement for it — whichever mode is primary, a
failure in `_classify_via_configured_mode` still funnels into the exact
same, unmodified cascade in `dispatcher.py`.

Two things are load-bearing here and easy to get backwards in a future edit:

- **`cloud_llm` success records `source="classifier"`, not
  `"classifier_cloud"`.** The latter string means specifically "the
  cascade's post-failure backup step fired," and both the `/metrics`
  degradation-share warning and the outcome-attribution set read it as a
  *degraded* signal. An intentionally configured cloud primary succeeding
  is the opposite of degraded, so reusing `"classifier_cloud"` for it would
  make healthy, on-purpose traffic look like an ongoing local outage.
- **`cloud_primary_auto` resolves live, cached, not per-request.**
  `routing.cheapest_classifier_candidate` reuses `select_candidates` +
  `estimated_cost` — the same functions real dispatch ranking uses — priced
  for the classifier's own short-prompt/short-completion call shape rather
  than the task's. `dispatcher._resolve_auto_classifier` caches the result
  for `classifier.cooldown_seconds` so this does not add a DB scan to every
  request's latency floor; the admin portal's GET endpoint calls the
  resolver fresh on every load instead, since a human loading a settings
  page is not on that latency floor and a stale "live" reading would be
  exactly the kind of bug the profiles page's zero-admit badge was.

`local_encoder` mode only ever produces `task_category` — `task_tier` falls
back to `classifier.fallback_tier`, a documented limitation rather than a
second heuristic. See [local-models.md](local-models.md) for why zero-shot
rather than fine-tuned (this router never stores raw task text).

### Checking whether scoring earns its complexity

`baseline_report.py` automates the "check whether the leader really is
dominant" step above: it replays recent `route_decisions` against two trivial
counterfactuals (always cheapest, always highest proficiency) using the
*current* catalog and proficiency table, and reports how often real scoring
picked something a trivial baseline wouldn't have.

```bash
PYTHONPATH=src python -m baseline_report --since 2026-08-01
PYTHONPATH=src python -m baseline_report --since 2026-08-01 --category coding_refactor --csv
```

A high dominance share paired with a near-zero proficiency delta against
`always_cheapest` means the quality-first ranking isn't earning its complexity
for that slice of traffic. Read-only — adds no schema, spends no quota.

### Tiering

Tier on `reasoning_default_enabled` (from `metadata.reasoning.default_enabled`,
falling back to `capabilities.reasoning`), **not** `supports_reasoning`.
`capabilities.reasoning` only means "the endpoint accepts a reasoning
param" — it is true for 17 of 19 rows, and tiering on it put 17 models in
tier 3 and left tier 1 empty. A `-fast` row does not inherit its sibling's
tier 3. Cost is checked before the reasoning rule so $0.28/1M models can
reach tier 1.

**Cheapness is not a capability ceiling** (`tier1_context_max`, default
512000). Tier is a *floor* — `routing.py` drops any row with
`tier < required_tier` — so tier 1 means "simple work only", not "cheap".
Deciding that on price alone put `deepseek-v4-flash` in tier 1 for no reason
but its $0.28/1M completion price, which excluded it **outright** from every
tier-2 request. It has a 1M advertised window and scores 1.00 on all three
coding categories. That was the same substitution the cost axis already had
to unlearn: price is a market signal, not a capability measurement.

Tier 1 now requires the model to be small **and** cheap. The gate reads the
**advertised** `context_window`, whose catalog values are the clean market
classes — 131056 / 199984 / 262128 / 1048560 — rather than
`effective_context_window`, which varies within a class. 512000 sits in the
empty band between the 256K and 1M classes with a 2x margin either side, so it
is not fitted to any one model. The gate only ever demotes; a huge window
never promotes an expensive model into tier 1, and a *missing* window does not
block it, since absent evidence should not decide anything.

Distribution moved **4 / 6 / 9 -> 1 / 9 / 9** — only the three deepseek rows
changed. With cost priced per-request, `deepseek-v4-flash` now wins
`coding_general` at every context size (16.5x cheaper than `kimi-k3` at 200k)
and is still correctly absent from `tool_use_agentic`, where its measured 0.33
drops it out of the quality band. That is the eval data earning it the slot
rather than a thumb on the scale — no `model_tiers` override was needed.

### Why tools and reasoning stay on their existing signals

Tools stay on the measured `tool_use_agentic` proficiency gate, not a
`supports_tools` flag gate. Every routable catalog row already has
`supports_tools = 1`, so a flag gate would be inert. The real signal is the
measured proficiency, because the observed failure is a model over-reaching for
tools on a non-agentic prompt. `routing.min_tool_proficiency` captures that
measurement and only applies when the request carries a `tools` array.

Reasoning stays on tiering (`reasoning_default_enabled`), not on a new flag gate.
`supports_reasoning` only means the endpoint accepts a reasoning parameter, and
that is true for 17 of 19 rows — nearly the whole catalog. `has_reasoning_request`
is detected purely for observation. Making it a gate would add no useful
filtering, because the decision of whether a request needs reasoning is already
encoded in the requested tier.

The fail-closed asymmetry, stated plainly: **capability flags fail closed on
unknown; quality measurements admit on absent evidence.** A missing
`supports_vision` or `supports_json_mode` flag means "cannot confirm", so the
model is dropped. A missing `tool_use_agentic` score or energy measurement means
"unproven, not bad", so the model is admitted. The first wrong guess is a
guaranteed 400; the second is just an empty data point that the neutral default
handles.

### The classifier's labels are not the proficiency scoring axis

`classifier.candidate_categories` is the set of labels a classifier may
return. `proficiency.categories` is the axis models are scored on. They were
one list, and the two jobs are not the same job: the axis answers "what is
this model good at", the candidate set answers "what should a classifier be
asked to distinguish". Config load validates the candidate set as a **subset**
of the axis — a label outside it joins against nothing in the `proficiency`
table, so routing would rank on NULLs, which is the same phantom-join failure
`routing.tool_use_category` is validated against, arriving from the other
side. Omitting the key means "every category", i.e. the pre-split behaviour.

Both classifier backends read the candidate set: `dispatcher.classify` builds
its allowed-values prompt from it, and `local_encoder.classify_zero_shot`
receives it as its candidate labels. `_classify_once` also validates the
returned label against it, so the exclusion is binding rather than advisory —
a local model that ignores the prompt's list is corrected, exactly as an
invented label always was. The scoring-axis consumers were deliberately left
on the full list: `leaderboard.py` (priors are per scoring category),
`eval_proficiency.py` (the benchmark still evaluates every category),
`admin.py`'s profile-coverage count and `/metrics`' category list (both
describe the scoring axis), and `config.py`'s `tool_use_category` /
`eligible_categories` validators.

**`tool_use_agentic` is the excluded category, and why is the point.** It
describes what a turn mechanically *does* rather than what it is *for*, and
every agent turn does it. Measured 2026-09-14 on live traffic with the session
cache off so every turn classified for real: **31 of 31 consecutive turns**
classified `tool_use_agentic`, all carrying `tools`, all routed to
`z-ai/glm-5.3-flash` — 14.8s time-to-first-token, p95 40s, the slowest model in
the catalog. Per-turn classification became accurate and routing got worse.
Classifying *for* tool use also duplicates a signal the router already has
exactly: the request carries a `tools` array, reading it is free, and
`routing.min_tool_proficiency` is the mechanism that acts on it.

**What the exclusion costs, written down so the next person does not have to
rediscover it:** no new `POST /outcome` report can attribute to
`tool_use_agentic`, because nothing classifies as it any more. Those scores
**freeze** at their current values (`qwen3.6-35b` at 0.902 over 154 samples).
The tool filter keeps reading them and the category keeps ranking; it simply
stops accumulating. That is accepted for now, not fixed.

**Considered and rejected:** attributing outcomes to `tool_use_agentic`
whenever the request carried a `tools` array. opencode sends `tools` on
essentially every request, so the score would converge on each model's overall
pass rate and stop discriminating the one thing the category exists to
detect — a model that *over-reaches* for tools on work that did not need them
(`deepseek-v4-flash` calling two tools to subtract 1:20pm from 3pm). A frozen
honest score beats a live meaningless one.

The readout is on the admin portal's Classifier card: the candidate list, and
the excluded categories with a note that they stop accumulating outcomes.
Read-only on purpose — it is a structural list in the same class as
`proficiency.categories` and `models.eligible_categories`, neither of which
has an editing surface, and what an operator needs from the portal is the
answer to "why does nothing ever classify as X".