modelrig 0.0.1 → 0.2.0

package/dist/artifacts/scrub.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Scrub v1 — deterministic PII/PHI detection over artifact content BEFORE upload
+ * (E2-C chunk B, spec §3.1 / Expansion spec §7.4).
+ *
+ * Four modes, per route (default `detect` when content custody is on):
+ *   off    — no scan; upload verbatim.
+ *   detect — scan; record FINDINGS as counts-by-type; upload verbatim. The
+ *            findings are metadata (how many SSNs, how many emails), NEVER the
+ *            matched values — recording the value would move the PII into the
+ *            control-plane DB, the exact thing custody is meant to contain.
+ *   redact — scan; upload a MASKED copy; the finding counts still travel.
+ *   block  — scan; if anything is found, REFUSE the upload (counted); the
+ *            artifact keeps its metadata + hash, it simply stores no content.
+ *
+ * ── DETERMINISTIC ≠ DLP (honest limits) ───────────────────────────────────
+ * These are regex/checksum detectors, not a model. They catch well-formed SSNs,
+ * Luhn-valid PANs, emails, E.164/US phones, and labelled MRNs. They WILL miss
+ * obfuscated or free-form PII (that is scrub v2, model-assisted, out of scope).
+ * The custody docs page states this plainly — a caller must not read a clean
+ * `detect` result as a guarantee of no PII.
+ *
+ * NEVER logs a matched value. Findings are `{type, count}` only.
+ */
+export type ScrubMode = "off" | "detect" | "redact" | "block";
+/** A finding is a COUNT by type — never a value (the load-bearing invariant). */
+export interface ScrubFinding {
+    readonly type: ScrubDetectorType;
+    readonly count: number;
+}
+export type ScrubDetectorType = "ssn" | "pan" | "email" | "phone" | "mrn";
+export interface ScrubResult {
+    /** Findings as counts-by-type, sorted by type. Empty when nothing matched. */
+    readonly findings: readonly ScrubFinding[];
+    /** The text to upload: identical to input for off/detect, masked for redact,
+     * and null for block-with-findings (nothing is uploaded). */
+    readonly text: string | null;
+    /** True when `block` mode refused because findings were present. */
+    readonly blocked: boolean;
+}
+/** The per-artifact scrub record persisted on `artifacts.scrub` (migration
+ * 00039). COUNTS ONLY — the `findings` are `{type,count}`, never a matched
+ * value (the load-bearing invariant, same as the SDK counters). `mode` records
+ * WHICH policy ran; `blocked` whether `block` mode refused the upload. */
+export interface ScrubSummary {
+    readonly mode: ScrubMode;
+    readonly blocked: boolean;
+    readonly findings: readonly ScrubFinding[];
+}
+/** Build the persisted summary from a scrub result. The only producer of the
+ * `artifacts.scrub` value, so the counts-not-values invariant lives in one
+ * place — it simply forwards `ScrubResult.findings`, which are already counts. */
+export declare function summarizeScrub(mode: ScrubMode, result: ScrubResult): ScrubSummary;
+/** Luhn checksum — the difference between "16 digits" and "a card number". */
+export declare function luhnValid(digits: string): boolean;
+/**
+ * Scan `text` and produce a scrub result for `mode`. Pure and deterministic.
+ * Never returns or logs a matched value.
+ */
+export declare function scrubContent(text: string, mode: ScrubMode): ScrubResult;
+//# sourceMappingURL=scrub.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scrub.d.ts","sourceRoot":"","sources":["../../src/artifacts/scrub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE9D,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAE1E,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C;iEAC6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;0EAG0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAED;;kFAEkF;AAClF,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,YAAY,CAEjF;AAWD,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAejD;AA0CD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA6CvE"}

