modelrig 0.0.1 → 0.2.0

package/dist/run/stream.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Streaming surface on the run path — G-1/G-5 Phase A (http-gateway spec §4.3).
+ *
+ * `runStream` wraps the existing `run()` loop with a delta side-channel: as the
+ * serving adapter streams, raw text tokens are emitted as `delta` events; when
+ * the run resolves, its terminal `RunResult` is emitted as the `final` event.
+ * Crucially the SAME pipeline (resolve → dispatch → validate → repair →
+ * telemetry) drives both streamed and buffered runs — streaming is purely a
+ * side-channel, so validation, repair, ZDR (G-3) and routing controls (G-2)
+ * all apply unchanged. `rig.run()` is left exactly as it was.
+ *
+ * The structured-route caveat (spec §4.3): streamed `delta` bytes are the
+ * model's RAW pre-validation output. The `final` event is authoritative — it
+ * carries the schema-validated (and, if repair fired, repaired) object plus
+ * `meta.validated` / `meta.repairedBy`. Callers wanting validated-only output
+ * pass `buffered: true` (no deltas, just the final) — the SDK mirror of the
+ * endpoint's `x-modelrig-stream: buffered`.
+ *
+ * ModelRig never executes a tool (spec §4.4); a tool-call turn surfaces on the
+ * final event's `meta.toolCalls` exactly as it does through `run()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStream = runStream;
+const run_1 = require("./run");
+/**
+ * Drive a route with token streaming. Returns an async-iterable of events plus
+ * a `result` promise for callers that only want the terminal value.
+ */
+function runStream(deps, routeName, opts) {
+    const queue = [];
+    let wake = null;
+    let done = false;
+    let failure = null;
+    const emit = (ev) => {
+        queue.push(ev);
+        if (wake !== null) {
+            wake();
+            wake = null;
+        }
+    };
+    const finish = () => {
+        done = true;
+        if (wake !== null) {
+            wake();
+            wake = null;
+        }
+    };
+    // Buffered mode omits the delta sink entirely — the loop then dispatches via
+    // the adapter's buffered call() (no true streaming), exactly as before.
+    const streamDeps = opts.buffered === true
+        ? deps
+        : { ...deps, onStreamDelta: ({ text }) => emit({ type: "delta", text }) };
+    const result = (0, run_1.run)(streamDeps, routeName, opts)
+        .then((r) => {
+        emit({ type: "final", result: r });
+        return r;
+    })
+        .catch((e) => {
+        failure = e;
+        throw e;
+    })
+        .finally(finish);
+    // A caller may consume only `events`; keep the promise from becoming an
+    // unhandled rejection (the error still surfaces through the iterator).
+    result.catch(() => undefined);
+    const events = {
+        async *[Symbol.asyncIterator]() {
+            for (;;) {
+                while (queue.length > 0) {
+                    const ev = queue.shift();
+                    if (ev !== undefined)
+                        yield ev;
+                }
+                if (done) {
+                    if (failure !== null)
+                        throw failure;
+                    return;
+                }
+                await new Promise((res) => {
+                    wake = res;
+                });
+            }
+        },
+    };
+    return { events, result };
+}

package/dist/run/validate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Output validation — plan §4. Ajv compiled once per (route, version), cached.
+ * Phase 1 checks schema conformance; value-accuracy gates arrive with the
+ * bake-off in Phase 3.
+ */
+import type { RouteBundle } from "../types/route";
+export interface ValidationOutcome {
+    readonly valid: boolean;
+    /** ajv error summaries, capped, human- and agent-readable. */
+    readonly errors: readonly string[];
+    /** Parsed output when text was JSON-parseable (even if schema-invalid). */
+    readonly parsed: unknown;
+}
+export declare function validateOutput(route: RouteBundle, text: string): ValidationOutcome;
+//# sourceMappingURL=validate.d.ts.map

package/dist/run/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/run/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAwBD,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CA6BlF"}

