How would-have-saved is measured

This page explains the "would-have-saved" figure on the dashboard counterfactual tile, served by GET /platform/v1/counterfactual.

What it is

A simulation over your own traffic. We reduce each observed request to a one-way fingerprint, replay those fingerprints through two lever simulators (a byte-identical exact cache, and in-flight coalescing), sum the metered cost of the requests those levers would have avoided, and discount the total by a published quality haircut. Nothing is applied to your traffic to produce it. Every payload carries basis: measured and applied: false.

How it is computed

Money is integer micro-USD (MicroUsd(i64); 1,000,000 µUSD = $1.00). No floats exist on this path.

Fingerprint. Recipe rcv-fp-v1: SHA-256 over the length-framed version tag, workspace id, provider tag (open_ai or anthropic), method, and route, then the raw body bytes. Framing writes each field's byte length as an 8-byte little-endian integer before the field, so ab + c and a + bc cannot collide. Headers are not hashed. Observe-mode hashing stops at 1,048,576 bytes; longer bodies are marked truncated and cannot match. Matching is keyed on (workspace id, fingerprint), so identical bytes from another workspace never match.
Cost. From the meter: each tokens x micro-USD-per-million-tokens product is summed in i128 and floor-divided by 1,000,000 exactly once, against a frozen price list version pinned on the receipt. Unreported usage is null, never estimated.
Exact cache. Replay in start order. A hit needs a stored entry for the same identity with 0 <= start_ms - stored_ms < ttl_ms. Exactly at the TTL is a miss. A record older than the entry is a miss and leaves state untouched. Hits never refresh; every miss stores or re-stores at its own start. The saving is the repeat's own cost, not the original's.
Dedup. The burst's first request is the leader, window [started_at, finished_at). A later identical record hits if start_ms < leader_finish_ms. Followers never extend the window. Starting exactly at the finish is a miss and becomes the new leader. The saving is the coalesced request's own cost.
Totals and haircut. events counts hits; known_cost_events counts hits with a reported cost and only those sum into gross; unknown_cost_events counts the rest and is never turned into money. Then net = floor(gross * retained_ppm / 1,000,000), integer, floored toward zero. retained_ppm cannot exceed 1,000,000, so a haircut only reduces. Results pin the factor version and this page. Versions are append-only.
Sufficiency. Nothing numeric renders below 1,000 metered requests and 25,000,000 µUSD ($25.00) period spend. Both, not either. Otherwise the response is {"sufficient": false} and nothing else.

Worked example

One workspace, one period, cache TTL 300 seconds.

#	fp	start ms	finish ms	cost µUSD	outcome
1	A	0	40	12,417	miss; stores A at 0
2	A	60,000	60,050	12,417	hit, +12,417
3	A	200,000	200,060	12,930	hit, +12,930
4	A	400,000	400,050	12,417	miss (not < 300,000); re-stores
5	A	450,000	450,050	null	hit; counted, never priced
6	B	1,000	1,900	11,000	leader; no saving
7	B	1,400	2,600	15,750	hit, +15,750
8	B	1,899	2,100	9,004	hit, +9,004
9	B	1,900	2,800	9,000	miss (1,900 not < 1,900)

events 5, known_cost_events 4, unknown_cost_events 1.

gross = 12,417 + 12,930 + 15,750 + 9,004 = 50,101 µUSD.

At 850,000 retained ppm: 50,101 x 850,000 = 42,585,850,000, divided by 1,000,000 is 42,585.85, floored to net = 42,585 µUSD, displayed $0.04. That ppm is illustrative; see below. This period still renders nothing, because 5 requests is under 1,000.

What it does not include

Provider-side prompt caching. Reported cached_tokens are already inside the metered cost. That is the provider's saving, not ours.
Model routing. No routing lever exists; realizedModel equals baselineModel on every receipt we have written.
Near-miss or semantic matching, cross-workspace reuse, unpriced hits, and bodies past 1,048,576 bytes.
Lever eligibility. The simulation does not test non-streamed, single-choice, temperature-0 shape; the dedup lever, where enabled, does. The simulated dedup figure is an upper bound on what a lever could coalesce where enabled.
Retry and failure economics (that is cost per successful output), your subscription, provider committed-spend discounts, and taxes.

Limits and current status

Counterfactual: measured, never applied. Levers are not activated in any deployed environment. RECOVEA_SAVINGS_LIVE is unset everywhere, so every lever caps at shadow.
The measurement is not running in production either. The fingerprint tee is attached only in tests, so the deployed gateway emits no fingerprint records, and the control plane still serves the in-memory counterfactual store, which returns zeros. The endpoint answers {"sufficient": false} for every workspace today, whatever its traffic. The simulators, haircut, and sufficiency gate are shipped and property-tested, but not connected to real traffic.
No haircut factor is published. The registry is empty in every deployed environment. A real factor will appear here, with its version id, first.
Budgets. Only workspace-scoped caps reach the gateway (scope_kind = 'workspace'). Key- and project-scoped budgets store but are not enforced on the data plane yet.
Alerts. The sweep runs about once a minute, so a fast burst can cross a threshold and reach a cap between checks. Alerts warn on the way up; they are not an ordering guarantee.
CPSO. Served figures are live at list price. Period-close reconciliation against provider invoices exists as worker code and fixtures, unwired and unscheduled.
Score. The engine is not shipped. No workspace has a score today.
Spend and attribution, known drift. Three contracts have two implementations each. The sufficiency threshold is defined in both the optimizer crate and the platform's counterfactual store, and the endpoint uses the platform copy; the values agree today, and nothing enforces that. The platform's ledger export is a local mirror of the shared ledger serializer, with a standing TODO to swap it. The optimizer's own doc comment describes the fingerprint as covering a sorted header subset, which the shipped rcv-fp-v1 does not; the implementation is authoritative and is what this page describes.

Where to check us

Read the integer. The endpoint returns wouldHaveSavedMicroUsd, factorVersion, periodRequests, periodSpendMicroUsd, basis, applied, netOfQuality. Format the display string yourself.
Reconcile the period. GET /platform/v1/ledger/export?period=YYYY-MM&format=jsonl|json|csv returns every metered request as a recovea-chain-v1 row with tokensIn, tokensOut, tokensCached, costMicroUsd, priceListVersion, and lever. The key-authed GET /v1/ledger/export serves the same rows in snake_case; the field map is on the ledger page. Summed costMicroUsd must equal periodSpendMicroUsd to the micro-USD; the row count must equal periodRequests.
Re-derive the hashes offline. Every row you can export today is recovea-chain-v1: join its 14 parts in published order with U+001F, SHA-256 the UTF-8 bytes, compare with rowHash, starting from a genesis of 64 zeros. The published recovea-receipt-v1 recipe joins 17 parts — the recipe id followed by its 16 hashed fields — but nothing in the API writes it. Golden vectors ship with both recipes; verification never calls us.
Check what we cannot hide. Every export row's lever reads observe, and leversFired is empty on every receipt GET /platform/v1/requests/{id} returns. A fired lever, or applied: true, is a bug. Send it to us.