modelrig 0.1.0 → 0.3.0

package/dist/run/raw.js

@@ -0,0 +1,363 @@
+"use strict";
+/**
+ * The RAW LANE — HTTP gateway Phase C (spec §4.2). A zero-margin BYOK
+ * passthrough: the caller names a `provider/model` and supplies (server-side,
+ * fail-closed) their own provider key; we dispatch DIRECTLY through the matching
+ * adapter and meter the call at the provider's list price. There is NO route, NO
+ * capability gate, NO validation, NO repair, NO envelope — and, by contract, NO
+ * ModelRig margin on the hop (the never-price-the-hop rule; the cost recorded is
+ * exactly `attemptCost`'s list price, which is what the verified lane records
+ * too). This module is the SDK half; the server half (BYOK resolution + the
+ * `key_ownership` tag) lives in `modelrig-server`.
+ *
+ * WHY THIS IS AN SDK PRIMITIVE, not server code: `AdapterRequest.candidate` is a
+ * branded `CandidateRef` mintable only in `run/resolve.ts`, and adapters are
+ * constructed with their key baked in — both live here. The server resolves the
+ * BYOK key fail-closed and calls `rig.runRaw`/`rig.runRawStream`; it never
+ * touches an adapter or the brand.
+ *
+ * KNOWN LIMITATIONS (flagged for the architect, not hidden):
+ *  - The adapter contract is single `systemPrompt` + `userPrompt`, not a
+ *    `messages[]` array, so a multi-turn transcript is flattened by the caller
+ *    (see `modelrig-server`'s `deriveRawPrompts`).
+ *  - CE-6: the raw lane now forwards `temperature`/`topP` (via
+ *    `AdapterRequest.sampling`) when the caller supplies them; absent, they are
+ *    still dropped and the dispatch is byte-identical to pre-CE-6. `max_tokens`
+ *    maps to `maxOutputTokens` (unchanged).
+ *  - CE-2: the raw lane exposes three more provider knobs — `grounding`
+ *    (native web grounding), `serviceTier`, and `reasoning` (thinking effort).
+ *    Each is ADDITIVE: absent ⇒ byte-identical dispatch. A DECLARED directive is
+ *    never silently dropped — `grounding`/`reasoning` on a provider that cannot
+ *    honor it are rejected fail-closed PRE-DISPATCH (`assertRawKnobsSupported`),
+ *    with no meter, no provider call, and no telemetry row. v1 support set for
+ *    both = { gemini }. `serviceTier` forwards to every adapter's tier path and
+ *    `meta.requestedTier` now reports the DECLARED tier (an honesty fix — it
+ *    previously hardcoded `"standard"`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertRawKnobsSupported = assertRawKnobsSupported;
+exports.buildRawRequest = buildRawRequest;
+exports.runRaw = runRaw;
+exports.runRawStream = runRawStream;
+const node_crypto_1 = require("node:crypto");
+const anthropic_1 = require("../adapters/anthropic");
+const deepseek_1 = require("../adapters/deepseek");
+const gemini_1 = require("../adapters/gemini");
+const grok_1 = require("../adapters/grok");
+const openai_1 = require("../adapters/openai");
+const openai_compat_1 = require("../adapters/openai-compat");
+const cost_1 = require("./cost");
+const resolve_1 = require("./resolve");
+const failures_1 = require("../types/failures");
+/** Absent a route timeout, the raw lane uses a generous default — a passthrough
+ * should not be shorter-fused than the underlying provider SDK. */
+const DEFAULT_RAW_TIMEOUT_MS = 120000;
+/** Conservative compat-host capability baseline — parity with createRig's
+ * COMPAT_STATIC. Inconsequential for raw calls (outputSchema is always null, so
+ * no JSON shaping fires), kept aligned so a raw and a routed compat call shape
+ * identically if a schema is ever added. */
+const RAW_COMPAT_PROFILE = new Set(["json_mode"]);
+/** Construct a THROWAWAY adapter bound to the caller's BYOK key for one call.
+ * Each adapter builds its provider client fresh inside `call()`/`stream()`, so
+ * a per-call instance carries no shared state and leaks no key. Exhaustive over
+ * ProviderId — a new provider forces a compile error here. */
+function buildRawAdapter(provider, apiKey) {
+    switch (provider) {
+        case "openai":
+            return (0, openai_1.createOpenAIAdapter)({ apiKey });
+        case "anthropic":
+            return (0, anthropic_1.createAnthropicAdapter)({ apiKey });
+        case "gemini":
+            return (0, gemini_1.createGeminiAdapter)({ apiKey });
+        case "grok":
+            return (0, grok_1.createGrokAdapter)({ apiKey });
+        case "deepseek":
+            return (0, deepseek_1.createDeepSeekAdapter)({ apiKey });
+        case "deepinfra":
+        case "fireworks": {
+            const host = openai_compat_1.OPENAI_COMPAT_HOSTS[provider];
+            return (0, openai_compat_1.createOpenAICompatAdapter)({
+                providerId: provider,
+                baseUrl: host.baseUrl,
+                apiKey,
+                ...(host.shapeModelId !== undefined ? { shapeModelId: host.shapeModelId } : {}),
+                capabilityProfile: () => RAW_COMPAT_PROFILE,
+            });
+        }
+    }
+}
+/** Providers that can honor a DECLARED raw-lane directive in v1 (spec §3
+ * fail-closed matrix). Native grounding and reasoning are both gemini-only
+ * today; the other adapters would silently ignore the field — exactly the bug
+ * class CE-2 makes impossible. A new-provider entry here is a deliberate,
+ * spec-gated widening, never an accident. */
+const NATIVE_GROUNDING_PROVIDERS = new Set(["gemini"]);
+const REASONING_PROVIDERS = new Set(["gemini"]);
+/**
+ * CE-2 fail-closed guard (spec §3 F1/F3). A DECLARED directive is NEVER silently
+ * dropped: `grounding`/`reasoning` on a provider that cannot honor it — or a
+ * `grounding.mode` other than the v1-supported `"native"` — throws
+ * `RigFailureError` `invariant_violation` (the existing TERMINAL class; no new
+ * FailureClass member, spec §3 rationale) BEFORE any adapter is built, any
+ * provider call is made, or any telemetry row is written. Exported so the guard
+ * is unit-testable without a network. Idempotent and side-effect-free.
+ */
+function assertRawKnobsSupported(input) {
+    const groundingMode = input.grounding?.mode;
+    if (groundingMode !== undefined) {
+        if (groundingMode !== "native") {
+            throw new failures_1.RigFailureError({
+                class: "invariant_violation",
+                message: `unsupported raw-lane grounding mode "${groundingMode}"`,
+                provider: input.provider,
+                model: input.model,
+                fixHint: 'only { mode: "native" } grounding is supported on the raw lane in v1',
+            });
+        }
+        if (!NATIVE_GROUNDING_PROVIDERS.has(input.provider)) {
+            throw new failures_1.RigFailureError({
+                class: "invariant_violation",
+                message: `native grounding on the raw lane is not supported for provider "${input.provider}"`,
+                provider: input.provider,
+                model: input.model,
+                fixHint: "native grounding on the raw lane is gemini-only in v1; remove grounding or switch provider",
+            });
+        }
+    }
+    if (input.reasoning !== undefined && !REASONING_PROVIDERS.has(input.provider)) {
+        throw new failures_1.RigFailureError({
+            class: "invariant_violation",
+            message: `reasoning control on the raw lane is not supported for provider "${input.provider}"`,
+            provider: input.provider,
+            model: input.model,
+            fixHint: "reasoning control on the raw lane is gemini-only in v1; remove reasoning or switch provider",
+        });
+    }
+}
+/** Pure raw-lane request shaping — exported for unit tests (no network). */
+function buildRawRequest(candidate, input) {
+    // CE-6: forward temperature/topP through AdapterRequest.sampling ONLY when the
+    // caller declared at least one — absent, no `sampling` key is added and the
+    // request is byte-identical to pre-CE-6. maxOutputTokens keeps its top-level
+    // channel (the adapter resolves sampling.maxOutputTokens ?? maxOutputTokens).
+    const sampling = input.temperature !== undefined || input.topP !== undefined
+        ? {
+            ...(input.temperature !== undefined ? { temperature: input.temperature } : {}),
+            ...(input.topP !== undefined ? { topP: input.topP } : {}),
+        }
+        : undefined;
+    return {
+        candidate,
+        systemPrompt: input.systemPrompt,
+        userPrompt: input.userPrompt,
+        outputSchema: null, // raw lane never validates — the product distinction
+        // CE-2 F2: forward the DECLARED tier (default "standard"); the meta/row
+        // honesty fix in finalizeRaw reports this same value, never a hardcode.
+        requestedTier: input.serviceTier ?? "standard",
+        timeoutMs: input.timeoutMs ?? DEFAULT_RAW_TIMEOUT_MS,
+        ...(input.maxOutputTokens !== undefined ? { maxOutputTokens: input.maxOutputTokens } : {}),
+        ...(sampling !== undefined ? { sampling } : {}),
+        // CE-2 F1: `{ mode: "native" }` → the adapter's native-grounding directive.
+        // Any other mode / unsupported provider never reaches here — the guard
+        // (assertRawKnobsSupported) rejects it pre-dispatch. Absent ⇒ no key added.
+        ...(input.grounding?.mode === "native" ? { grounding: true } : {}),
+        // CE-2 F3: forward reasoning verbatim; absent ⇒ no key added (byte-identical).
+        ...(input.reasoning !== undefined ? { reasoning: input.reasoning } : {}),
+        ...(input.tools !== undefined ? { tools: input.tools } : {}),
+        ...(input.toolChoice !== undefined ? { toolChoice: input.toolChoice } : {}),
+        ...(input.cache !== undefined ? { cache: input.cache } : {}),
+    };
+}
+/** Write the metered raw-lane telemetry row. Mirrors the run loop's minimal
+ * `recordSearchCostRow` shape: only load-bearing fields set, route = the
+ * `provider/model` handle the caller used, lane + key_ownership riding in
+ * `tags_json`. The exporter mirrors it on its normal cadence — no lane column,
+ * no schema change (telemetry map, 2026-08-10). */
+function recordRawRow(telemetry, p) {
+    const row = {
+        id: p.id,
+        ts: new Date().toISOString(),
+        route: p.rawModelId,
+        routeVersion: 0,
+        provider: p.provider,
+        model: p.model,
+        requestedTier: p.requestedTier,
+        servedTier: p.usage?.servedTier ?? "standard",
+        tokensIn: p.usage?.tokensIn ?? 0,
+        tokensOut: p.usage?.tokensOut ?? 0,
+        tokensCached: p.usage?.tokensCached ?? 0,
+        tokensCacheWrite: p.usage?.tokensCacheWrite ?? 0,
+        tokensCacheWrite1h: p.usage?.tokensCacheWrite1h ?? 0,
+        costEstimateUsd: p.costUsd,
+        latencyMs: p.latencyMs,
+        ttfbMs: p.usage?.ttfbMs ?? null,
+        failureClass: p.failureClass,
+        attemptsJson: "{}",
+        tagsJson: JSON.stringify(p.tags),
+        fingerprintCell: null,
+        servedVariant: null,
+        repairedBy: null,
+        pricingMissing: p.pricingMissing,
+        // CE-1: a customer cache handle (if supplied) stamps `cache_key`; the raw
+        // lane runs no WS-C stamping, so `prefix_fingerprint` is always null and the
+        // provenance rule reads any non-null key here as `customer`.
+        cacheKey: p.cacheKey ?? null,
+        prefixFingerprint: null,
+    };
+    telemetry.record(row);
+}
+/**
+ * Turn an `AdapterResult` into a RunResult, recording exactly one telemetry row.
+ * Shared by the buffered and streaming paths so cost/telemetry are byte-identical.
+ * On a failure result: record the (possibly billed) row, then throw
+ * `RigFailureError` — the server maps it to a status exactly like the slug lane.
+ */
+function finalizeRaw(deps, input, result, latencyMs) {
+    const unpricedRatePerTok = (deps.unpricedRateUsdPerMTok ?? cost_1.DEFAULT_UNPRICED_RATE_USD_PER_MTOK) / 1000000;
+    const rawModelId = `${input.provider}/${input.model}`;
+    // CE-2 F2: the declared tier is reported truthfully on the row AND the meta.
+    const requestedTier = input.serviceTier ?? "standard";
+    // lane is SDK-owned and cannot be overridden by a caller-supplied tag.
+    const tags = { ...(input.tags ?? {}), lane: "raw" };
+    if (!result.ok) {
+        let costUsd = 0;
+        let pricingMissing = false;
+        if (result.usage !== undefined) {
+            const settled = (0, cost_1.attemptCost)(input.provider, input.model, result.usage, unpricedRatePerTok);
+            costUsd = settled.costUsd;
+            pricingMissing = settled.pricingMissing;
+        }
+        recordRawRow(deps.telemetry, {
+            id: (0, node_crypto_1.randomUUID)(),
+            rawModelId,
+            provider: input.provider,
+            model: input.model,
+            ...(result.usage !== undefined ? { usage: result.usage } : {}),
+            costUsd,
+            latencyMs,
+            requestedTier,
+            failureClass: result.failure.class,
+            tags,
+            pricingMissing,
+            ...(input.cache !== undefined ? { cacheKey: input.cache.key } : {}),
+        });
+        throw new failures_1.RigFailureError(result.failure);
+    }
+    const { costUsd, pricingMissing } = (0, cost_1.attemptCost)(input.provider, input.model, result.usage, unpricedRatePerTok);
+    const id = (0, node_crypto_1.randomUUID)();
+    recordRawRow(deps.telemetry, {
+        id,
+        rawModelId,
+        provider: input.provider,
+        model: input.model,
+        usage: result.usage,
+        costUsd,
+        latencyMs,
+        requestedTier,
+        failureClass: null,
+        tags,
+        pricingMissing,
+        ...(input.cache !== undefined ? { cacheKey: input.cache.key } : {}),
+    });
+    const toolCalls = result.toolCalls;
+    const isToolTurn = toolCalls !== undefined && toolCalls.length > 0;
+    const meta = {
+        inferenceId: id,
+        route: rawModelId,
+        routeVersion: 0,
+        provider: input.provider,
+        model: input.model,
+        requestedTier,
+        servedTier: result.usage.servedTier,
+        tokensIn: result.usage.tokensIn,
+        tokensOut: result.usage.tokensOut,
+        tokensCached: result.usage.tokensCached,
+        costEstimateUsd: costUsd,
+        latencyMs,
+        validated: false, // raw is NEVER validated — the central product claim
+        attemptsByClass: {},
+        servedVariant: null,
+        repairedBy: null,
+        ...(isToolTurn ? { toolCalls } : {}),
+    };
+    return { output: isToolTurn ? null : result.text, meta };
+}
+/** Buffered raw dispatch (spec §4.2). Records telemetry, returns the RunResult,
+ * or throws `RigFailureError` on an adapter failure. */
+async function runRaw(deps, input) {
+    // CE-2 F1/F3: fail closed on an unsupported declared directive BEFORE building
+    // an adapter — no meter, no provider call, no telemetry row.
+    assertRawKnobsSupported(input);
+    const adapter = buildRawAdapter(input.provider, input.apiKey);
+    const candidate = (0, resolve_1.mintRawCandidate)(input.provider, input.model);
+    const started = Date.now();
+    const result = await adapter.call(buildRawRequest(candidate, input));
+    return finalizeRaw(deps, input, result, Date.now() - started);
+}
+function streamEndedFailure(input) {
+    return {
+        ok: false,
+        failure: {
+            class: "network",
+            message: "adapter stream ended without a terminal result",
+            provider: input.provider,
+            model: input.model,
+        },
+    };
+}
+/**
+ * Streaming raw dispatch (spec §4.3, "raw lane: true streaming, deltas passed
+ * through"). Drains the adapter's own stream when it has one, forwarding raw
+ * text deltas, and emits a single terminal `final` RunResult; adapters without
+ * `stream` (anthropic/gemini) fall back to a buffered `call()` with no deltas.
+ * There is NO terminal-validation event — that is a structured-route concept;
+ * the raw lane has no schema and the streamed bytes ARE the answer.
+ */
+function runRawStream(deps, input) {
+    let settle;
+    let fail;
+    const result = new Promise((res, rej) => {
+        settle = res;
+        fail = rej;
+    });
+    // Mark handled so an unconsumed rejection never becomes an unhandledRejection;
+    // the events iterator surfaces the same error to whoever drains it.
+    result.catch(() => { });
+    async function* events() {
+        try {
+            // CE-2 F1/F3: fail closed on an unsupported declared directive BEFORE any
+            // adapter/dispatch — surfaced through the handle (result rejects, the
+            // events iterator throws), so no meter, no provider call, no telemetry row.
+            assertRawKnobsSupported(input);
+            const adapter = buildRawAdapter(input.provider, input.apiKey);
+            const candidate = (0, resolve_1.mintRawCandidate)(input.provider, input.model);
+            const req = buildRawRequest(candidate, input);
+            const started = Date.now();
+            let adapterResult;
+            if (adapter.stream !== undefined) {
+                let final = null;
+                for await (const ev of adapter.stream(req)) {
+                    if (ev.kind === "delta") {
+                        if (ev.text !== "")
+                            yield { type: "delta", text: ev.text };
+                    }
+                    else {
+                        final = ev.result;
+                    }
+                }
+                adapterResult = final ?? streamEndedFailure(input);
+            }
+            else {
+                adapterResult = await adapter.call(req);
+            }
+            const runResult = finalizeRaw(deps, input, adapterResult, Date.now() - started);
+            settle(runResult);
+            yield { type: "final", result: runResult };
+        }
+        catch (err) {
+            fail(err);
+            throw err;
+        }
+    }
+    return { events: events(), result };
+}

