modelrig 0.1.0 → 0.3.0

package/dist/run/resolve.js

@@ -8,6 +8,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveCandidates = resolveCandidates;
+exports.applyRunRequirements = applyRunRequirements;
+exports.candidateFilterFromOptions = candidateFilterFromOptions;
+exports.filterSummary = filterSummary;
+exports.mintRawCandidate = mintRawCandidate;
 exports.resolveDeclaredCandidate = resolveDeclaredCandidate;
 function satisfiesRequirements(route, flags, searchAvailable) {
     for (const requirement of route.require) {
@@ -38,15 +42,43 @@ function satisfiesRequirements(route, flags, searchAvailable) {
                     return false;
                 break;
             case "zero_retention":
-                // Phase 1: validated by the loader, not solvable — no capability flag
-                // exists yet (registry work, Phase 2). Declared intent only.
+                // G-3: opt-in data-governance filter. Route only to endpoints the
+                // credential-scoped registry facts designate zero-retention (claims.ts
+                // → facts.ts materializes the flag under the managed/any scope). A hard
+                // capability filter exactly like trace_visible; the empty-set case falls
+                // through to the existing no-eligible-candidate path (fail-closed — never
+                // a silent non-ZDR dispatch). The claim ceiling: "route only to
+                // zero-retention–designated endpoints," never "verified non-retention."
+                if (!flags.has("zero_retention"))
+                    return false;
                 break;
         }
     }
     return true;
 }
-function resolveCandidates(route, capabilities, costUsdPerMTok, searchAvailable = false) {
-    const eligible = route.candidates.filter((c) => satisfiesRequirements(route, capabilities(c.provider, c.model), searchAvailable));
+function resolveCandidates(route, capabilities, costUsdPerMTok, searchAvailable = false, filter, shadowWarmth) {
+    // Filter order (spec §4.1): provider only → provider ignore → capability+ZDR
+    // → maxPrice → prefer:[cost]. When `filter` is absent every step is a no-op,
+    // so the path is byte-for-byte the pre-G-2 behavior (back-compat).
+    let pool = route.candidates;
+    if (filter?.only && filter.only.length > 0) {
+        const only = new Set(filter.only);
+        pool = pool.filter((c) => only.has(c.provider));
+    }
+    if (filter?.ignore && filter.ignore.length > 0) {
+        const ignore = new Set(filter.ignore);
+        pool = pool.filter((c) => !ignore.has(c.provider));
+    }
+    let eligible = pool.filter((c) => satisfiesRequirements(route, capabilities(c.provider, c.model), searchAvailable));
+    if (filter?.maxPriceUsdPerMTok != null) {
+        const cap = filter.maxPriceUsdPerMTok;
+        // Unknown cost + a ceiling set → DROP (fail-closed: we can't prove it is
+        // under the cap; same stance as the envelope on unpriced models).
+        eligible = eligible.filter((c) => {
+            const usd = costUsdPerMTok(c.provider, c.model);
+            return usd !== null && usd <= cap;
+        });
+    }
     // prefer: [cost] — ascending, unknown cost sorts last, stable otherwise.
     // "latency" is advisory in Phase 1 (no probe data): declared order stands.
     const ordered = [...eligible];
@@ -56,6 +88,37 @@ function resolveCandidates(route, capabilities, costUsdPerMTok, searchAvailable
             return usd === null ? Number.POSITIVE_INFINITY : usd;
         };
         ordered.sort((a, b) => cost(a) - cost(b));
+        // SHADOW MODE (spec §5.5, step 8): compute what ordering by cache-ADJUSTED
+        // effective cost would recommend, log chosen-vs-recommended, and DO NOTHING
+        // ELSE. `ordered` (the list-cost order) is what we return — warmth never
+        // flips a route this mission. A no-op when `shadowWarmth` is absent, so the
+        // returned order is byte-identical to the pre-WS-B resolver.
+        //
+        // WRAPPED so shadow-mode is STRICTLY non-interfering: this is the actuation
+        // path (the only CandidateRef minter). A throwing warmth/log callback is a
+        // shadow-observation bug and must NEVER take down live candidate resolution
+        // — swallow it. `ordered` is already fixed above; nothing here can change it.
+        if (shadowWarmth !== undefined) {
+            try {
+                const effCost = (c) => {
+                    const usd = shadowWarmth.effectiveCostUsdPerMTok(c.provider, c.model);
+                    return usd === null ? Number.POSITIVE_INFINITY : usd;
+                };
+                const recommended = [...eligible].sort((a, b) => effCost(a) - effCost(b));
+                const same = recommended.length === ordered.length &&
+                    recommended.every((c, i) => c.provider === ordered[i].provider && c.model === ordered[i].model);
+                shadowWarmth.log({
+                    route: route.route,
+                    chosen: ordered.map((c) => ({ provider: c.provider, model: c.model })),
+                    recommended: recommended.map((c) => ({ provider: c.provider, model: c.model })),
+                    diverged: !same,
+                });
+            }
+            catch {
+                // Shadow observation failed — intentionally ignored. Routing proceeds on
+                // the list-cost order exactly as if no warmth had been supplied.
+            }
+        }
     }
     // THE brand site — the only place in the codebase a CandidateRef may be
     // minted. The cast below is the single sanctioned exception to the
@@ -68,6 +131,65 @@ function resolveCandidates(route, capabilities, costUsdPerMTok, searchAvailable
         },
     };
 }
