Cost optimization & savings verdicts — TokenTriage Docs

Cost analytics tells you where the money went; optimization tells you what’s safe to cut — and grades every claim. The defining rule is that a saving is never a bare number: it carries a verdict and a basis, or it is refused.

The recommendation engine

A detection loop scans on analytics.recommendations.interval and produces append-only artifacts. There are two kinds, and applying is always an explicit, per-action operator decision — there is no auto-apply, ever:

Actionable recommendations carry a config candidate. POST /recommendations/{id}/apply compiles → validates → diffs → writes it through the same config path a manual edit uses → audits it (returning the diff, the new generation, and an audit id).
Advisory recommendations carry a recipe, not a candidate (a change not expressible in config — e.g. a provider-side batch enrolment or a prompt restructure). Apply returns 422 by design.

The eight registered recommendation types are routing-downgrade, cache-opportunity, prompt-caching, provider-arbitrage, batch-eligibility, output-cap, reasoning-effort, and dedup. Each recommendation carries two separate verdicts — quality (did the cheaper alternative answer as well? — shadow grades, Wilson-bounded) and impact (how many dollars? — the savings verdict) — and they never blend. A degrading recommendation is BLOCKED with the guard named and its arithmetic quoted: guards block, they never discount.

Recommendations view: graded cards with an ESTIMATED savings chip, the method, and an evidence link. — Recommendations are graded — here an ESTIMATED cache saving with its method and evidence. A recommendation can never be PROVEN, and that is by design.

The three savings verdicts

The verdict vocabulary is closed. The three are different kinds of claim:

Verdict	Meaning	Licensed by
`PROVEN`	Measured on rows that actually happened after a change	a realized post-apply counterfactual only
`ESTIMATED`	A model — recorded usage repriced under a different mechanism	the query + projection methods
`UNPROVABLE`	The slice’s evidence is insufficient, with what was needed named	any method, when the bound isn’t met

Once a recommendation is applied, the Realized surface measures what it actually did — and deliberately offers no single delta between projected and measured, because they’re computed over different periods and baselines.

Realized view: what an applied recommendation actually did, versus its projection, shown as separate measured figures. — Realized-vs-projected — measured post-apply, the only path to a PROVEN dollar.

Provider-bill reconciliation

Import a provider invoice and match it against the ledger. The delta is decomposed into five named candidates — unproxied_traffic, window_mismatch, rounding, estimated_pricing, and unpriced_excluded:

Any applied model alias is disclosed with its line count and dollars moved, labeled “an operator assertion, not a measurement”; an alias onto a never-recorded model is flagged SUSPECT, and chained aliases are refused at tokentriage validate.

Reconcile view: an imported invoice matched to the ledger, with named delta candidates and an unexplained residual. — Reconcile — named explanations for the delta, and an 'unexplained' residual that is never zeroed away.

Forecasts

Forecasts are banded — a series point is a {p10, p50, p90} quantile triple, because a single line is unrepresentable. Month-end is actual-to-date plus the sum of the remaining point forecasts. Insufficiency is a state, not a guess: below four populated weeks the forecast says so and a labeled linear-burn fallback answers instead. A forecast can never be PROVEN (it’s always ESTIMATED), it covers priced spend only, and the unpriced row-count trend is disclosed beside it — never folded in at $0.

Chargeback & FOCUS exports

FOCUS (POST /tt/api/v1/cost-exports, kind: focus_cost — a companion focus_savings kind exports the verdict-bearing savings) emits FinOps-standard columns; an unpriced row’s EffectiveCost cell is empty with a reason, never 0, and the export re-aggregates nothing, so it agrees with the dashboard by construction. (Current build: the FOCUS export takes no filter and no row-level grain.)
Chargeback allocates per scope in showback (default) or chargeback mode, printed on the report header. Unallocated and unpriced rows are first-class rows, never silently redistributed, and every allocated dollar names the split rule that moved it (even / fixed(weights) / proportional(driver: cost|requests|tokens)). Every CSV export escapes formula injection.

Related: Cost analytics (attribution & rollups), Anomaly detection, and Caching (where cache savings are licensed by replay evidence).