# Quality-aware routing
How a calibrated quality number changes a route — off the hot path, keyed on the served model, deciding candidacy rather than rank.
Source: https://tokentriage.com/docs/calibration/quality-aware-routing
---
import Callout from '../../../components/Callout.astro';
import NextSteps from '../../../components/NextSteps.astro';
import QualityRoutingSeamDiagram from '../../../components/QualityRoutingSeamDiagram.astro';
An active calibration only matters if it can change a decision. This page explains the seam where
it does: how a proven quality number becomes a routing constraint without ever touching the hot
path, why it keys on the model that was *served* rather than the one requested, and why the floor
it enforces gates a tier's **candidacy** — not its rank.
## Off the hot path
All of the licensing arithmetic runs **off the request path**. A background fold in
`internal/policyctx` applies the emission rule once per segment on its own cadence and publishes
an **immutable snapshot**. On the hot path the router does exactly **one map probe per
candidate** against that snapshot — no fitting, no statistics, no I/O. This is the same
[off-the-hot-path invariant](/docs/concepts/honesty-model#the-invariants) the rest of TokenTriage
holds: a stalled or unconfigured calibration cannot slow, block, or backpressure your traffic.
The feature is also **inert when unused**. With no calibration wired the dependency is nil, the
join is skipped, every quality fact is absent, and the decision context is byte-identical to a
build compiled before the feature existed. Opting in adds facts; it never rewrites the baseline.
## The subject key
A quality fact is filed under a four-coordinate segment key — the Mondrian coordinates
`{Metric, Tier, Model, Endpoint}`. One of those coordinates is subtle and load-bearing:
**The model coordinate is the model that was *served*, not the model that was requested.** Routing
rewrites the model, so keying a pass rate on the requested model would file the *cheap* tier's
outcomes under the *frontier's* name — and the router would then read the frontier's reputation
when deciding whether the cheap tier is safe. Keying on the served model is what makes the number
a fact about the tier that actually produced the output.
## The five licensing conjuncts
A segment licenses a claim only if **all five** conjuncts hold. Each is refused by a named,
closed token, so a consumer never has to parse prose to learn which one bit:
| Conjunct | Refusal token |
|---|---|
| An `active` artifact exists and is the one consulted | `no_active_calibration` / `artifact_not_active` |
| An entry exists for this segment and is fitted | `segment_uncalibrated` |
| That entry passed its B.5 gate | `gate_failed` |
| The policy epoch is current | `calibration_stale` |
| The fit is fresh (≤ 30 days) | `calibration_stale` |
Two of those tokens are easy to confuse. `no_active_calibration` means there is no active
artifact at all. `artifact_not_active` means an artifact *was* consulted and its lifecycle
status is not `active` — it may exist only as a candidate.
Two related cases: a segment whose entry exists but is too thin reports its own insufficiency
token (`below_min_n`, for example) rather than `segment_uncalibrated`. And an artifact that
failed its own measurement can be written to disk, but it never clears the third conjunct, so
it never serves.
## `min_quality_lcb` gates candidacy, not rank
When a policy sets a `min_quality_lcb` floor for a metric, the router reads the fitted segment's
**Clopper–Pearson lower confidence bound** — *not* the mean. A point estimate would let a
segment with thin evidence clear a floor it cannot support. The lower bound is what the
evidence guarantees, so that is what the floor is compared against.
The floor decides **candidacy, not rank**. A tier whose calibrated lower bound is below the floor
"is not a cheap option — it is not an option": it is removed from the candidate set entirely,
before any cost comparison runs. The floor never reorders the survivors; it only decides who
survives. (Only the binomial `GuaranteeLCB` bound is servable at this seam today — a conformal
predictive interval bounds a *request's own* future outcome, which does not exist before the
response.)
### A worked inversion
Suppose a policy sets `min_quality_lcb: 0.8` on `schema_validity` for a route with a frontier
tier and a cheaper `mid` tier. *(These figures are illustrative — yours depend on your own
traffic.)*
```yaml
# selector params (illustrative)
min_quality_lcb: 0.8
quality_metric: schema_validity
```
- The **cheap tier** has a fitted, gated segment whose Clopper–Pearson lower bound is ≈ `0.91`.
That clears `0.8`, so the cheap tier stays a candidate — and being cheaper, it wins.
- The **frontier tier** was never scored on this segment: its quality is **absent**, disclosed as
the score-table term `quality_absent:` and left as a candidate on the fail-open rule
(absence is disclosure, never a penalty).
- A **third tier** that *was* measured and came in at a lower bound of `0.72` is excluded, and its
disclosure term is `quality_below_min_lcb`.
`quality_absent` and `quality_below_min_lcb` are **different score-table terms on purpose** — "we
could not measure this tier" and "we measured it and it fell short" call for different operator
actions, and collapsing them would hide which one happened.
## Fail-open everywhere
Absence is never a penalty. A tier the router could not measure is disclosed and kept eligible,
not silently dropped — the safe failure direction. The floor only ever *removes* a candidate on
a **measured** bound that fell short, never on a missing one.
## The decision-log witness
When the router actually reads a candidate's quality, the decision row records it. A consulted
segment writes a `QualityConsult` and a `decision.predicted.*` block naming the metric, the tier,
the calibration version, and the fact that was read — so the route is auditable against the same
[decision ledger](/docs/concepts/core-concepts#the-decision-ledger) as every dollar. A
consulted-but-absent tier writes **no** predicted block; it shows up instead as the
`quality_absent` term in `decision.explain`. The row therefore distinguishes "we read a quality
fact and acted on it" from "we looked and there was nothing to read" — the same refuse-don't-guess
discipline calibration is built on.