modelrig 0.1.0 → 0.2.0

package/dist/run/record-attempt.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * The run loop's per-attempt telemetry recorder, extracted from run.ts (WS-A).
+ *
+ * run.ts sits at the 700-LOC cap; threading cache-write accounting through the
+ * row builder pushed it over, so the recorder — a self-contained mapping from
+ * an `AttemptTelemetry` to a persisted `TelemetryRow` plus the ground-truth
+ * step mirror — moves here as a factory over the loop's per-run state. Behavior
+ * is byte-identical to the former inline closure, save the additive cache
+ * fields. Keeping it separate also shrinks the run-loop conflict surface for the
+ * in-flight E4 / capture-write work (plan coordination note).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRecordAttempt = createRecordAttempt;
+const node_crypto_1 = require("node:crypto");
+const failures_1 = require("../types/failures");
+const cache_stamp_1 = require("./cache-stamp");
+const cache_handle_1 = require("./cache-handle");
+/** Build the run loop's `recordAttempt(attempt) => inferenceId` over this run's
+ * state. Records one inference row and, with an active run context, mirrors it
+ * as a ground-truth step (fail-open). */
+function createRecordAttempt(deps) {
+    const { telemetry, route, ledger, effectiveTags, servedVariant, runCtx, autoStepKey } = deps;
+    const { cache, droppedCacheHandle } = deps;
+    return function recordAttempt(attempt) {
+        // Request-path cache substrate (WS-C): derived from the SAME pure gate the
+        // dispatcher stamps the request with, so `cache_key`/`prefix_fingerprint` on
+        // the row match what was sent for this candidate. No-op (both null) unless
+        // the route opted into `cache: auto` — pre-WS-C rows are byte-identical.
+        // PRIMARY-attempt only: a repair call (repairedBy set) re-asks with a
+        // different prompt (error feedback / repair-model framing), so its prefix
+        // does not share the route's cacheable identity — stamping it would file a
+        // cold, different-prefix call under the primary fingerprint and pollute
+        // WS-B's warm-set derivation and the §5.6 streak alert. Repair rows carry
+        // neither key nor fingerprint (matching buildRepairAdapterRequest, which
+        // sends no cache directive).
+        // CE-1 (spec §2.3): derive the customer key from the SAME gate as the request
+        // builder — a matching-provider, non-suppressed handle WINS over the WS-C
+        // generated stamp. `prefix_fingerprint` is unchanged, so origin stays
+        // derivable with NO new column (customer key != fingerprint ⇒ customer;
+        // key == fingerprint ⇒ generated — cacheKeyProvenance). Both derivations
+        // skip repair rows symmetrically (their prefix differs from the route's).
+        const isPrimary = attempt.repairedBy === undefined;
+        const cacheStamp = isPrimary ? (0, cache_stamp_1.cacheStampForCandidate)(route, attempt.candidate) : null;
+        // The customer key marks rows whose REQUEST carried the handle. A terminal
+        // failure (budget_exhausted / invariant_violation) is recorded by failRun
+        // BEFORE any dispatch — the wire never carried the handle — so those rows
+        // must not claim a customer key. Terminal classes come only from failRun;
+        // adapters never return them. (A grounding-search failure is the one
+        // non-terminal pre-dispatch path, but a customer cachedContents handle and
+        // the inject rung are mutually exclusive, so it is unreachable in practice.)
+        const preDispatch = attempt.failure !== null && failures_1.TERMINAL_CLASSES.has(attempt.failure.class);
+        const dropped = droppedCacheHandle.has(`${attempt.candidate.provider} ${attempt.candidate.model}`);
+        const customer = isPrimary && !preDispatch ? (0, cache_handle_1.customerCacheHandle)(cache, attempt.candidate, dropped) : null;
+        const cacheKey = customer?.key ?? cacheStamp?.cacheKey ?? null;
+        const row = {
+            id: (0, node_crypto_1.randomUUID)(),
+            ts: new Date().toISOString(),
+            route: route.route,
+            routeVersion: route.version,
+            provider: attempt.candidate.provider,
+            model: attempt.candidate.model,
+            requestedTier: route.policy.tier,
+            servedTier: attempt.servedTier,
+            tokensIn: attempt.tokensIn,
+            tokensOut: attempt.tokensOut,
+            tokensCached: attempt.tokensCached,
+            // Cache-write accounting (WS-A) + request-path substrate (WS-C).
+            tokensCacheWrite: attempt.tokensCacheWrite ?? 0,
+            tokensCacheWrite1h: attempt.tokensCacheWrite1h ?? 0,
+            cacheKey,
+            prefixFingerprint: cacheStamp?.prefixFingerprint ?? null,
+            costEstimateUsd: attempt.costUsd,
+            latencyMs: attempt.latencyMs,
+            ttfbMs: attempt.ttfbMs ?? null,
+            failureClass: attempt.failure?.class ?? null,
+            attemptsJson: JSON.stringify(ledger.snapshot()),
+            tagsJson: JSON.stringify(effectiveTags),
+            fingerprintCell: route.fingerprintCell,
+            servedVariant,
+            repairedBy: attempt.repairedBy ?? null,
+            pricingMissing: attempt.pricingMissing ?? false,
+        };
+        telemetry.record(row);
+        // Mirror this inference into a ground-truth step attempt (fail-open — the
+        // context swallows buffer errors; the run loop is never affected).
+        if (runCtx !== null && autoStepKey !== null) {
+            runCtx.emitGroundTruthStep({
+                stepKey: autoStepKey,
+                task: route.route,
+                inferenceId: row.id,
+                startedAt: row.ts,
+                endedAt: new Date().toISOString(),
+                failureClass: row.failureClass,
+            });
+        }
+        return row.id;
+    };
+}

