Module usage 

Usage reports — a per-request roll-up of context cost (docs/context-reuse.md §2).

Every frame carries an honest token_cost (§protocol-surface B1), but the protocol otherwise stops at the frame. A host that meters context into a billing system — the usage-events → ClickHouse → Stripe loop platforms run — needs an aggregate: which providers served how many frames, at what token cost, against which budget. Left unspecified, every host invents that shape independently and context cost stays unauditable one level up from the wire — the blob-pipe problem reborn at the accounting layer.

A UsageReport is that aggregate. It is a host-side artifact, not a wire message: it rides no new envelope variant and no new required field, so a provider implements nothing to make one possible. The reference host produces it from a fan-out (FanOut::usage_report).

Each served frame is recorded as a ServedFrame: its stable FrameId identity and the token_cost the provider declared for it. Storing the pair is what lets an auditor walk from a billed total back to the exact frames behind it — and it makes the report self-verifying: the per-provider and request totals re-sum from these entries, so a corrupted total is a checkable arithmetic failure, not a silent misbill (the conformance case in §2).

Structs

ProviderUsage

One provider’s usage within a single query: how many frames it served, how many were rejected, the summed token cost, and the served frames’ identities.

ServedFrame

One served frame’s contribution to a UsageReport: its stable identity and the token_cost its provider declared for it.

UsageReport

A per-request roll-up of context cost across every provider a query fanned out to (docs/context-reuse.md §2).