package/dist/run/record-attempt.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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).
+ */
+import type { AttemptTelemetry } from "./dispatch";
+import type { ActiveRunContext } from "../artifacts/run-context";
+import type { RetryLedger } from "./retry";
+import type { RouteBundle, RunOptions, RunTags } from "../types/route";
+import type { TelemetryStore } from "../types/telemetry";
+export interface RecordAttemptDeps {
+    readonly telemetry: TelemetryStore;
+    readonly route: RouteBundle;
+    readonly ledger: RetryLedger;
+    readonly effectiveTags: RunTags;
+    readonly servedVariant: string | null;
+    /** Active run context (E2 chunk A) or null when the artifact namespace is off. */
+    readonly runCtx: ActiveRunContext | null;
+    readonly autoStepKey: string | null;
+    /** CE-1: the run's customer cache handle (RunOptions.cache), or undefined.
+     * The recorder derives the customer key from the SAME pure gate the request
+     * builder uses ({@link customerCacheHandle}), so wire and row never disagree. */
+    readonly cache?: RunOptions["cache"];
+    /** CE-1 retry-drop: candidate keys whose handle was dropped after a
+     * `cache_invalid` (live reference — the run loop mutates it between calls). A
+     * dropped candidate's later rows carry no customer key (they dispatched
+     * uncached), exactly matching the request builder's suppression. */
+    readonly droppedCacheHandle: ReadonlySet<string>;
+}
+/** 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). */
+export declare function createRecordAttempt(deps: RecordAttemptDeps): (attempt: AttemptTelemetry) => string;
+//# sourceMappingURL=record-attempt.d.ts.map

package/dist/run/record-attempt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-attempt.d.ts","sourceRoot":"","sources":["../../src/run/record-attempt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIvE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;qFAEiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IACrC;;;wEAGoE;IACpE,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAClD;AAED;;yCAEyC;AACzC,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,CA6ElG"}

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