modelrig 0.1.0 → 0.2.0

package/dist/artifacts/step.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * `@step` / `step()` — execution scope for NON-LLM stages (spec §1.4, §9).
+ *
+ * A step is an execution operation ("what happened"). For LLM calls `rig.run()`
+ * auto-creates a ground-truth step (its inference row already exists); this
+ * wrapper is for the OTHER stages — retrieval, transforms, tool calls, external
+ * APIs — which have no inference row.
+ *
+ * ── WHY THIS WRITES NO STEP ROW THIS MISSION ──────────────────────────────
+ * The `steps` CHECK requires EXACTLY ONE reference: ground-truth (an inference)
+ * XOR attested (a foreign OTLP span). A pure non-LLM stage has neither — its
+ * span reference arrives with OTLP INGEST (E3), and nothing writes `attested`
+ * rows this mission. So `step()` establishes a NAMED execution scope inside the
+ * active run context (chunk B attributes artifact save/load lineage to it) and
+ * runs the body; it does not persist a row until it has a valid reference.
+ *
+ * Instrumentation never changes the wrapped function's return value, and never
+ * throws into it — a disabled or absent run context just runs the body.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.step = step;
+const run_context_1 = require("./run-context");
+/**
+ * Run `fn` as a named execution step within the active run context. Returns the
+ * body's value unchanged (a promise if the body is async). Outside a run context
+ * (namespace disabled, or no run.start on this path) it simply runs the body.
+ */
+function step(key, fn) {
+    const ctx = (0, run_context_1.getActiveRunContext)();
+    if (ctx === null)
+        return fn();
+    // Reserve a unique step key so chunk B can attribute this scope's artifact
+    // saves/loads. No row is written (see header).
+    ctx.nextStepKey(key);
+    return fn();
+}

package/dist/artifacts/taint.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Taint propagation — downstream closure over the artifact graph (Expansion E4
+ * chunk C, spec §Chunk C). "If THIS artifact is bad, what derived from it?" —
+ * the condemn-or-clear question. Follows lineage edges forward (an edge means
+ * `from` was produced from / consumed `to`, so `from` is DOWNSTREAM of `to`) and
+ * `supersedes` chains forward (a version that supersedes a tainted one inherits
+ * the taint). Served as a bounded DTO the artifact page renders and the replay
+ * affordance (chunk A) links into.
+ *
+ * ── BOUNDED + HONEST ──────────────────────────────────────────────────────
+ * Real graphs can be deep, wide, or cyclic (a redaction supersedes an artifact
+ * that a later step also consumed). So the closure is:
+ *   - depth-bounded (default 20) — `depthLimited` says more may exist deeper;
+ *   - cycle-guarded (a visited set — a node is expanded once);
+ *   - count-capped (default 500) — `truncated` says "≥ cap", never a silent cut.
+ * The production path is a recursive CTE with the SAME bounds (server); this pure
+ * function is the algorithm both the CTE golden-tests against and a caller can
+ * run over fetched edges without a database.
+ */
+/** A stored lineage edge: `from` depends on `to` (kind = how). */
+export interface TaintEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: "consumed" | "derived_from";
+}
+/** A supersession: `artifactId` supersedes `supersedesArtifactId` (a newer
+ * version). The superseder is downstream of what it supersedes. */
+export interface Supersession {
+    readonly artifactId: string;
+    readonly supersedesArtifactId: string;
+}
+export interface TaintNode {
+    readonly id: string;
+    /** Hops from the root (1 = a direct descendant). */
+    readonly depth: number;
+}
+export interface TaintClosure {
+    readonly root: string;
+    /** Downstream artifacts, breadth-first (nearest first), deduped, capped. */
+    readonly downstream: readonly TaintNode[];
+    /** `downstream.length` — the count actually returned. */
+    readonly count: number;
+    /** True when the closure hit the count cap — the honest "≥ count" signal. */
+    readonly truncated: boolean;
+    /** True when the frontier reached `maxDepth` — more may exist deeper. */
+    readonly depthLimited: boolean;
+    readonly maxDepth: number;
+    readonly cap: number;
+}
+export interface TaintOptions {
+    /** Max hops from the root (default 20). */
+    readonly maxDepth?: number;
+    /** Max downstream nodes returned before truncation (default 500). */
+    readonly cap?: number;
+}
+export declare const TAINT_DEFAULT_MAX_DEPTH = 20;
+export declare const TAINT_DEFAULT_CAP = 500;
+/**
+ * Downstream closure from `root`. Pure and deterministic. Cycle-guarded via a
+ * visited set; depth-bounded; count-capped with an honest `truncated` flag.
+ */
+export declare function computeDownstreamClosure(root: string, edges: readonly TaintEdge[], supersessions: readonly Supersession[], options?: TaintOptions): TaintClosure;
+//# sourceMappingURL=taint.d.ts.map

