Module cache_attribution 

Prompt-cache miss attribution (#986, cache-economics telemetry).

The proxy already keeps the client-cached prefix byte-stable (#448) and can re-seed a leaner one on a cold resume (#480). What it could not yet measure is why a turn fails to hit the provider prompt-cache — the single most actionable cache signal. There are only two causes, and they want opposite fixes:

• TTL lapse — the cacheable prefix is byte-identical to last turn, but the idle gap exceeded the provider’s cache TTL, so the entry expired. The fix is the cold-prefix repack (#480) / longer TTL, never a prefix change.
• Prefix change — the cacheable prefix is different from last turn, so the provider re-writes from the first changed byte regardless of timing. The fix is to stop mutating the prefix (a moving system prompt, an edited earlier turn, volatile fields — see the cache-aligner #940/#974).

This module classifies every anchored turn (cached > 0) into one of four outcomes by comparing the cached_prefix_hash and idle time against the conversation’s previous turn, and exposes cumulative gauges on /status. It is measurement-only — the request body is never touched — and gated behind the opt-in proxy.cache_policy, so a default proxy pays nothing.

Structs

CacheAttribution

Point-in-time view of the miss-attribution counters for /status.

Enums

CacheOutcome

The cache outcome attributed to one anchored (cached > 0) request, by comparing its cacheable prefix + idle time against the previous turn.

Functions

classify

Pure classification of a turn’s cache outcome. prev is the conversation’s previous (prefix_hash, last_touch), curr_hash this turn’s cacheable-prefix hash, now/ttl_secs the idle clock. Pure (no globals, no I/O) so the TTL-vs-prefix decision is unit-tested independently of the live store.

estimated_reuse_rate

Estimated reuse count for a conversation. Returns the global warm_reuse count as a rough proxy — individual per-conversation tracking would require extending PrefixState. Global warm_reuses / total_anchored gives the average reuse rate across all conversations.

record_request

Attribute this request’s cache outcome and record it, updating the conversation’s last-seen prefix baseline for the next turn. Only anchored turns (cached > 0) are attributable; an unanchored turn returns None (the cache-aligner telemetry #940 covers “client never anchors”). The caller owns the opt-in gate — this only runs when proxy.cache_policy is enabled.

snapshot