package/dist/artifacts/scrub.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Scrub v1 — deterministic PII/PHI detection over artifact content BEFORE upload
+ * (E2-C chunk B, spec §3.1 / Expansion spec §7.4).
+ *
+ * Four modes, per route (default `detect` when content custody is on):
+ *   off    — no scan; upload verbatim.
+ *   detect — scan; record FINDINGS as counts-by-type; upload verbatim. The
+ *            findings are metadata (how many SSNs, how many emails), NEVER the
+ *            matched values — recording the value would move the PII into the
+ *            control-plane DB, the exact thing custody is meant to contain.
+ *   redact — scan; upload a MASKED copy; the finding counts still travel.
+ *   block  — scan; if anything is found, REFUSE the upload (counted); the
+ *            artifact keeps its metadata + hash, it simply stores no content.
+ *
+ * ── DETERMINISTIC ≠ DLP (honest limits) ───────────────────────────────────
+ * These are regex/checksum detectors, not a model. They catch well-formed SSNs,
+ * Luhn-valid PANs, emails, E.164/US phones, and labelled MRNs. They WILL miss
+ * obfuscated or free-form PII (that is scrub v2, model-assisted, out of scope).
+ * The custody docs page states this plainly — a caller must not read a clean
+ * `detect` result as a guarantee of no PII.
+ *
+ * NEVER logs a matched value. Findings are `{type, count}` only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizeScrub = summarizeScrub;
+exports.luhnValid = luhnValid;
+exports.scrubContent = scrubContent;
+/** Build the persisted summary from a scrub result. The only producer of the
+ * `artifacts.scrub` value, so the counts-not-values invariant lives in one
+ * place — it simply forwards `ScrubResult.findings`, which are already counts. */
+function summarizeScrub(mode, result) {
+    return { mode, blocked: result.blocked, findings: result.findings };
+}
+/** Luhn checksum — the difference between "16 digits" and "a card number". */
+function luhnValid(digits) {
+    const only = digits.replace(/\D/g, "");
+    if (only.length < 13 || only.length > 19)
+        return false;
+    let sum = 0;
+    let dbl = false;
+    for (let i = only.length - 1; i >= 0; i--) {
+        let d = only.charCodeAt(i) - 48;
+        if (dbl) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        dbl = !dbl;
+    }
+    return sum % 10 === 0;
+}
+// Order matters: PAN before phone/SSN so a 16-digit run is claimed as a card,
+// not split. Each pattern is intentionally conservative — a false positive that
+// masks a non-secret is cheaper than a false negative, but a pattern loose
+// enough to match ordinary prose would make `block` unusable.
+const DETECTORS = [
+    {
+        // PAN: 13–16 digits, optionally split by spaces/dashes in 4s, Luhn-valid.
+        type: "pan",
+        re: /\b(?:\d[ -]?){12,18}\d\b/g,
+        accept: luhnValid,
+        mask: "[REDACTED-PAN]",
+    },
+    {
+        // US SSN: AAA-GG-SSSS with dashes (the delimited form; bare 9-digit runs are
+        // too ambiguous to claim without a false-positive flood).
+        type: "ssn",
+        re: /\b\d{3}-\d{2}-\d{4}\b/g,
+        mask: "[REDACTED-SSN]",
+    },
+    {
+        type: "email",
+        re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+        mask: "[REDACTED-EMAIL]",
+    },
+    {
+        // Phone: E.164 (+1…) or US formats (parens/dashes/dots/spaces). Requires a
+        // grouping delimiter or leading + so bare 10-digit ids don't all match.
+        type: "phone",
+        re: /(?:\+\d{1,3}[ -]?)?(?:\(\d{3}\)|\d{3})[ .-]\d{3}[ .-]\d{4}\b/g,
+        mask: "[REDACTED-PHONE]",
+    },
+    {
+        // MRN-ish: an explicit label followed by an id. A heuristic by nature — the
+        // label is what makes it claimable without a false-positive flood.
+        type: "mrn",
+        re: /\bMRN\b\s*[:#]?\s*[A-Za-z0-9-]{4,}/gi,
+        mask: "[REDACTED-MRN]",
+    },
+];
+/**
+ * Scan `text` and produce a scrub result for `mode`. Pure and deterministic.
+ * Never returns or logs a matched value.
+ */
+function scrubContent(text, mode) {
+    if (mode === "off") {
+        return { findings: [], text, blocked: false };
+    }
+    const counts = new Map();
+    let masked = text;
+    for (const det of DETECTORS) {
+        // Fresh regex state per pass (global flag carries lastIndex otherwise).
+        const re = new RegExp(det.re.source, det.re.flags);
+        let count = 0;
+        const matched = [];
+        for (const m of text.matchAll(re)) {
+            const value = m[0];
+            if (det.accept && !det.accept(value))
+                continue;
+            count += 1;
+            if (mode === "redact")
+                matched.push(value);
+        }
+        if (count > 0) {
+            counts.set(det.type, count);
+            if (mode === "redact") {
+                for (const value of matched) {
+                    // Replace literal occurrences with the mask. split/join avoids
+                    // regex-escaping the value AND avoids putting it in any log.
+                    masked = masked.split(value).join(det.mask);
+                }
+            }
+        }
+    }
+    const findings = [...counts.entries()]
+        .map(([type, count]) => ({ type, count }))
+        .sort((a, b) => (a.type < b.type ? -1 : a.type > b.type ? 1 : 0));
+    const hasFindings = findings.length > 0;
+    if (mode === "block" && hasFindings) {
+        return { findings, text: null, blocked: true };
+    }
+    if (mode === "redact") {
+        return { findings, text: masked, blocked: false };
+    }
+    // detect (or block with no findings): upload verbatim, report counts.
+    return { findings, text, blocked: false };
+}

package/dist/artifacts/step.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@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.
+ */
+/**
+ * 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.
+ */
+export declare function step<T>(key: string, fn: () => T): T;
+//# sourceMappingURL=step.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../src/artifacts/step.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAOnD"}

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;
+}