jcp: count the joules a cache hit did not spend, without ever calling it spend #75

Merged

dcharlot merged 1 commit from jcp/avoided-energy into main 2026-09-03 15:11:51 -04:00

Conversation 0 Commits 1 Files changed 2 +284

2026-09-03

David Charlot

jcp: count the joules a cache hit did not spend, without ever calling it spend ...

MCP's 2026-07-28 revision added `CacheableResult` with `ttlMs`/`cacheScope`, so
a served result can declare itself reusable. When it is reused, work that would
have run did not — and for a family whose doctrine is that inference is the last
resort, the cheapest joule is the one never spent. Nothing in the family bound a
reused result to an energy figure.

It is also the easiest quantity here to lie with, so it does not become another
`Energy`.

**It is a counterfactual, not a measurement.** Nothing measures a joule that was
not spent; an avoided figure is a claim about what would have happened. The only
thing making it checkable is a pointer to the execution it stands in for, so
`AvoidedEnergy` cannot be constructed without naming the receipt whose measured
cost it claims to have avoided. Without that, "this hit saved 10 mJ" is
unfalsifiable — and unfalsifiable savings are how an efficiency programme
reports progress it never made.

**It must never be added to energy spent.** If avoided joules were summed with
spent joules, or subtracted from them, a system could manufacture arbitrary
efficiency and, with enough hits, report negative consumption. Physics has no
negative-joule case; an accounting system that does has a bug that looks like a
triumph. So this type produces no `Energy`, offers no arithmetic against a spend
total, and `AvoidedSummary::saving_ppm_of` takes the spend as an argument rather
than holding it — the two totals meet in exactly one place, expressed as a ratio
*to* spend and never a deduction *from* it. A test drives five million-microjoule
hits against a 200 µJ spend and shows no path to a negative spend figure.

**A cache hit is not free.** The net subtracts what serving the hit cost, since
claiming the full prior cost over-claims by exactly that amount. When a lookup
costs more than recomputing would have, the saving is reported **negative rather
than clamped**: a cache that does not pay for itself is a real outcome, and
rounding it to "no saving" hides the one case an operator most needs to act on.
`unprofitable_hits` is counted separately, so a cache that is net-positive
overall while losing on most requests is visible rather than averaged away.

The saving inherits the basis measurement's acquisition class, because a saving
standing in for an `Estimator` figure is an estimated saving however precisely
it prints.

Ranked by the 2026-08-29 sweep as the one remaining item it called unclaimed
territory rather than an adapter.

Verified: 265 jcp-rs tests pass (5 new), conformance passes all classes, no
clippy warnings in the new file.

Co-Authored-By: Claude Opus 5 <[email protected]>

50b5efaad0

• View at this point in history

2026-09-03 15:06:42 -04:00