Quality-aware routing

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 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 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

The first conjunct carries two distinct tokens: no_active_calibration means there is no active artifact at all, while artifact_not_active means an artifact was consulted and its lifecycle status is not active (it may exist only as a candidate). (A segment whose entry exists but is too thin surfaces its own insufficiency token — for example below_min_n — rather than segment_uncalibrated.) An artifact that failed its own measurement can be written to disk but can never clear 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. Routing on a point estimate is the overconfidence anti-pattern the whole substrate exists to refuse: the lower bound is what the evidence guarantees, and it is what the floor is compared against.

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.)

# 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:<reason> 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 honest 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 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 the whole substrate is built on.