package/dist/artifacts/taint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"taint.d.ts","sourceRoot":"","sources":["../../src/artifacts/taint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,CAAC;CAC5C;AAED;mEACmE;AACnE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,aAAa,EAAE,SAAS,YAAY,EAAE,EACtC,OAAO,GAAE,YAAiB,GACzB,YAAY,CA2Cd"}

package/dist/artifacts/taint.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Taint propagation — downstream closure over the artifact graph (Expansion E4
+ * chunk C, spec §Chunk C). "If THIS artifact is bad, what derived from it?" —
+ * the condemn-or-clear question. Follows lineage edges forward (an edge means
+ * `from` was produced from / consumed `to`, so `from` is DOWNSTREAM of `to`) and
+ * `supersedes` chains forward (a version that supersedes a tainted one inherits
+ * the taint). Served as a bounded DTO the artifact page renders and the replay
+ * affordance (chunk A) links into.
+ *
+ * ── BOUNDED + HONEST ──────────────────────────────────────────────────────
+ * Real graphs can be deep, wide, or cyclic (a redaction supersedes an artifact
+ * that a later step also consumed). So the closure is:
+ *   - depth-bounded (default 20) — `depthLimited` says more may exist deeper;
+ *   - cycle-guarded (a visited set — a node is expanded once);
+ *   - count-capped (default 500) — `truncated` says "≥ cap", never a silent cut.
+ * The production path is a recursive CTE with the SAME bounds (server); this pure
+ * function is the algorithm both the CTE golden-tests against and a caller can
+ * run over fetched edges without a database.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAINT_DEFAULT_CAP = exports.TAINT_DEFAULT_MAX_DEPTH = void 0;
+exports.computeDownstreamClosure = computeDownstreamClosure;
+exports.TAINT_DEFAULT_MAX_DEPTH = 20;
+exports.TAINT_DEFAULT_CAP = 500;
+/**
+ * Downstream closure from `root`. Pure and deterministic. Cycle-guarded via a
+ * visited set; depth-bounded; count-capped with an honest `truncated` flag.
+ */
+function computeDownstreamClosure(root, edges, supersessions, options = {}) {
+    const maxDepth = options.maxDepth ?? exports.TAINT_DEFAULT_MAX_DEPTH;
+    const cap = options.cap ?? exports.TAINT_DEFAULT_CAP;
+    // Adjacency: node → its direct downstream nodes. An edge (from → to) makes
+    // `from` downstream of `to`; a supersession makes the superseder downstream of
+    // what it supersedes. Both collapse into the same "who depends on X" map.
+    const downstreamOf = new Map();
+    const add = (parent, child) => {
+        const cur = downstreamOf.get(parent);
+        if (cur === undefined)
+            downstreamOf.set(parent, [child]);
+        else
+            cur.push(child);
+    };
+    for (const e of edges)
+        add(e.to, e.from);
+    for (const s of supersessions)
+        add(s.supersedesArtifactId, s.artifactId);
+    const visited = new Set([root]); // root is never listed as its own downstream
+    const downstream = [];
+    let truncated = false;
+    let depthLimited = false;
+    // BFS by depth so `downstream` is nearest-first and depth is well-defined.
+    let frontier = [root];
+    for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
+        const next = [];
+        for (const node of frontier) {
+            for (const child of downstreamOf.get(node) ?? []) {
+                if (visited.has(child))
+                    continue; // cycle / diamond guard: expand once
+                visited.add(child);
+                if (downstream.length >= cap) {
+                    truncated = true;
+                    continue; // keep draining `visited` so we don't re-count, but add no more
+                }
+                downstream.push({ id: child, depth });
+                next.push(child);
+            }
+        }
+        frontier = next;
+    }
+    // If we stopped because we hit maxDepth but there was still a frontier, more
+    // may exist deeper than we looked.
+    if (frontier.length > 0)
+        depthLimited = true;
+    return { root, downstream, count: downstream.length, truncated, depthLimited, maxDepth, cap };
+}

