Module cache_share 

Cache-share guard: per provider+model cost log, rolling cache-read share, alarm below the threshold, and the provider allowlist for open models.

A customer at the plan limit costs several times more when the provider’s prompt cache does not hit: every prompt token then bills at the full input rate instead of the cache-read rate. This module watches that per provider+model:

• Cost log — record_turn logs every measured provider turn with its provider, model, input/cache-read/cache-write/output tokens and the purchase price of each token class (USD per 1M tokens).
• Rolling aggregate — the turns land in time buckets per provider+model; CacheShareLedger::report sums the configured window into the cache-read share of the prompt tokens and the effective cost (with what the same tokens would have cost without any cache).
• Alarm — when a window with enough prompt tokens drops below [proxy.cache_share] alarm_threshold (default 90 %), a warning is logged and a VerificationWarning event (cache_share_below_threshold) is emitted once; it re-arms when the share recovers.
• Open-model allowlist — an open-weight model served by a provider outside open_model_providers is flagged (warning + event) or, with open_model_policy = "refuse", refused before the request leaves (open_model_refusal). Local endpoints are exempt.

The ledger persists to proxy_cache_share.json next to proxy_usage.json so lean-ctx spend --cache reads it from another process.

Structs

CacheShareLedger

Rolling per provider+model ledger. Pure: the caller passes the clock and the settings, and turns the returned Signals into logs and events.

CacheShareReport

The window report: settings plus one row per provider+model.

CacheShareRow

One provider+model over the window.

CallCost

One measured provider turn, priced.

Settings

Resolved [proxy.cache_share] settings.

TokenPrices

Purchase price per token class, USD per 1M tokens.

Enums

OpenModelVerdict

How the open-model allowlist judges one provider+model.

ShareStatus

Health of one provider+model over the window.

Signal

State change worth a log line and an event.

Constants

ALARM_EVENT

Event kind of the cache-share alarm.

OPEN_MODEL_EVENT

Event kind of an open model on an unlisted provider.

OPEN_MODEL_PROVIDER_NOT_ALLOWED

Reason code of a refused open model on an unlisted provider.

Functions

cache_read_share

Cache-read share of the prompt tokens (uncached input + cache reads + cache writes); None when there are no prompt tokens.

is_open_model

True when model names an open-weight model family (built-in fragments plus extra, all lowercase).

load_persisted

Cross-process read of the persisted ledger.

open_model_refusal

Request-time check: the refusal code when the policy refuses this open model on this provider; a flag-only verdict is reported at record time.

open_model_verdict

Judges model on provider against the open-model allowlist.

persisted_report

The persisted window report for the CLI, or None before any turn.

record_turn

Logs, aggregates and persists one measured turn (called from super::usage_meter::record, the single choke-point of measured turns).