+/**
+ * Per-run requirement opt-ins (G-3). A caller can demand zero-retention routing
+ * for a single run without editing the route bundle: `zero_retention` is unioned
+ * into the effective `require`, so the existing satisfiesRequirements filter, the
+ * no-eligible-candidate message, and the fail-closed empty-set path all apply
+ * unchanged. Additive only — a run opts INTO a stricter requirement, never OUT of
+ * a route's declared one (opting out would be a governance downgrade).
+ */
+function applyRunRequirements(route, zeroRetention) {
+    if (!zeroRetention || route.require.includes("zero_retention"))
+        return route;
+    return Object.freeze({
+        ...route,
+        require: Object.freeze([...route.require, "zero_retention"]),
+    });
+}
+/** Map a run's RunOptions to a CandidateFilter (G-2), or undefined when no knob
+ * is set — so the resolver takes the byte-identical pre-G-2 path (back-compat). */
+function candidateFilterFromOptions(opts) {
+    const only = opts.providers?.only;
+    const ignore = opts.providers?.ignore;
+    const max = opts.maxPriceUsdPerMTok;
+    if (max == null && (only?.length ?? 0) === 0 && (ignore?.length ?? 0) === 0)
+        return undefined;
+    return {
+        ...(max != null ? { maxPriceUsdPerMTok: max } : {}),
+        ...(only ? { only } : {}),
+        ...(ignore ? { ignore } : {}),
+    };
+}
+/** A human-readable suffix naming the binding request-time filters, for the
+ * existing no-eligible-candidate error (spec §4.3 — explainability, not a new
+ * error class). Empty when no filter is set. */
+function filterSummary(opts) {
+    const parts = [];
+    if (opts.maxPriceUsdPerMTok != null)
+        parts.push(`maxPrice ≤ $${opts.maxPriceUsdPerMTok}/MTok`);
+    if (opts.providers?.only?.length)
+        parts.push(`only=[${opts.providers.only.join(", ")}]`);
+    if (opts.providers?.ignore?.length)
+        parts.push(`ignore=[${opts.providers.ignore.join(", ")}]`);
+    return parts.length > 0 ? ` and request filters {${parts.join("; ")}}` : "";
+}
+/**
+ * Mint a CandidateRef for the RAW LANE (http-gateway spec §4.2) — a
+ * `provider/model` the caller named explicitly, dispatched at zero margin on
+ * the caller's own BYOK key with NO route and NO verified pipeline.
+ *
+ * The candidate-set invariant guards against substituting a model outside a
+ * ROUTE's declared list; a route-free, explicitly-named passthrough is outside
+ * that invariant's scope by construction (there is no list to escape). This is
+ * the ONE sanctioned brand site for it, so the "no `as CandidateRef`" grep stays
+ * clean and the brand stays centralized here. The authorization that replaces
+ * route membership lives server-side: the raw lane dispatches only after
+ * `resolveProviderKeyForCall` returns a BYOK key fail-closed (spec §4.2).
+ */
+function mintRawCandidate(provider, model) {
+    return Object.freeze({ provider, model });
+}
 /**
  * Mint a CandidateRef for a SPECIFIC declared candidate (the repair rung's
  * designated repair model — loader-validated to be in the route's candidate

package/dist/run/run.d.ts

@@ -14,6 +14,8 @@ import type { TelemetryStore } from "../types/telemetry";
 import type { CaptureStore } from "../telemetry/capture";
 import type { CapabilityLookup } from "./resolve";
 import type { SearchProvider } from "./grounding";
+import type { StreamDeltaSink } from "./dispatch";
+import type { TaskSettingsResolver } from "../settings/task-settings";
 export interface RunDeps {
     readonly routes: LoadedRoutes;
     readonly adapters: ReadonlyMap<string, ProviderAdapter>;
@@ -36,6 +38,18 @@ export interface RunDeps {
     readonly search?: SearchProvider | null;
     /** Injectable backoff sleep — tests pass a no-op. */
     readonly sleep?: (ms: number) => Promise<void>;