package/dist/bakeoff/cache-sim.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Virtual cache simulator — cache-aware-routing spec §5.4, [Briefing §26]. PURE:
+ * no store/clock/network. THE fix for the independent-turn evaluation fallacy:
+ * replay currently scores every sample COLD, so a bake-off report can never see
+ * that a candidate would run warm at production cadence. This walks a candidate's
+ * call sequence in timestamp order, maintaining a per-candidate VIRTUAL cache
+ * from the POLICY REGISTRY (TTL + min-cacheable + refresh-on-read), and emits a
+ * per-call {read, write, uncached} token split.
+ *
+ * ── SIMULATOR HONESTY (spec §5.4, §10 credibility risk) ───────────────────
+ *   • State comes ONLY from the policy registry — never from a guessed model of
+ *     how a provider caches. An undocumented TTL uses a CONSERVATIVE fallback
+ *     (short), so the sim UNDER-credits rather than over-credits warmth.
+ *   • The output is always LABELLED simulation. The odometer stays measured-only
+ *     (this module never feeds it) — simulator output is never "verified savings".
+ *   • Cache identity is the caller-supplied `prefixFingerprint`. A template
+ *     mutation or a tool-order change is, by construction, a DIFFERENT
+ *     fingerprint — so a mutation forces a miss/rewrite with no special-casing
+ *     here (the synthetic tests exercise exactly that).
+ *
+ * A "switch-and-return" is modelled by a time GAP in this candidate's sequence:
+ * if the gap is within TTL the return is a read (still warm); if it exceeds TTL
+ * the cache has expired and the return rewrites. Nothing about the OTHER
+ * candidate is needed — each candidate is simulated over its own calls.
+ */
+import type { CachePolicy } from "../registry/cache-policy";
+import type { EffectiveRates } from "../registry/effective-rate";
+import type { ProviderId } from "../types/provider";
+/** One call in a candidate's sequence. `prefixTokens` is the cacheable prefix
+ * length; `promptTokens` the whole input (prefix + volatile tail). */
+export interface SimCall {
+    readonly tsMs: number;
+    readonly prefixFingerprint: string;
+    readonly prefixTokens: number;
+    readonly promptTokens: number;
+}
+/** Per-call token split — a disjoint partition of `promptTokens`:
+ * `simulated_read + simulated_write + simulated_uncached === promptTokens`. */
+export interface SimCallResult {
+    readonly simulated_read: number;
+    readonly simulated_write: number;
+    readonly simulated_uncached: number;
+    /** True when the cacheable prefix was served from a warm virtual cache. */
+    readonly hit: boolean;
+}
+/** The policy assumptions the sim ran under — PRINTED with every report so the
+ * simulation's basis is never hidden (spec §5.4 "assumptions printed"). */
+export interface CacheSimAssumptions {
+    readonly provider: string;
+    readonly model: string;
+    readonly cacheSupported: boolean;
+    /** TTL used to expire virtual entries (seconds). */
+    readonly ttlSeconds: number;
+    /** false ⇒ `ttlSeconds` is the conservative fallback, not a published value. */
+    readonly ttlSourced: boolean;
+    readonly minCacheableTokens: number;
+    readonly refreshOnRead: boolean;
+}
+export interface CacheSimResult {
+    readonly perCall: readonly SimCallResult[];
+    readonly totalRead: number;
+    readonly totalWrite: number;
+    readonly totalUncached: number;
+    readonly hitCount: number;
+    readonly assumptions: CacheSimAssumptions;
+}
+/**
+ * Conservative TTL (seconds) for a provider that publishes none
+ * (`default_ttl_seconds: null`). Deliberately SHORT — the shortest real registry
+ * TTL (Anthropic 5m) — so the simulator never over-credits warmth for a provider
+ * whose true window is longer but undocumented (spec §5.4 honesty).
+ */
+export declare const FALLBACK_SIM_TTL_SECONDS = 300;
+export interface CacheSimOptions {
+    /** Policy override — injected for tests; defaults to the live registry. */
+    readonly policy?: CachePolicy;
+}
+/**
+ * Simulate one candidate's cache trajectory over `calls`. Calls are processed in
+ * ascending timestamp order (a copy is sorted; the input is not mutated). The
+ * per-call results are returned in that same timestamp order.
+ */
+export declare function simulateCache(provider: ProviderId, model: string, calls: readonly SimCall[], opts?: CacheSimOptions): CacheSimResult;
+/**
+ * Cache-ADJUSTED input cost of a simulated trajectory (spec §5.4): the read /
+ * write / uncached token buckets each priced at their own rate, with the
+ * fail-closed fallback to the input rate (dev-rule L5) when a cache rate is
+ * unverified. This is what the candidate WOULD pay at production cadence — the
+ * right-hand column of the bake-off's side-by-side.
+ */
+export declare function simulatedInputCostUsd(sim: CacheSimResult, rates: EffectiveRates): number;
+/**
+ * Measured-COLD input cost (spec §5.4): every input token at the list input
+ * rate — what independent-turn replay actually pays. The left-hand column. This
+ * equals `simulatedInputCostUsd` exactly when the sim produced zero reads and
+ * zero writes (the regression pin — no cache activity, no divergence).
+ */
+export declare function coldInputCostUsd(sim: CacheSimResult, rates: EffectiveRates): number;
+//# sourceMappingURL=cache-sim.d.ts.map

