# Verdicts, methods and baselines

The closed registries behind every claimed dollar: twelve methods, five baselines, seven approximation labels, and the five licensing rules.

Source: https://tokentriage.com/docs/build/cost-figure-reference

---
import Details from '../../../components/Details.astro';
import NextSteps from '../../../components/NextSteps.astro';

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](/docs/build/cost-figures) is the explanation these tables
support.

## The shape of an assessed figure

```json
{
  "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.

1. **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.
2. **`PROVEN` needs a link and a capable method.** An `evidence_ref` pointing at the licensing
   evidence, and a method from the proven-capable set.
3. **A refusal renders no number.** `UNPROVABLE` requires an actionable `reason` and forces
   `usd` to `null`.
4. **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.
5. **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.

<Details summary="Reading a guard result">

```json
{
  "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.

</Details>

<NextSteps items={[
  {title: "How to read a cost figure", href: "/docs/build/cost-figures", description: "The four questions to ask of any dollar, with a worked example you can check by hand."},
  {title: "The eight recommendation types", href: "/docs/build/cost-recommendation-types", description: "Which method and which guards each detector declares, and which two can be applied."},
  {title: "The honesty model", href: "/docs/concepts/honesty-model", description: "Where the verdict vocabulary is defined, and how it differs from the routing verdict."},
  { title: "Routing explanation fields", href: "/docs/build/routing-explanation-fields", description: "Read the fields that explain a routing decision and its cost baseline." },
]} />