Savings ledger
Squeezy records savings as labeled evidence, and every number says where it came from. The ledger keeps mechanism, provenance, confidence, bytes, optional token estimates, optional dollar estimates, and recovery references together so reports can explain what was measured and what was modeled.
Why a ledger exists
Cost-saving features work at different layers. A receipt stub avoids sending repeated bytes. A shell shaper keeps a build log small. Provider prompt caching can discount tokens even though the model still sees the same prefix. Cheap-model routing compares actual spend with a stronger-model baseline. Those are all useful, but they are not the same kind of fact.
The ledger gives each fact a row instead of rolling everything into one opaque savings number. That lets a summary say which mechanism fired, how many bytes were avoided or discounted, whether the token count came from the provider or from local request shape, and whether any dollar figure is a local estimate.
Cheap-model routing is one such row. When the router judges a turn simple enough to run on a cheaper model than your default, Squeezy records the estimated saving as a labeled counterfactual: the same tokens re-priced at the default model's rate, minus the cheaper model's actual bill and the small routing-judge call. The default model never ran, so it is a modeled comparison, not a charge. It is recorded only when the router chose the cheaper model, never when you pinned a turn cheap yourself.
Confidence labels
A savings row is only useful if you can trust its label. Provider-reported usage means the provider returned the token counter used for that row, such as cached input tokens. A local estimate means Squeezy derived the value from its own request shape or stored metadata and should not be read as the provider tokenizer's exact count.
The confidence levels then say how strong that evidence is. Measured rows are grounded in observed local bytes or provider usage counters. Deterministic estimates come from repeatable local facts like known byte sizes, output hashes, and request assembly. Counterfactual estimates compare what happened with a modeled alternative that did not happen. Heuristic rows are directional and should be shown cautiously.
Those labels are intentionally visible. A provider-reported cache token is not the same as a local byte-to-token estimate, and a counterfactual baseline is not a charge. Squeezy keeps the distinction so product surfaces can be useful without overclaiming precision.
- Measured: grounded in local observed bytes or provider usage counters.
- Deterministic estimate: repeatable from Squeezy's own request and output metadata.
- Counterfactual estimate: a modeled alternative, useful for comparison but not a billed event.
- Heuristic: directional evidence that should be shown cautiously.
What a summary can show
A savings summary groups rows by mechanism. For each mechanism it can show event count, confidence mix, raw bytes, model-visible bytes, saved bytes, and optional token or dollar estimates when every relevant row supplied enough data. If only some rows have token or dollar fields, a careful report says that aggregate is partial.
Negative rows are allowed. For example, a cache write can cost more than ordinary input on the current turn while setting up cheaper cache reads later. Keeping that row visible is clearer than hiding the up-front cost.
Deterministic example
This example is generated data. It does not require provider credentials and should be read as an export shape, not a benchmark result.
{
"by_mechanism": {
"receipt_stub": {
"event_count": 1,
"confidence": {
"measured_events": 0,
"deterministic_estimate_events": 1,
"counterfactual_estimate_events": 0,
"heuristic_events": 0
},
"raw_bytes_estimate": 12000,
"model_visible_bytes": 240,
"saved_bytes": 11760,
"saved_tokens_estimate": 2940,
"saved_tokens_estimate_events": 1
},
"prompt_cache_read": {
"event_count": 1,
"confidence": {
"measured_events": 1,
"deterministic_estimate_events": 0,
"counterfactual_estimate_events": 0,
"heuristic_events": 0
},
"raw_bytes_estimate": 32000,
"model_visible_bytes": 32000,
"saved_bytes": 0,
"saved_tokens_estimate": 8000,
"saved_tokens_estimate_events": 1,
"estimated_usd_micros": 7200,
"estimated_usd_micros_events": 1
}
}
}How to use it
Use the ledger to compare mechanisms, spot repeated waste, and decide which control to tune next. If receipt stubs dominate, repeated reads are being avoided. If shell shaping dominates, command output is being kept small. If cache rows dominate, provider cache behavior is driving the estimate.
Do not use the ledger as invoice reconciliation. It is designed to make savings evidence auditable and comparable while preserving the difference between provider-reported counters, deterministic local estimates, and counterfactual estimates.