package/dist/bakeoff/cache-sim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-sim.d.ts","sourceRoot":"","sources":["../../src/bakeoff/cache-sim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;sEACsE;AACtE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;+EAC+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB;AAED;2EAC2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;CAC3C;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AASD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,IAAI,GAAE,eAAoB,GACzB,cAAc,CAkEhB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAIxF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAEnF"}

package/dist/bakeoff/cache-sim.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * Virtual cache simulator — cache-aware-routing spec §5.4, [Briefing §26]. PURE:
+ * no store/clock/network. THE fix for the independent-turn evaluation fallacy:
+ * replay currently scores every sample COLD, so a bake-off report can never see
+ * that a candidate would run warm at production cadence. This walks a candidate's
+ * call sequence in timestamp order, maintaining a per-candidate VIRTUAL cache
+ * from the POLICY REGISTRY (TTL + min-cacheable + refresh-on-read), and emits a
+ * per-call {read, write, uncached} token split.
+ *
+ * ── SIMULATOR HONESTY (spec §5.4, §10 credibility risk) ───────────────────
+ *   • State comes ONLY from the policy registry — never from a guessed model of
+ *     how a provider caches. An undocumented TTL uses a CONSERVATIVE fallback
+ *     (short), so the sim UNDER-credits rather than over-credits warmth.
+ *   • The output is always LABELLED simulation. The odometer stays measured-only
+ *     (this module never feeds it) — simulator output is never "verified savings".
+ *   • Cache identity is the caller-supplied `prefixFingerprint`. A template
+ *     mutation or a tool-order change is, by construction, a DIFFERENT
+ *     fingerprint — so a mutation forces a miss/rewrite with no special-casing
+ *     here (the synthetic tests exercise exactly that).
+ *
+ * A "switch-and-return" is modelled by a time GAP in this candidate's sequence:
+ * if the gap is within TTL the return is a read (still warm); if it exceeds TTL
+ * the cache has expired and the return rewrites. Nothing about the OTHER
+ * candidate is needed — each candidate is simulated over its own calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FALLBACK_SIM_TTL_SECONDS = void 0;
+exports.simulateCache = simulateCache;
+exports.simulatedInputCostUsd = simulatedInputCostUsd;
+exports.coldInputCostUsd = coldInputCostUsd;
+const cache_policy_1 = require("../registry/cache-policy");
+/**
+ * Conservative TTL (seconds) for a provider that publishes none
+ * (`default_ttl_seconds: null`). Deliberately SHORT — the shortest real registry
+ * TTL (Anthropic 5m) — so the simulator never over-credits warmth for a provider
+ * whose true window is longer but undocumented (spec §5.4 honesty).
+ */
+exports.FALLBACK_SIM_TTL_SECONDS = 300;
+/**
+ * Simulate one candidate's cache trajectory over `calls`. Calls are processed in
+ * ascending timestamp order (a copy is sorted; the input is not mutated). The
+ * per-call results are returned in that same timestamp order.
+ */
+function simulateCache(provider, model, calls, opts = {}) {
+    const policy = opts.policy ?? (0, cache_policy_1.getCachePolicy)(provider);
+    const ttlSourced = policy.cache_supported && policy.default_ttl_seconds !== null;
+    const ttlSeconds = policy.cache_supported && policy.default_ttl_seconds !== null
+        ? policy.default_ttl_seconds
+        : exports.FALLBACK_SIM_TTL_SECONDS;
+    const ttlMs = ttlSeconds * 1000;
+    const minCacheable = policy.min_cacheable_tokens ?? 0;
+    const assumptions = {
+        provider,
+        model,
+        cacheSupported: policy.cache_supported,
+        ttlSeconds,
+        ttlSourced,
+        minCacheableTokens: minCacheable,
+        refreshOnRead: policy.ttl_refresh_on_read,
+    };
+    const ordered = [...calls].sort((a, b) => a.tsMs - b.tsMs);
+    const cache = new Map();
+    const perCall = [];
+    let totalRead = 0;
+    let totalWrite = 0;
+    let totalUncached = 0;
+    let hitCount = 0;
+    for (const call of ordered) {
+        const prompt = Math.max(call.promptTokens, 0);
+        const prefix = Math.min(Math.max(call.prefixTokens, 0), prompt);
+        // Provider does not cache on our path, or the prefix is below the minimum
+        // cacheable size: caching does not engage — the whole prompt is uncached and
+        // NO virtual state is written (spec §5.4: min-cacheable gates the write).
+        if (!policy.cache_supported || prefix < minCacheable || prefix === 0) {
+            perCall.push({ simulated_read: 0, simulated_write: 0, simulated_uncached: prompt, hit: false });
+            totalUncached += prompt;
+            continue;
+        }
+        const entry = cache.get(call.prefixFingerprint);
+        const warm = entry !== undefined && call.tsMs < entry.expiresAtMs;
+        if (warm) {
+            // HIT: read the cached prefix; the volatile tail is uncached.
+            const read = Math.min(prefix, entry.tokens);
+            const uncached = prompt - read;
+            perCall.push({ simulated_read: read, simulated_write: 0, simulated_uncached: uncached, hit: true });
+            totalRead += read;
+            totalUncached += uncached;
+            hitCount += 1;
+            // TTL base: a read refreshes the window only when the policy says so;
+            // otherwise the entry keeps expiring from its WRITE time.
+            if (policy.ttl_refresh_on_read)
+                entry.expiresAtMs = call.tsMs + ttlMs;
+        }
+        else {
+            // MISS (cold or expired): WRITE the prefix into cache; the tail is uncached.
+            const uncached = prompt - prefix;
+            perCall.push({ simulated_read: 0, simulated_write: prefix, simulated_uncached: uncached, hit: false });
+            totalWrite += prefix;
+            totalUncached += uncached;
+            cache.set(call.prefixFingerprint, { tokens: prefix, expiresAtMs: call.tsMs + ttlMs });
+        }
+    }
+    return { perCall, totalRead, totalWrite, totalUncached, hitCount, assumptions };
+}
+/**
+ * Cache-ADJUSTED input cost of a simulated trajectory (spec §5.4): the read /
+ * write / uncached token buckets each priced at their own rate, with the
+ * fail-closed fallback to the input rate (dev-rule L5) when a cache rate is
+ * unverified. This is what the candidate WOULD pay at production cadence — the
+ * right-hand column of the bake-off's side-by-side.
+ */
+function simulatedInputCostUsd(sim, rates) {
+    const readRate = rates.cacheRead ?? rates.input;
+    const writeRate = rates.cacheWrite ?? rates.input;
+    return sim.totalRead * readRate + sim.totalWrite * writeRate + sim.totalUncached * rates.input;
+}
+/**
+ * Measured-COLD input cost (spec §5.4): every input token at the list input
+ * rate — what independent-turn replay actually pays. The left-hand column. This
+ * equals `simulatedInputCostUsd` exactly when the sim produced zero reads and
+ * zero writes (the regression pin — no cache activity, no divergence).
+ */
+function coldInputCostUsd(sim, rates) {
+    return (sim.totalRead + sim.totalWrite + sim.totalUncached) * rates.input;
+}