package/dist/run/validate.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Output validation — plan §4. Ajv compiled once per (route, version), cached.
+ * Phase 1 checks schema conformance; value-accuracy gates arrive with the
+ * bake-off in Phase 3.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOutput = validateOutput;
+const ajv_1 = require("./ajv");
+// Mirrors the production probe harness (packages/modelrig-probes/src/harness.ts):
+// an Ajv-2020 instance with the draft-07 meta added for back-compat — the two
+// must enforce identically, or a fixture would score differently than it serves.
+// Schemas trip ajv strict-mode warnings by design (strict:false).
+const ajv = (0, ajv_1.createModelrigAjv)();
+const MAX_ERRORS = 12;
+/** Compiled validators cached per (route, version) — recompiling a 300-line
+ * schema per attempt is measurable. */
+const validatorCache = new Map();
+function validatorFor(route) {
+    const key = `${route.route}@${route.version}`;
+    let compiled = validatorCache.get(key);
+    if (compiled === undefined) {
+        compiled = ajv.compile(route.outputSchema);
+        validatorCache.set(key, compiled);
+    }
+    return compiled;
+}
+function validateOutput(route, text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            errors: [`output is not valid JSON: ${err.message}`],
+            parsed: undefined,
+        };
+    }
+    if (route.outputSchema === null) {
+        return { valid: true, errors: [], parsed };
+    }
+    const validate = validatorFor(route);
+    if (validate(parsed)) {
+        return { valid: true, errors: [], parsed };
+    }
+    const all = validate.errors ?? [];
+    const errors = all
+        .slice(0, MAX_ERRORS)
+        .map((e) => `${e.instancePath || "/"} ${e.message ?? "invalid"}${e.keyword === "enum" ? ` (${JSON.stringify(e.params)})` : ""}`);
+    if (all.length > MAX_ERRORS) {
+        errors.push(`… ${all.length - MAX_ERRORS} more errors`);
+    }
+    return { valid: false, errors, parsed };
+}

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

@@ -0,0 +1,108 @@
+/**
+ * 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.
+ */
+import type { CachePolicy } from "../registry/cache-policy";
+import type { ProviderId } from "../types/provider";
+import type { TelemetryRow } from "../types/telemetry";
+export type WarmStatus = "observed_hot" | "probably_hot" | "probably_expired" | "cold";
+/**
+ * One derived warm-set entry: a (route, candidate, prefix_fingerprint, cache_key)
+ * group's current cache standing. The shape is the phase-2 storage seam —
+ * everything a dedicated ledger row would carry is here, derived.
+ */
+export interface CacheLedgerEntry {
+    readonly route: string;
+    readonly provider: string;
+    readonly model: string;
+    /** The cacheable-prefix identity (WS-C fills it; null in WS-A telemetry). */
+    readonly prefixFingerprint: string | null;
+    /** The provider cache key sent, if any (WS-C fills it; null otherwise). */
+    readonly cacheKey: string | null;
+    readonly status: WarmStatus;
+    /** Most recent use of this group (ISO). */
+    readonly lastSeenAt: string;
+    /** Seconds since `lastSeenAt` relative to the injected `now`. */
+    readonly ageSeconds: number;
+    /** Best estimate of the warm prefix size, tokens ("by how much" [§41]): the
+     * largest observed cache-READ on the group, or — when no read was observed —
+     * the mean input tokens as an upper bound of what COULD be cached. */
+    readonly warmTokens: number;
+    /** Largest observed cache-read on the group (0 ⇒ warmth is inferred, not seen). */
+    readonly observedReadTokens: number;
+    /** The policy TTL used to classify (seconds), or null when undocumented. */
+    readonly ttlSeconds: number | null;
+    /** Workflow identity (spec §9): run-loop = route; E2 runs carry episode_id.
+     * v1 normalizes to the route handle — the field exists so the ledger type is
+     * stable when episode-keyed workflows arrive. */
+    readonly workflowId: string;
+}
+export interface CacheLedgerOptions {
+    /** Reference "now" (epoch ms) — injected for deterministic derivation/tests. */
+    readonly now: number;
+    /** Policy lookup — injected for tests; defaults to the live registry. */
+    readonly policyFor?: (provider: ProviderId) => CachePolicy;
+    /** Only rows at/after this window start (epoch ms) are considered. Older rows
+     * cannot be warm and are skipped. Defaults to 24h before `now` — well past any
+     * seeded TTL, so no genuinely-warm group is dropped. */
+    readonly windowStartMs?: number;
+}
+/**
+ * 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.
+ */
+export declare const 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.
+ */
+export declare const PROBABLY_EXPIRED_TTL_MULTIPLE = 3;
+/**
+ * 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.
+ */
+export declare function classifyWarmStatus(policy: CachePolicy, ageSeconds: number, lastUseReadCache: boolean): WarmStatus;
+/**
+ * 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.
+ */
+export declare function deriveCacheLedger(rows: readonly TelemetryRow[], opts: CacheLedgerOptions): CacheLedgerEntry[];
+/** 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. */
+export declare function warmEntries(ledger: readonly CacheLedgerEntry[]): CacheLedgerEntry[];
+//# sourceMappingURL=cache-ledger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache-ledger.d.ts","sourceRoot":"","sources":["../../src/savings/cache-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,cAAc,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAEvF;;;;GAIG;AACH,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,6EAA6E;IAC7E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;0EAEsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;qDAEiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,KAAK,WAAW,CAAC;IAC3D;;4DAEwD;IACxD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAa/C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,OAAO,GACxB,UAAU,CAkBZ;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,IAAI,EAAE,kBAAkB,GACvB,gBAAgB,EAAE,CA6FpB;AAED;;;yCAGyC;AACzC,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,CAEnF"}

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"}