+    /** Streaming side-channel (G-1/G-5 Phase A). When set AND the serving
+     * adapter can stream, the primary attempt forwards raw text deltas here as
+     * they arrive; the buffered terminal result still drives validation/telemetry
+     * unchanged. `rig.runStream()` wires this; `rig.run()` leaves it undefined. */
+    readonly onStreamDelta?: StreamDeltaSink;
+    /** Control-plane task-settings resolver (settings-plane §1.5) — present only
+     * in api mode. The capture-WRITE gate consults it: `effectiveCapture` lets a
+     * control-plane flip WIN over the YAML `capture:` flag (a console flip turns
+     * capture on/off with no redeploy), and the task's scrub setting governs
+     * content before a capture row is written. null/omitted = local-only (the
+     * YAML flag governs, no per-task scrub policy). */
+    readonly settings?: TaskSettingsResolver | null;
 }
 export declare function run(deps: RunDeps, routeName: string, opts: RunOptions): Promise<RunResult>;
 //# sourceMappingURL=run.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAMrD,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,mBAAmB,CAAC;AAGvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAsC,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AASlD,OAAO,KAAK,EAAE,cAAc,EAAoC,MAAM,aAAa,CAAC;AAGpF,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC,+EAA+E;IAC/E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;gDAE4C;IAC5C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC;2EACuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACxC;;0BAEsB;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAwFD,wBAAsB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAwiBhG"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAMrD,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,mBAAmB,CAAC;AAGvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAsC,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAQlD,OAAO,KAAK,EAAE,cAAc,EAAoC,MAAM,aAAa,CAAC;AASpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC,+EAA+E;IAC/E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;gDAE4C;IAC5C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC;2EACuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACxC;;0BAEsB;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;mFAG+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,eAAe,CAAC;IACzC;;;;;uDAKmD;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACjD;AAsED,wBAAsB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAoiBhG"}

package/dist/run/stream.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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()`.
+ */
+import type { RunDeps } from "./run";
+import type { RunOptions, RunResult } from "../types/route";
+export type RunStreamEvent = {
+    readonly type: "delta";
+    readonly text: string;
+} | {
+    readonly type: "final";
+    readonly result: RunResult;
+};
+export interface RunStreamOptions extends RunOptions {
+    /** Buffered mode (spec §4.3): suppress token deltas and emit only the
+     * terminal (validated) result. Default false = stream-then-final. */
+    readonly buffered?: boolean;
+}
+export interface RunStreamHandle {
+    /** Async-iterable of `delta` events then a single `final`. Re-throws the
+     * run's error if it failed (after any deltas already emitted). */
+    readonly events: AsyncIterable<RunStreamEvent>;
+    /** The terminal RunResult, or a rejection with the run's typed failure.
+     * Resolves with the same object carried by the `final` event. */
+    readonly result: Promise<RunResult>;
+}
+/**
+ * Drive a route with token streaming. Returns an async-iterable of events plus
+ * a `result` promise for callers that only want the terminal value.
+ */
+export declare function runStream(deps: RunDeps, routeName: string, opts: RunStreamOptions): RunStreamHandle;
+//# sourceMappingURL=stream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/run/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE5D,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAE3D,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD;yEACqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B;sEACkE;IAClE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC/C;qEACiE;IACjE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CACrC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,gBAAgB,GACrB,eAAe,CA6DjB"}

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.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/run/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,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;AAsBD,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CA6BlF"}
+{"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

@@ -4,15 +4,14 @@
  * Phase 1 checks schema conformance; value-accuracy gates arrive with the
  * bake-off in Phase 3.
  */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateOutput = validateOutput;
-const ajv_1 = __importDefault(require("ajv"));
-// Mirrors the production probe harness: new Ajv({ strict: false, allErrors:
-// true }) — the v3 schemas trip ajv strict-mode warnings by design.
-const ajv = new ajv_1.default({ strict: false, allErrors: true, allowUnionTypes: true });
+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. */

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