package/dist/bakeoff/eval-cases.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Bake-off input selection from eval cases — Expansion E4 chunk A (spec §3).
+ *
+ * `bakeoff --from-eval-cases <task>` replays the promoted regression/golden cases
+ * for a task instead of the last-N captures. A case only holds METADATA (a source
+ * artifact id); the INPUT to replay lives in a LOCAL capture, reachable through
+ * the chain:
+ *
+ *   eval_case → source artifact (run_id, step_key) → step's inference_id → capture
+ *
+ * Any link may be missing — the source artifact predates local retention, the
+ * route never had `capture: true`, the capture was evicted. When it is, the case
+ * is UNREHYDRATABLE. The load-bearing doctrine (spec §3.3): the bake-off runs on
+ * the rehydratable subset and NAMES every refused case with a reason — NEVER a
+ * silent subset. `selectEvalCaseCaptures` returns both halves so the CLI can
+ * print the honest-refusal report before it spends a cent.
+ */
+import type { CaptureRow, CaptureStore } from "../telemetry/capture";
+import type { ArtifactStore } from "../telemetry/artifact-store";
+import type { ExportableTelemetryStore } from "../telemetry/store";
+import type { EvalCaseRow } from "../types/telemetry";
+import type { RunDeps } from "../run/run";
+import { type BakeoffSamplesSink } from "./engine";
+import type { KeepOutputsMode } from "./samples";
+import type { BakeoffArtifact } from "./types";
+/** The narrow store surface the selection reads — kept minimal so this module
+ * depends on four reads, not three whole stores. */
+export interface EvalCaseSelectionDeps {
+    readonly readEvalCasesByTask: (task: string) => EvalCaseRow[];
+    readonly getArtifactById: (id: string) => {
+        runId: string | null;
+        stepKey: string | null;
+    } | null;
+    readonly getStepInferenceId: (runId: string, stepKey: string) => string | null;
+    readonly getCaptureByInferenceId: (inferenceId: string) => CaptureRow | null;
+}
+export interface RehydratedCase {
+    readonly caseId: string;
+    readonly capture: CaptureRow;
+}
+export interface EvalCaseRefusal {
+    readonly caseId: string;
+    readonly sourceArtifactId: string;
+    /** Which link of the chain broke — the honest, actionable reason. */
+    readonly reason: string;
+}
+export interface EvalCaseSelection {
+    readonly task: string;
+    /** Total eval cases found for the task (rehydratable + refused). */
+    readonly total: number;
+    readonly rehydratable: readonly RehydratedCase[];
+    readonly refusals: readonly EvalCaseRefusal[];
+}
+/**
+ * Partition a task's eval cases into rehydratable (with their captured input) and
+ * refused (named, with a reason). Pure over the injected reads — no network, no
+ * spend; the CLI runs this first and reports before replaying.
+ */
+export declare function selectEvalCaseCaptures(deps: EvalCaseSelectionDeps, task: string): EvalCaseSelection;
+/**
+ * A read-only in-memory CaptureStore over a fixed set of rehydrated captures, so
+ * the EXISTING bake-off engine (which reads `captures.readLast(route, n)`) runs
+ * over the eval-case selection with NO second actuation path (spec §3.3). Only
+ * `readLast` is meaningful; `getByInferenceId` is supported for symmetry; writes
+ * throw (this store is a replay lens, never a sink).
+ */
+export declare function evalCaseCaptureStore(rows: readonly RehydratedCase[]): CaptureStore;
+export interface EvalCaseBakeoffResult {
+    readonly selection: EvalCaseSelection;
+    /** The bake-off artifact over the rehydratable subset, or null when NOTHING
+     * was rehydratable (the CLI then reports the refusals and exits without spend). */
+    readonly artifact: BakeoffArtifact | null;
+}
+/**
+ * `bakeoff --from-eval-cases <task>` end to end: select rehydratable cases, then
+ * run the EXISTING bake-off engine over exactly those captured inputs (no second
+ * actuation path — spec §3.3). Replays every rehydratable case (replayLastN =
+ * the rehydratable count). Returns the selection (so the caller reports refusals)
+ * alongside the artifact.
+ */
+/** The rig-side store bundle the orchestrator adapts into `EvalCaseSelectionDeps`
+ * — passed straight from `createRig` so `index.ts` stays a one-line delegate.
+ * `artifacts` is null when the namespace is off (nothing to rehydrate); `captures`
+ * is a thunk because the rig opens that handle lazily. */
+export interface EvalCaseStores {
+    readonly artifacts: Pick<ArtifactStore, "readEvalCasesByTask" | "getArtifactById"> | null;
+    readonly telemetry: Pick<ExportableTelemetryStore, "getStepInferenceId">;
+    readonly captures: () => Pick<CaptureStore, "getByInferenceId">;
+}
+export declare function runBakeoffFromEvalCases(deps: RunDeps, stores: EvalCaseStores, req: {
+    readonly task: string;
+    readonly variants: readonly string[];
+    readonly envelopeUsdPerVariant: number;
+    readonly keepOutputs?: KeepOutputsMode;
+}, samplesSink?: BakeoffSamplesSink): Promise<EvalCaseBakeoffResult>;
+//# sourceMappingURL=eval-cases.d.ts.map

