Verdicts, methods and baselines

Every claimed-impact dollar TokenTriage renders is a typed value carrying a verdict, a method, a baseline and its exclusion counts. This page lists the closed vocabularies those fields draw from, and the rules that decide whether a figure may be sent at all.

Each vocabulary is closed in code: an unregistered value is rejected rather than sent as an unlabelled number. How to read a cost figure is the explanation these tables support.

The shape of an assessed figure

{
  "usd": 2.146137273,
  "estimated": false,
  "unpriced": false,
  "verdict": "ESTIMATED",
  "basis": {
    "method": "shadow-measured-delta-v1",
    "rows": 120,
    "window": { "since": "…", "until": "…", "tz": "UTC" }
  },
  "baseline": {
    "kind": "measured-current",
    "desc": "vs this slice's actual recorded spend over the window"
  },
  "unpriced_excluded": 0,
  "approximations": ["fixed_usage", "volume_extrapolation"]
}

Field	Meaning
`usd`	the amount, or `null` when the figure is `UNPROVABLE` or unpriced
`estimated`	the token counts or a rate behind it were approximated
`unpriced`	no dollar is being claimed
`verdict`	`PROVEN` · `ESTIMATED` · `UNPROVABLE`
`basis.method`	which registered method computed it
`basis.rows`	how many rows it was computed over
`basis.evidence_ref`	a link to the licensing evidence; required on `PROVEN`
`basis.reason`	what was missing; required on `UNPROVABLE`
`baseline.kind`	what it was compared against
`baseline.desc`	the registered fairness sentence for that kind
`unpriced_excluded`	rows left out because they could not be priced; always emitted, `0` is meaningful
`excluded_rows`	rows left out because they do not license this baseline
`disclosure`	the exclusion sentence, derived from the two counts above
`approximations`	every simulation step the method involves
`ci`	a confidence interval, when the method honestly computes one

The three verdicts

Verdict	What it means	What licenses it
`PROVEN`	measured on rows that actually ran	one of the two proven-capable methods, plus an evidence link
`ESTIMATED`	a model: recorded usage repriced under a different mechanism	any other method that met its bar
`UNPROVABLE`	the evidence for this slice is insufficient	any method, when its bar was not met

UNPROVABLE renders usd: null. That is enforced when the value is serialised rather than left to the caller, so a declined figure cannot leak a number even if something upstream set one.

The five rules a figure must satisfy

A figure that violates any of these fails to serialise and the request errors, rather than sending an unlabelled dollar.

Complete paperwork. The verdict, method, row count, baseline kind and baseline sentence are all required, and the method and baseline kind must both be registered.
PROVEN needs a link and a capable method. An evidence_ref pointing at the licensing evidence, and a method from the proven-capable set.
A refusal renders no number. UNPROVABLE requires an actionable reason and forces usd to null.
A simulation names its approximations. A method registered as simulation-derived carries its labels from the registry. A caller may add a label but cannot drop a mandatory one.
Zero is a statement. unpriced_excluded is always emitted, including when it is 0.

The methods

ProvenCapable answers one question: may a figure from this method be stamped PROVEN? Two of the twelve may. Simulation marks a method whose figures must carry approximation labels.

Method id	Proven-capable	Simulation	What it computes
`realized-counterfactual-v1`	yes	yes	on post-apply rows, what the prior choice would have cost minus what it did cost
`cache-licensed-replay-v1`	yes	no	replay-measured avoided spend on licensed exact-cache hits
`shadow-measured-delta-v1`	no	yes	measured per-row deltas on graded rows, extrapolated by slice volume
`cache-shadow-would-hit-v1`	no	yes	counterfactual avoided spend on rows that would have hit the cache
`evidence-scoped-v1`	no	yes	would-based savings arithmetic under the per-slice evidence verdict
`evidence-global-v1`	no	yes	the same, under the unscoped evidence verdict
`seasonal-quantile-v1`	no	no	same-hour-of-week medians with pooled relative-residual bands
`linear-burn-v1`	no	no	linear burn-rate extrapolation, the short-history fallback
`shadow-grade-wilson-v1`	no	no	graded shadow rows at the licensing bound — licenses quality, not impact
`mechanism-byte-identical-v1`	no	no	the served bytes are constructionally the incumbent’s — licenses quality
`quality-calibrated-delta-v1`	no	yes	delta between two calibrated quality estimates — licenses quality
`quality-reported-delta-v1`	no	no	delta between two unvalidated quality figures — licenses nothing

The last four answer is this change safe? rather than how many dollars?. They are in the same registry so a descriptor cannot name a method that does not exist, but none of them can ever license a PROVEN dollar, however strong the quality result.

The baselines

A savings figure cannot render without naming what it was measured against. The sentence is a constant of the kind rather than caller prose, so the same arithmetic cannot be labelled one way on one screen and another way elsewhere.

Kind	The sentence rendered next to the dollar
`requested-model`	vs what you asked for, at your recorded usage
`top-tier-would`	vs always serving the top tier — assumes clients request the top tier
`measured-current`	vs this slice’s actual recorded spend over the window
`prior-choice`	vs the tier that was serving this slice before the change, at your recorded usage
`projected-spend`	projected from your recorded traffic patterns; not a savings claim

top-tier-would is the basis behind the report command’s savings column, and its assumption is the one to watch: it is inflated for any client that already asks for a mid tier. projected-spend is the non-savings kind, used by forecasts.

The approximation labels

Label	What it discloses
`fixed_usage`	the counterfactual reprices recorded usage the other choice would not have generated verbatim
`volume_extrapolation`	measured deltas were projected over future volume
`cache_trajectory_modeled`	the projection was repriced under the cache-loss model
`operator_asserted_eligibility`	eligibility rests on an operator’s assertion, not a measurement
`fingerprint_approximated`	the population was identified by a fingerprint rather than exactly
`same_segment`	a quality delta is quoted over one named segment
`fixed_window`	a quality delta is quoted over one fixed window

fixed_usage appears on the PROVEN method too, and that is not an oversight. Measuring what the prior tier would have cost means pricing the tokens that were actually generated, and the prior tier would have generated different ones.

The guards

A guard blocks a recommendation whose saving would be bought at a cost the dollar does not show. Three are registered, and a descriptor may only declare one of these.

Guard	Blocks when
`cache-trajectory`	the routing change would destroy cache hits the saving depends on
`retry-inflation`	the cheaper tier’s retry rate would eat the saving
`truncation-rate`	the proposed output cap would truncate real completions

Guards block; they do not discount. A change that would degrade something measurable is withheld with the guard’s arithmetic quoted, rather than shown with a smaller number. A saving bought by cutting off one answer in seven is a different product, not a smaller saving.

A declared guard must also be evaluated. A guard with nothing to compare on a slice is run and passed with its emptiness recorded rather than skipped, because a skipped guard and a passing guard are indistinguishable on every surface.

Reading a guard result

{
  "name": "retry-inflation",
  "passed": true,
  "params": {
    "candidate_failure_rate": "0.0909",
    "incumbent_failure_rate": "0.1818",
    "labeled_rows": "11",
    "margin": "0.05"
  }
}

Every guard carries the parameters it decided on, so the decision is auditable without re-running the scan. A failing guard additionally carries a reason, and a guard that repriced rather than blocked carries the approximation label it contributed.