modelrig 0.1.0 → 0.3.0

package/dist/savings/cache-ledger.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * Cache Ledger — DERIVED in v1 (cache-aware-routing spec §5.2, [Briefing §8]).
+ *
+ * The Briefing's Cache Ledger is a first-class fast-state store; v1 does NOT
+ * build one. It DERIVES warm-set state from telemetry rows at decision time —
+ * ZERO new tables (spec schema budget). The `CacheLedgerEntry` TYPE ships now so
+ * that when the conversational-gateway phase needs a dedicated store (per-message
+ * traffic makes per-call derivation too hot), it is a swap of BACKING, not of
+ * SHAPE. Nothing here persists anything.
+ *
+ * This answers the Briefing's first-milestone question — "which candidate routes
+ * appear warm, by how much, at what confidence" [§41] — with a 4-value status:
+ *
+ *   observed_hot    — the most recent use within the TTL window actually READ
+ *                     cache (tokensCached>0): the cache is demonstrably warm.
+ *   probably_hot    — last use within the TTL window but no read observed on it:
+ *                     warmth is INFERRED from recency, not seen.
+ *   probably_expired— last use past the TTL but within a bounded grace: likely
+ *                     cold, yet recent enough that a switch-back could still hit
+ *                     (LiteLLM: 99.3% of switch-backs land within TTL, [§6]).
+ *   cold            — no recent use, well past any grace, or the provider does
+ *                     not cache on our path (fail-closed).
+ *
+ * ── CONSERVATISM (spec §10 cache-state overconfidence) ────────────────────
+ * The TTL comes from the POLICY REGISTRY only. When a provider publishes no TTL
+ * (deepseek "hours-to-days", gemini/fireworks best-effort → `default_ttl_seconds:
+ * null`), we do NOT invent a warm window: the entry can reach `observed_hot`
+ * only via a demonstrated read within a short fallback recency, and otherwise is
+ * `cold`. Under-claiming warmth never over-predicts a hit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROBABLY_EXPIRED_TTL_MULTIPLE = exports.NULL_TTL_OBSERVED_HOT_SECONDS = void 0;
+exports.classifyWarmStatus = classifyWarmStatus;
+exports.deriveCacheLedger = deriveCacheLedger;
+exports.warmEntries = warmEntries;
+const cache_policy_1 = require("../registry/cache-policy");
+/**
+ * Fallback recency window (seconds) for the `observed_hot` decision when a
+ * provider publishes NO TTL. NOT a claimed provider TTL — a conservative display
+ * bound so an ancient demonstrated read is not still called "hot". 5 minutes is
+ * the shortest real cache TTL in the registry (Anthropic 5m), so it never
+ * over-claims relative to any documented policy.
+ */
+exports.NULL_TTL_OBSERVED_HOT_SECONDS = 300;
+/**
+ * Grace multiplier past the TTL for `probably_expired` before an entry is called
+ * `cold`. Beyond `ttl × this`, a switch-back is very unlikely to still hit.
+ */
+exports.PROBABLY_EXPIRED_TTL_MULTIPLE = 3;
+// Grouping key — none of the components contains a newline.
+const KEY_SEP = "\n";
+function isProductionRow(row) {
+    try {
+        return JSON.parse(row.tagsJson).replay === undefined;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Classify a group's warm status from its policy TTL, age, and whether the most
+ * recent use read cache. Pure and total; the boundary rules are the architect
+ * math-review surface, so they are spelled out rather than folded together.
+ */
+function classifyWarmStatus(policy, ageSeconds, lastUseReadCache) {
+    if (!policy.cache_supported)
+        return "cold";
+    const ttl = policy.default_ttl_seconds;
+    if (ttl === null) {
+        // No documented TTL: only a demonstrated, recent read earns "hot". We never
+        // INFER warmth here (no probably_hot) — that would be the overconfidence the
+        // spec §10 warns against.
+        return lastUseReadCache && ageSeconds <= exports.NULL_TTL_OBSERVED_HOT_SECONDS ? "observed_hot" : "cold";
+    }
+    if (ageSeconds <= ttl) {
+        return lastUseReadCache ? "observed_hot" : "probably_hot";
+    }
+    if (ageSeconds <= ttl * exports.PROBABLY_EXPIRED_TTL_MULTIPLE) {
+        return "probably_expired";
+    }
+    return "cold";
+}
+/**
+ * Derive the warm-set ledger from telemetry rows (spec §5.2). Groups production
+ * rows by (route, provider, model, prefix_fingerprint, cache_key), takes each
+ * group's most-recent use to classify warmth via the policy TTL, and estimates
+ * the warm prefix size. Replay rows are excluded (odometer parity). Output is
+ * sorted for deterministic rendering. Nothing is stored.
+ */
+function deriveCacheLedger(rows, opts) {
+    const policyFor = opts.policyFor ?? ((p) => (0, cache_policy_1.getCachePolicy)(p));
+    const windowStartMs = opts.windowStartMs ?? opts.now - 86400000;
+    const byKey = new Map();
+    for (const row of rows) {
+        if (!isProductionRow(row))
+            continue;
+        const t = Date.parse(row.ts);
+        if (Number.isNaN(t) || t < windowStartMs || t > opts.now)
+            continue;
+        const fp = row.prefixFingerprint ?? null;
+        const ck = row.cacheKey ?? null;
+        const key = [row.route, row.provider, row.model, fp ?? "", ck ?? ""].join(KEY_SEP);
+        let acc = byKey.get(key);
+        if (acc === undefined) {
+            acc = {
+                route: row.route,
+                provider: row.provider,
+                model: row.model,
+                prefixFingerprint: fp,
+                cacheKey: ck,
+                lastSeenAtMs: -1,
+                lastSeenAt: row.ts,
+                lastUseReadCache: false,
+                maxReadTokens: 0,
+                tokensInSum: 0,
+                n: 0,
+            };
+            byKey.set(key, acc);
+        }
+        acc.n += 1;
+        acc.tokensInSum += Math.max(row.tokensIn, 0);
+        acc.maxReadTokens = Math.max(acc.maxReadTokens, Math.max(row.tokensCached, 0));
+        if (t > acc.lastSeenAtMs) {
+            acc.lastSeenAtMs = t;
+            acc.lastSeenAt = row.ts;
+            acc.lastUseReadCache = row.tokensCached > 0;
+        }
+        else if (t === acc.lastSeenAtMs && row.tokensCached > 0) {
+            // Same-ms tie: a DEMONSTRATED read at the newest timestamp wins,
+            // regardless of row order in the (unsorted) feed. Without this the
+            // observed_hot/probably_hot status would depend on array order — a
+            // reordered feed of the same rows could flip the status. Preferring the
+            // read is the truer signal (the cache WAS warm at that instant).
+            acc.lastUseReadCache = true;
+        }
+    }
+    const out = [];
+    for (const acc of byKey.values()) {
+        const ageSeconds = Math.max(0, (opts.now - acc.lastSeenAtMs) / 1000);
+        const policy = policyFor(acc.provider);
+        const status = classifyWarmStatus(policy, ageSeconds, acc.lastUseReadCache);
+        const meanIn = acc.n > 0 ? acc.tokensInSum / acc.n : 0;
+        const warmTokens = acc.maxReadTokens > 0 ? acc.maxReadTokens : meanIn;
+        out.push({
+            route: acc.route,
+            provider: acc.provider,
+            model: acc.model,
+            prefixFingerprint: acc.prefixFingerprint,
+            cacheKey: acc.cacheKey,
+            status,
+            lastSeenAt: acc.lastSeenAt,
+            ageSeconds,
+            warmTokens,
+            observedReadTokens: acc.maxReadTokens,
+            ttlSeconds: policy.cache_supported ? policy.default_ttl_seconds : null,
+            workflowId: acc.route,
+        });
+    }
+    return out.sort((a, b) => a.route !== b.route
+        ? a.route.localeCompare(b.route)
+        : a.provider !== b.provider
+            ? a.provider.localeCompare(b.provider)
+            : a.model !== b.model
+                ? a.model.localeCompare(b.model)
+                : (a.prefixFingerprint ?? "").localeCompare(b.prefixFingerprint ?? ""));
+}
+/** The warm candidates for a route — `observed_hot` or `probably_hot` — as the
+ * warmth input for shadow-mode ordering (WS-B step 8) and the console warm-set
+ * chips (WS-D). `probably_expired`/`cold` are excluded: warmth we would ACT on
+ * must be current, not merely recent. */
+function warmEntries(ledger) {
+    return ledger.filter((e) => e.status === "observed_hot" || e.status === "probably_hot");
+}

package/dist/savings/cache-reconcile.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Cache prediction reconciliation — cache-aware-routing spec §5.2 (the
+ * [Briefing §8] feedback loop, v1-deterministic). PURE: no store/clock/network.
+ *
+ * "Predict → route → observe → reconcile" (spec §1.2): the derived ledger + the
+ * simulator PREDICT cache reads; provider-reported usage is GROUND TRUTH. When
+ * the two diverge beyond tolerance, the estimate is systematically off — a
+ * provider rule changed, a fingerprint is unstable, an endpoint lost affinity —
+ * and a `cache_prediction_drift` health event fires so the discrepancy is
+ * surfaced rather than silently trusted.
+ *
+ * G-4 PATTERN (telemetry/health.ts): this is a pure aggregation that RETURNS
+ * event objects — it never persists. A min-sample gate protects against calling
+ * two noisy calls a "drift". WS-D renders the events (console badge); no DDL and
+ * no new table are involved (spec schema budget).
+ */
+/** A predicted-vs-observed pair for one (route, candidate) over the window. */
+export interface CachePredictionSample {
+    readonly route: string;
+    readonly provider: string;
+    readonly model: string;
+    /** Cache-READ tokens the ledger/simulator predicted over the window. */
+    readonly predictedReadTokens: number;
+    /** Cache-READ tokens the provider actually reported (Σ tokensCached). */
+    readonly observedReadTokens: number;
+    /** Total input tokens over the window — the base the drift is normalized by,
+     * and the min-sample gate. */
+    readonly windowInputTokens: number;
+    /** Production rows the pair aggregates (for the gate + the surfaced evidence). */
+    readonly sampleN: number;
+}
+/** A fired drift event (G-4 shape). Never persisted; rendered by WS-D. */
+export interface CachePredictionDrift {
+    readonly route: string;
+    readonly provider: string;
+    readonly model: string;
+    readonly predictedReadTokens: number;
+    readonly observedReadTokens: number;
+    /** |predicted − observed| / windowInputTokens — the normalized gap. */
+    readonly driftFraction: number;
+    /** Signed hit-rate error (predicted_h − observed_h): positive ⇒ we OVER-predicted
+     * warmth (the more dangerous direction — over-optimistic routing). */
+    readonly signedHitRateError: number;
+    readonly sampleN: number;
+}
+export interface ReconcileOptions {
+    /** Drift tolerance as a FRACTION of window input tokens (default 0.15 — the
+     * estimate must be within 15% of ground truth before it is "off"). */
+    readonly toleranceFraction?: number;
+    /** Minimum production rows before a pair is judged (default 20 — matches the
+     * observed-health min-n; below it the gap is too noisy to trust). */
+    readonly minN?: number;
+}
+export declare const DEFAULT_DRIFT_TOLERANCE_FRACTION = 0.15;
+export declare const DEFAULT_DRIFT_MIN_N = 20;
+/**
+ * Compare predicted vs observed cache reads per (route, candidate) and emit a
+ * drift event for each pair whose normalized gap exceeds tolerance AND clears
+ * the min-sample gate. Pure and total; output sorted for deterministic
+ * rendering. An empty result means every prediction tracked ground truth (or
+ * nothing had enough data) — the healthy case.
+ */
+export declare function reconcileCacheDrift(samples: readonly CachePredictionSample[], opts?: ReconcileOptions): CachePredictionDrift[];
+//# sourceMappingURL=cache-reconcile.d.ts.map

package/dist/savings/cache-reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-reconcile.d.ts","sourceRoot":"","sources":["../../src/savings/cache-reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,yEAAyE;IACzE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC;kCAC8B;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;0EACsE;IACtE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B;0EACsE;IACtE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;yEACqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,gCAAgC,OAAO,CAAC;AACrD,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,IAAI,GAAE,gBAAqB,GAC1B,oBAAoB,EAAE,CA+BxB"}

package/dist/savings/cache-reconcile.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Cache prediction reconciliation — cache-aware-routing spec §5.2 (the
+ * [Briefing §8] feedback loop, v1-deterministic). PURE: no store/clock/network.
+ *
+ * "Predict → route → observe → reconcile" (spec §1.2): the derived ledger + the
+ * simulator PREDICT cache reads; provider-reported usage is GROUND TRUTH. When
+ * the two diverge beyond tolerance, the estimate is systematically off — a
+ * provider rule changed, a fingerprint is unstable, an endpoint lost affinity —
+ * and a `cache_prediction_drift` health event fires so the discrepancy is
+ * surfaced rather than silently trusted.
+ *
+ * G-4 PATTERN (telemetry/health.ts): this is a pure aggregation that RETURNS
+ * event objects — it never persists. A min-sample gate protects against calling
+ * two noisy calls a "drift". WS-D renders the events (console badge); no DDL and
+ * no new table are involved (spec schema budget).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DRIFT_MIN_N = exports.DEFAULT_DRIFT_TOLERANCE_FRACTION = void 0;
+exports.reconcileCacheDrift = reconcileCacheDrift;
+exports.DEFAULT_DRIFT_TOLERANCE_FRACTION = 0.15;
+exports.DEFAULT_DRIFT_MIN_N = 20;
+/**
+ * Compare predicted vs observed cache reads per (route, candidate) and emit a
+ * drift event for each pair whose normalized gap exceeds tolerance AND clears
+ * the min-sample gate. Pure and total; output sorted for deterministic
+ * rendering. An empty result means every prediction tracked ground truth (or
+ * nothing had enough data) — the healthy case.
+ */
+function reconcileCacheDrift(samples, opts = {}) {
+    const tolerance = opts.toleranceFraction ?? exports.DEFAULT_DRIFT_TOLERANCE_FRACTION;
+    const minN = opts.minN ?? exports.DEFAULT_DRIFT_MIN_N;
+    const out = [];
+    for (const s of samples) {
+        if (s.sampleN < minN || s.windowInputTokens <= 0)
+            continue; // thin data → no judgment
+        const gap = Math.abs(s.predictedReadTokens - s.observedReadTokens);
+        const driftFraction = gap / s.windowInputTokens;
+        if (driftFraction <= tolerance)
+            continue;
+        const predictedH = s.predictedReadTokens / s.windowInputTokens;
+        const observedH = s.observedReadTokens / s.windowInputTokens;
+        out.push({
+            route: s.route,
+            provider: s.provider,
+            model: s.model,
+            predictedReadTokens: s.predictedReadTokens,
+            observedReadTokens: s.observedReadTokens,
+            driftFraction,
+            signedHitRateError: predictedH - observedH,
+            sampleN: s.sampleN,
+        });
+    }
+    return out.sort((a, b) => a.route !== b.route
+        ? a.route.localeCompare(b.route)
+        : a.provider !== b.provider
+            ? a.provider.localeCompare(b.provider)
+            : a.model.localeCompare(b.model));
+}

package/dist/savings/cache-stats.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Cache-hit-rate rollup — cache-aware-routing spec §5.1, WS-B. PURE: a function
+ * over telemetry rows, no store/clock/network (an injected `now` bounds the
+ * window). Feeds the effective-rate blend (§4.2), the derived ledger (§5.2), and
+ * the console (WS-D).
+ *
+ * ── THE ODOMETER RULE (replay exclusion) ──────────────────────────────────
+ * Trailing-window measurements count PRODUCTION serving only: a bake-off replay
+ * pass runs real (billed) calls tagged `replay`, and those must NEVER inflate a
+ * route's measured hit rate any more than they inflate measured savings. This is
+ * the SAME 5-line filter the savings odometer uses — see
+ * `savings/odometer.ts` (`JSON.parse(r.tagsJson).replay !== undefined`). It is
+ * duplicated (not imported) deliberately: the two live in different modules with
+ * different row shapes, and a shared 5-line helper would couple them for no real
+ * gain. If the replay tag convention ever changes, change BOTH.
+ *
+ * ── UNPRICED ROWS ARE KEPT ────────────────────────────────────────────────
+ * Unlike the odometer (which drops `pricingMissing` rows so a $0 cannot inflate
+ * dollar savings), the hit-rate rollup is a TOKEN measurement, not a dollar one:
+ * an unpriced row still carries honest token counts, so it counts toward h/w.
+ * Pricing enters later, in the effective-rate blend, where a missing rate
+ * fail-closes on its own.
+ */
+import type { TelemetryRow } from "../types/telemetry";
+/** Trailing window for the rollup — 7 days by default (spec §5.1). */
+export declare const DEFAULT_CACHE_WINDOW_DAYS = 7;
+/** Observed cache activity for one (route, provider, model) over the window. */
+export interface CacheStatsRollup {
+    readonly route: string;
+    readonly provider: string;
+    readonly model: string;
+    /** Production rows in the window (replay excluded). */
+    readonly sampleN: number;
+    /** Σ input tokens (the denominator of h and w). */
+    readonly tokensIn: number;
+    /** Σ cache-READ tokens. */
+    readonly tokensCached: number;
+    /** Σ cache-WRITE (creation) tokens. */
+    readonly tokensCacheWrite: number;
+    /** Observed hit rate `h = Σcached/Σin` (0 when `tokensIn` is 0). */
+    readonly h: number;
+    /** Observed write rate `w = Σwrite/Σin` (0 when `tokensIn` is 0). */
+    readonly w: number;
+    /** Most recent row ts in the window (ISO), or null when none. */
+    readonly lastSeenAt: string | null;
+    /** Distinct non-null prefix fingerprints seen — the cacheable prefixes this
+     * route×candidate exercised (WS-C fills them; empty in WS-A-only telemetry). */
+    readonly prefixFingerprints: readonly string[];
+}
+export interface CacheStatsOptions {
+    /** Reference "now" (epoch ms) — injected for deterministic windowing/tests. */
+    readonly now: number;
+    /** Window width in days (default 7). */
+    readonly windowDays?: number;
+}
+/**
+ * Roll telemetry rows up into per-(route, provider, model) cache stats over the
+ * trailing window. Rows outside `[now − windowDays, now]`, with an unparseable
+ * ts, or tagged `replay` are excluded. Output is sorted (route, provider, model)
+ * for deterministic downstream rendering and stable snapshots.
+ */
+export declare function rollupCacheStats(rows: readonly TelemetryRow[], opts: CacheStatsOptions): CacheStatsRollup[];
+//# sourceMappingURL=cache-stats.d.ts.map

package/dist/savings/cache-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-stats.d.ts","sourceRoot":"","sources":["../../src/savings/cache-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,sEAAsE;AACtE,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2BAA2B;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uCAAuC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,oEAAoE;IACpE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;oFACgF;IAChF,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAiBD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,IAAI,EAAE,iBAAiB,GACtB,gBAAgB,EAAE,CAwEpB"}

package/dist/savings/cache-stats.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Cache-hit-rate rollup — cache-aware-routing spec §5.1, WS-B. PURE: a function
+ * over telemetry rows, no store/clock/network (an injected `now` bounds the
+ * window). Feeds the effective-rate blend (§4.2), the derived ledger (§5.2), and
+ * the console (WS-D).
+ *
+ * ── THE ODOMETER RULE (replay exclusion) ──────────────────────────────────
+ * Trailing-window measurements count PRODUCTION serving only: a bake-off replay
+ * pass runs real (billed) calls tagged `replay`, and those must NEVER inflate a
+ * route's measured hit rate any more than they inflate measured savings. This is
+ * the SAME 5-line filter the savings odometer uses — see
+ * `savings/odometer.ts` (`JSON.parse(r.tagsJson).replay !== undefined`). It is
+ * duplicated (not imported) deliberately: the two live in different modules with
+ * different row shapes, and a shared 5-line helper would couple them for no real
+ * gain. If the replay tag convention ever changes, change BOTH.
+ *
+ * ── UNPRICED ROWS ARE KEPT ────────────────────────────────────────────────
+ * Unlike the odometer (which drops `pricingMissing` rows so a $0 cannot inflate
+ * dollar savings), the hit-rate rollup is a TOKEN measurement, not a dollar one:
+ * an unpriced row still carries honest token counts, so it counts toward h/w.
+ * Pricing enters later, in the effective-rate blend, where a missing rate
+ * fail-closes on its own.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CACHE_WINDOW_DAYS = void 0;
+exports.rollupCacheStats = rollupCacheStats;
+/** Trailing window for the rollup — 7 days by default (spec §5.1). */
+exports.DEFAULT_CACHE_WINDOW_DAYS = 7;
+/** The replay-exclusion predicate — see the module header (odometer parity).
+ * A row is production unless its tags carry a `replay` key. Unparseable tags
+ * are treated as production (a malformed tag never hides real traffic). */
+function isProductionRow(row) {
+    try {
+        return JSON.parse(row.tagsJson).replay === undefined;
+    }
+    catch {
+        return true;
+    }
+}
+// Grouping key: none of route / provider / model contains a newline, so a
+// newline separator splits back unambiguously.
+const KEY_SEP = "\n";
+/**
+ * Roll telemetry rows up into per-(route, provider, model) cache stats over the
+ * trailing window. Rows outside `[now − windowDays, now]`, with an unparseable
+ * ts, or tagged `replay` are excluded. Output is sorted (route, provider, model)
+ * for deterministic downstream rendering and stable snapshots.
+ */
+function rollupCacheStats(rows, opts) {
+    const windowDays = opts.windowDays ?? exports.DEFAULT_CACHE_WINDOW_DAYS;
+    const windowStartMs = opts.now - windowDays * 86400000;
+    const byKey = new Map();
+    for (const row of rows) {
+        if (!isProductionRow(row))
+            continue;
+        const t = Date.parse(row.ts);
+        if (Number.isNaN(t) || t < windowStartMs || t > opts.now)
+            continue;
+        const key = `${row.route}${KEY_SEP}${row.provider}${KEY_SEP}${row.model}`;
+        let acc = byKey.get(key);
+        if (acc === undefined) {
+            acc = {
+                sampleN: 0,
+                tokensIn: 0,
+                tokensCached: 0,
+                tokensCacheWrite: 0,
+                lastSeenAtMs: -1,
+                lastSeenAt: null,
+                fingerprints: new Set(),
+            };
+            byKey.set(key, acc);
+        }
+        acc.sampleN += 1;
+        acc.tokensIn += Math.max(row.tokensIn, 0);
+        acc.tokensCached += Math.max(row.tokensCached, 0);
+        acc.tokensCacheWrite += Math.max(row.tokensCacheWrite ?? 0, 0);
+        if (t > acc.lastSeenAtMs) {
+            acc.lastSeenAtMs = t;
+            acc.lastSeenAt = row.ts;
+        }
+        if (row.prefixFingerprint != null && row.prefixFingerprint !== "") {
+            acc.fingerprints.add(row.prefixFingerprint);
+        }
+    }
+    const out = [];
+    for (const [key, acc] of byKey) {
+        const [route, provider, model] = key.split(KEY_SEP);
+        out.push({
+            route,
+            provider,
+            model,
+            sampleN: acc.sampleN,
+            tokensIn: acc.tokensIn,
+            tokensCached: acc.tokensCached,
+            tokensCacheWrite: acc.tokensCacheWrite,
+            h: acc.tokensIn > 0 ? acc.tokensCached / acc.tokensIn : 0,
+            w: acc.tokensIn > 0 ? acc.tokensCacheWrite / acc.tokensIn : 0,
+            lastSeenAt: acc.lastSeenAt,
+            prefixFingerprints: [...acc.fingerprints].sort(),
+        });
+    }
+    return out.sort((a, b) => a.route !== b.route
+        ? a.route.localeCompare(b.route)
+        : a.provider !== b.provider
+            ? a.provider.localeCompare(b.provider)
+            : a.model.localeCompare(b.model));
+}

package/dist/savings/emit.d.ts

@@ -21,5 +21,18 @@ export interface SwapChange {
      * revert can be emitted even without the pre-swap file. */
     readonly incumbentCandidates: readonly CandidateSpec[];
 }
+/**
+ * Restore-YAML for a REVERT — managed-loop §1 (`POST /v1/swaps/:id/revert`).
+ *
+ * A revert has no bake-off winner; it restores the swap's snapshotted incumbent
+ * candidates (`swap_events.baseline.incumbent_candidates`) at a version above the
+ * route's current one — history moves forward, never rewrites. Same
+ * no-filesystem, paste-ready shape as `buildSwapChange`; the server emits it and
+ * a human applies it via a PR (never-silent-swap extends to the revert).
+ */
+export declare function buildRestoreYaml(route: string, incumbent: readonly {
+    readonly provider: string;
+    readonly model: string;
+}[], currentVersion: number): string;
 export declare function buildSwapChange(bundle: RouteBundle, winningVariant: string): SwapChange;
 //# sourceMappingURL=emit.d.ts.map

package/dist/savings/emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/savings/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAgB,MAAM,gBAAgB,CAAC;AAE/E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;yCACqC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;+DAC2D;IAC3D,QAAQ,CAAC,mBAAmB,EAAE,SAAS,aAAa,EAAE,CAAC;CACxD;AAiCD,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,UAAU,CA6CvF"}
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/savings/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAgB,MAAM,gBAAgB,CAAC;AAE/E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;yCACqC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;+DAC2D;IAC3D,QAAQ,CAAC,mBAAmB,EAAE,SAAS,aAAa,EAAE,CAAC;CACxD;AAmCD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,EAC3E,cAAc,EAAE,MAAM,GACrB,MAAM,CAgBR;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,UAAU,CA6CvF"}

package/dist/savings/emit.js

@@ -7,6 +7,7 @@
  * greps for it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRestoreYaml = buildRestoreYaml;
 exports.buildSwapChange = buildSwapChange;
 function candidateLines(candidates) {
     return candidates.flatMap((c) => [`  - provider: ${c.provider}`, `    model: ${c.model}`]);
@@ -32,6 +33,30 @@ function promotedOrder(declared, winners) {
     const winnerKeys = new Set(winners.map(key));
     return [...winners, ...declared.filter((c) => !winnerKeys.has(key(c)))];
 }
+/**
+ * Restore-YAML for a REVERT — managed-loop §1 (`POST /v1/swaps/:id/revert`).
+ *
+ * A revert has no bake-off winner; it restores the swap's snapshotted incumbent
+ * candidates (`swap_events.baseline.incumbent_candidates`) at a version above the
+ * route's current one — history moves forward, never rewrites. Same
+ * no-filesystem, paste-ready shape as `buildSwapChange`; the server emits it and
+ * a human applies it via a PR (never-silent-swap extends to the revert).
+ */
+function buildRestoreYaml(route, incumbent, currentVersion) {
+    if (incumbent.length === 0) {
+        throw new Error(`cannot emit a restore for "${route}" — the swap recorded no incumbent candidates to restore ` +
+            "(an older swap predating the baseline snapshot; revert it by hand from git history)");
+    }
+    const file = `modelrig/routes/${route}.yaml`;
+    return [
+        `# revert: restore ${route} to ${incumbent[0].provider}/${incumbent[0].model}`,
+        `# apply to ${file} — replace the version and candidates fields; nothing else changes`,
+        `version: ${currentVersion + 1}`,
+        "candidates:",
+        ...candidateLines(incumbent),
+        "",
+    ].join("\n");
+}
 function buildSwapChange(bundle, winningVariant) {
     const variant = bundle.variants.find((v) => v.name === winningVariant);
     if (variant === undefined) {

package/dist/savings/swap-execute.d.ts

@@ -15,8 +15,16 @@
  */
 import type { SwapChange } from "./emit";
 import type { SwapEventRecord } from "./swaps-client";
+import type { CacheContext } from "../watch/evaluate";
+import type { CacheVerdict } from "../registry/effective-rate";
 import type { ProposalRecord, ProposalStatus } from "../watch/proposals";
 import type { RouteBundle } from "../types/route";
+/** Narrow a proposal's `evidence.cache_context` jsonb (spec §5.5 — additive,
+ * present only on cache-aware proposals) to a typed `CacheContext`, or null when
+ * absent/malformed. Defensive: an older or non-cache proposal has no block, and
+ * a partial block must degrade to "no cache explanation", never throw on the
+ * safety-critical execute path. */
+export declare function readCacheContext(evidence: Record<string, unknown> | null): CacheContext | null;
 export interface SwapExecuteDeps {
     readonly proposalId: string;
     /** THE gate — false throws before any read or write. */
@@ -39,6 +47,12 @@ export interface SwapExecuteResult {
     readonly change: SwapChange;
     readonly approvedBy: string;
     readonly executedAt: string;
+    /** Cache-aware verdict from the proposal's `cache_context` evidence (spec
+     * §5.5), or null on a non-cache proposal. Additive — never gates execution
+     * (the human already approved); surfaced so the CLI/console can show WHY. */
+    readonly cacheVerdict: CacheVerdict | null;
+    /** The [Briefing §30] one-line explanation for the approval prompt, or null. */
+    readonly cacheExplanation: string | null;
 }
 export declare function executeSwap(deps: SwapExecuteDeps): Promise<SwapExecuteResult>;
 //# sourceMappingURL=swap-execute.d.ts.map

package/dist/savings/swap-execute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swap-execute.d.ts","sourceRoot":"","sources":["../../src/savings/swap-execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAgB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AASlD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE;QAClB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;QAChD,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAChF,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE;QAAE,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAClE,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,WAAW,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuFnF"}
+{"version":3,"file":"swap-execute.d.ts","sourceRoot":"","sources":["../../src/savings/swap-execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAgB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;;mCAImC;AACnC,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,YAAY,GAAG,IAAI,CAmB9F;AASD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE;QAClB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;QAChD,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAChF,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE;QAAE,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAClE,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,WAAW,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;iFAE6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAwGnF"}

package/dist/savings/swap-execute.js

@@ -15,8 +15,36 @@
  *    executed. Applying the YAML stays a human/git action.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCacheContext = readCacheContext;
 exports.executeSwap = executeSwap;
 const emit_1 = require("./emit");
+const evaluate_1 = require("../watch/evaluate");
+/** Narrow a proposal's `evidence.cache_context` jsonb (spec §5.5 — additive,
+ * present only on cache-aware proposals) to a typed `CacheContext`, or null when
+ * absent/malformed. Defensive: an older or non-cache proposal has no block, and
+ * a partial block must degrade to "no cache explanation", never throw on the
+ * safety-critical execute path. */
+function readCacheContext(evidence) {
+    const raw = evidence?.cache_context;
+    if (raw === null || typeof raw !== "object")
+        return null;
+    const c = raw;
+    const verdicts = ["cache_positive", "cache_marginal", "cache_negative", "no_cache_signal"];
+    if (typeof c.verdict !== "string" || !verdicts.includes(c.verdict))
+        return null;
+    const num = (v) => (typeof v === "number" ? v : 0);
+    return {
+        observed_hit_rate: num(c.observed_hit_rate),
+        observed_write_rate: num(c.observed_write_rate),
+        window_days: num(c.window_days),
+        incumbent_effective_in_per_mtok: num(c.incumbent_effective_in_per_mtok),
+        challenger_cold_in_per_mtok: num(c.challenger_cold_in_per_mtok),
+        switch_cost_usd: num(c.switch_cost_usd),
+        cache_option_value_usd: num(c.cache_option_value_usd),
+        breakeven_conformant_calls: typeof c.breakeven_conformant_calls === "number" ? c.breakeven_conformant_calls : Number.POSITIVE_INFINITY,
+        verdict: c.verdict,
+    };
+}
 async function executeSwap(deps) {
     // The gate first — before any client call, so a non-approved invocation
     // has zero side effects (defense in depth with the CLI's fast-fail check).
@@ -83,5 +111,20 @@ async function executeSwap(deps) {
         revertedAt: null,
     });
     await deps.proposals.setStatus(proposal.id, "approved", "executed");
-    return { swapId, route: proposal.route, change, approvedBy: deps.approvedBy, executedAt };
+    // Cache-aware explainability (spec §5.5) — additive, read-only. The verdict +
+    // prose ride along for the approval prompt / audit trail; they NEVER gate the
+    // swap (the human decision above is the only gate). Absent on non-cache
+    // proposals, in which case both are null and behavior is byte-identical.
+    const cacheContext = readCacheContext(proposal.evidence);
+    const incumbentLabel = change.incumbentCandidates.map((c) => `${c.provider}/${c.model}`).join(", ") || "incumbent";
+    const cacheExplanation = cacheContext !== null ? (0, evaluate_1.explainCacheContext)(cacheContext, incumbentLabel, winner.variant) : null;
+    return {
+        swapId,
+        route: proposal.route,
+        change,
+        approvedBy: deps.approvedBy,
+        executedAt,
+        cacheVerdict: cacheContext?.verdict ?? null,
+        cacheExplanation,
+    };
 }