package/dist/bakeoff/eval-cases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-cases.d.ts","sourceRoot":"","sources":["../../src/bakeoff/eval-cases.ts"],"names":[],"mappings":"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"}

package/dist/bakeoff/eval-cases.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Bake-off input selection from eval cases — Expansion E4 chunk A (spec §3).
+ *
+ * `bakeoff --from-eval-cases <task>` replays the promoted regression/golden cases
+ * for a task instead of the last-N captures. A case only holds METADATA (a source
+ * artifact id); the INPUT to replay lives in a LOCAL capture, reachable through
+ * the chain:
+ *
+ *   eval_case → source artifact (run_id, step_key) → step's inference_id → capture
+ *
+ * Any link may be missing — the source artifact predates local retention, the
+ * route never had `capture: true`, the capture was evicted. When it is, the case
+ * is UNREHYDRATABLE. The load-bearing doctrine (spec §3.3): the bake-off runs on
+ * the rehydratable subset and NAMES every refused case with a reason — NEVER a
+ * silent subset. `selectEvalCaseCaptures` returns both halves so the CLI can
+ * print the honest-refusal report before it spends a cent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectEvalCaseCaptures = selectEvalCaseCaptures;
+exports.evalCaseCaptureStore = evalCaseCaptureStore;
+exports.runBakeoffFromEvalCases = runBakeoffFromEvalCases;
+const engine_1 = require("./engine");
+/**
+ * Partition a task's eval cases into rehydratable (with their captured input) and
+ * refused (named, with a reason). Pure over the injected reads — no network, no
+ * spend; the CLI runs this first and reports before replaying.
+ */
+function selectEvalCaseCaptures(deps, task) {
+    const cases = deps.readEvalCasesByTask(task);
+    const rehydratable = [];
+    const refusals = [];
+    for (const c of cases) {
+        const refuse = (reason) => {
+            refusals.push({ caseId: c.id, sourceArtifactId: c.sourceArtifactId, reason });
+        };
+        const art = deps.getArtifactById(c.sourceArtifactId);
+        if (art === null) {
+            refuse("source artifact is not in the local store (promoted on another deployment, or evicted)");
+            continue;
+        }
+        if (art.runId === null || art.stepKey === null) {
+            refuse("source artifact was saved outside a step — no inference to key its input");
+            continue;
+        }
+        const inferenceId = deps.getStepInferenceId(art.runId, art.stepKey);
+        if (inferenceId === null) {
+            refuse("no ground-truth inference recorded for the source step");
+            continue;
+        }
+        const capture = deps.getCaptureByInferenceId(inferenceId);
+        if (capture === null) {
+            refuse("input not captured locally (route `capture` was off, or the capture was evicted)");
+            continue;
+        }
+        rehydratable.push({ caseId: c.id, capture });
+    }
+    return { task, total: cases.length, rehydratable, refusals };
+}
+/**
+ * A read-only in-memory CaptureStore over a fixed set of rehydrated captures, so
+ * the EXISTING bake-off engine (which reads `captures.readLast(route, n)`) runs
+ * over the eval-case selection with NO second actuation path (spec §3.3). Only
+ * `readLast` is meaningful; `getByInferenceId` is supported for symmetry; writes
+ * throw (this store is a replay lens, never a sink).
+ */
+function evalCaseCaptureStore(rows) {
+    const captures = rows.map((r) => r.capture);
+    return {
+        record() {
+            throw new Error("evalCaseCaptureStore is read-only (a replay lens, not a sink)");
+        },
+        readLast(route, n) {
+            return captures.filter((c) => c.route === route).slice(0, n);
+        },
+        getByInferenceId(inferenceId) {
+            return captures.find((c) => c.inferenceId === inferenceId) ?? null;
+        },
+        close() { },
+    };
+}
+async function runBakeoffFromEvalCases(deps, stores, req, samplesSink) {
+    const empty = { task: req.task, total: 0, rehydratable: [], refusals: [] };
+    // No artifact namespace ⇒ nothing to rehydrate; honest empty selection.
+    if (stores.artifacts === null)
+        return { selection: empty, artifact: null };
+    const arts = stores.artifacts;
+    const caps = stores.captures();
+    const selection = selectEvalCaseCaptures({
+        readEvalCasesByTask: (t) => arts.readEvalCasesByTask(t),
+        getArtifactById: (id) => arts.getArtifactById(id),
+        getStepInferenceId: (r, s) => stores.telemetry.getStepInferenceId(r, s),
+        getCaptureByInferenceId: (i) => caps.getByInferenceId(i),
+    }, req.task);
+    if (selection.rehydratable.length === 0)
+        return { selection, artifact: null };
+    const artifact = await (0, engine_1.runBakeoff)(deps, evalCaseCaptureStore(selection.rehydratable), {
+        route: req.task,
+        variants: req.variants,
+        replayLastN: selection.rehydratable.length, // replay every rehydratable case
+        envelopeUsdPerVariant: req.envelopeUsdPerVariant,
+        ...(req.keepOutputs !== undefined ? { keepOutputs: req.keepOutputs } : {}),
+    }, samplesSink);
+    return { selection, artifact };
+}