package/dist/run/resolve.d.ts

@@ -5,7 +5,7 @@
  * route.require, ordered by prefer:[cost] via the pricing snapshot; on a
  * retryable failure the run loop asks for the next candidate.
  */
-import type { RouteBundle } from "../types/route";
+import type { RouteBundle, RunOptions } from "../types/route";
 import type { CandidateRef, CapabilityFlag, ProviderId } from "../types/provider";
 /** Static capability stub — replaced by the probed registry in Phase 2. */
 export type CapabilityLookup = (provider: ProviderId, model: string) => ReadonlySet<CapabilityFlag>;
@@ -13,7 +13,80 @@ export interface CandidateIterator {
     /** Next eligible candidate, or null when the set is exhausted. */
     next(): CandidateRef | null;
 }
-export declare function resolveCandidates(route: RouteBundle, capabilities: CapabilityLookup, costUsdPerMTok: (provider: ProviderId, model: string) => number | null, searchAvailable?: boolean): CandidateIterator;
+/**
+ * Request-time candidate filters (G-2) — optional, applied by resolveCandidates
+ * BEFORE the prefer:[cost] sort. Distinct from route.require (capability + ZDR):
+ * these are per-run narrowings a caller passes on RunOptions. `maxPriceUsdPerMTok`
+ * reuses the same rate prefer:[cost] sorts on, so filter and sort agree.
+ */
+export interface CandidateFilter {
+    readonly maxPriceUsdPerMTok?: number;
+    readonly only?: readonly ProviderId[];
+    readonly ignore?: readonly ProviderId[];
+}
+/**
+ * SHADOW-MODE warmth-aware ordering (cache-aware-routing spec §5.5, WS-B step 8;
+ * [Briefing] "auto only after validation"). Opt-in and NON-ACTUATING: when
+ * supplied, `resolveCandidates` computes the ordering that ranking by
+ * cache-ADJUSTED effective cost WOULD produce, hands the chosen-vs-recommended
+ * comparison to `log`, and then returns the UNCHANGED list-cost order. Absent ⇒
+ * the resolver is byte-for-byte its pre-WS-B self. No behavior flip ships this
+ * mission — the shadow log is reviewed before any warmth ordering activates
+ * (post-deploy gate ledger).
+ */
+export interface WarmthShadowOptions {
+    /** Cache-adjusted effective cost for a candidate (USD/MTok), or null when
+     * unknown — computed by the caller from the derived ledger + effective-rate
+     * (kept out of the resolver so this file stays free of pricing/cache logic). */
+    readonly effectiveCostUsdPerMTok: (provider: ProviderId, model: string) => number | null;
+    /** Sink for the shadow comparison — a logger/telemetry hook. */
+    readonly log: (shadow: WarmthShadowLog) => void;
+}
+/** One shadow observation: the order the resolver ACTUALLY returned (list-cost)
+ * vs the order warmth-aware ranking would recommend, and whether they diverge. */
+export interface WarmthShadowLog {
+    readonly route: string;
+    readonly chosen: readonly {
+        readonly provider: ProviderId;
+        readonly model: string;
+    }[];
+    readonly recommended: readonly {
+        readonly provider: ProviderId;
+        readonly model: string;
+    }[];
+    readonly diverged: boolean;
+}
+export declare function resolveCandidates(route: RouteBundle, capabilities: CapabilityLookup, costUsdPerMTok: (provider: ProviderId, model: string) => number | null, searchAvailable?: boolean, filter?: CandidateFilter, shadowWarmth?: WarmthShadowOptions): CandidateIterator;
+/**
+ * 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).
+ */
+export declare function applyRunRequirements(route: RouteBundle, zeroRetention: boolean): RouteBundle;
+/** 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). */
+export declare function candidateFilterFromOptions(opts: RunOptions): CandidateFilter | undefined;
+/** 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. */
+export declare function filterSummary(opts: RunOptions): string;
+/**
+ * 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).
+ */
+export declare function mintRawCandidate(provider: ProviderId, model: string): CandidateRef;
 /**
  * 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/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/run/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAElF,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,CAC7B,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,MAAM,KACV,WAAW,CAAC,cAAc,CAAC,CAAC;AAEjC,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,IAAI,YAAY,GAAG,IAAI,CAAC;CAC7B;AAuCD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,gBAAgB,EAC9B,cAAc,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,EACtE,eAAe,UAAQ,GACtB,iBAAiB,CA6BnB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9D,YAAY,GAAG,IAAI,CAMrB"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/run/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAElF,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,CAC7B,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,MAAM,KACV,WAAW,CAAC,cAAc,CAAC,CAAC;AAEjC,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,IAAI,YAAY,GAAG,IAAI,CAAC;CAC7B;AA6CD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;oFAEgF;IAChF,QAAQ,CAAC,uBAAuB,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACzF,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;CACjD;AAED;kFACkF;AAClF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtF,QAAQ,CAAC,WAAW,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,gBAAgB,EAC9B,cAAc,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,EACtE,eAAe,UAAQ,EACvB,MAAM,CAAC,EAAE,eAAe,EACxB,YAAY,CAAC,EAAE,mBAAmB,GACjC,iBAAiB,CAkFnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,GAAG,WAAW,CAM5F;AAED;mFACmF;AACnF,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,UAAU,GAAG,eAAe,GAAG,SAAS,CAUxF;AAED;;gDAEgD;AAChD,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAElF;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9D,YAAY,GAAG,IAAI,CAMrB"}

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. */