modelrig 0.1.0 → 0.2.0

package/dist/run/dispatch.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Dispatch helpers extracted from run.ts (G-1/G-5 Phase A). The run loop is at
+ * its LOC cap, so the tool-passthrough and streaming seams live here — the same
+ * move G-2 made when it pulled applyRunRequirements/candidateFilterFromOptions
+ * into resolve.ts. Pure/near-pure: request shaping, the stream-vs-buffered
+ * dispatch fork, and the tool-call RunResult builder.
+ *
+ * Tool *execution* is never ours (spec §4.4); these helpers normalize the
+ * protocol and surface it — nothing here runs a tool.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordSearchCostRow = recordSearchCostRow;
+exports.buildAdapterRequest = buildAdapterRequest;
+exports.buildRepairAdapterRequest = buildRepairAdapterRequest;
+exports.dispatchCandidate = dispatchCandidate;
+exports.emitToolCallResult = emitToolCallResult;
+const node_crypto_1 = require("node:crypto");
+const cache_stamp_1 = require("./cache-stamp");
+const cache_handle_1 = require("./cache-handle");
+/** Record the grounding-inject search's own telemetry row (WS3): a $-only line
+ * under the synthetic "search" provider. Extracted from run.ts to keep it under
+ * the LOC cap; behaviour is byte-identical to the prior inline recorder. */
+function recordSearchCostRow(telemetry, route, effectiveTags, servedVariant, searchProviderId, costUsd) {
+    telemetry.record({
+        id: (0, node_crypto_1.randomUUID)(),
+        ts: new Date().toISOString(),
+        route: route.route,
+        routeVersion: route.version,
+        provider: "search",
+        model: searchProviderId,
+        requestedTier: "standard",
+        servedTier: "standard",
+        tokensIn: 0,
+        tokensOut: 0,
+        tokensCached: 0,
+        tokensCacheWrite: 0,
+        tokensCacheWrite1h: 0,
+        costEstimateUsd: costUsd,
+        latencyMs: 0,
+        ttfbMs: null,
+        failureClass: null,
+        attemptsJson: "{}",
+        tagsJson: JSON.stringify(effectiveTags),
+        fingerprintCell: route.fingerprintCell,
+        servedVariant,
+        repairedBy: null,
+        pricingMissing: false,
+        cacheKey: null,
+        prefixFingerprint: null,
+    });
+}
+/** Build the primary-attempt AdapterRequest — adds the grounding hint and the
+ * unified tools/toolChoice passthrough (spec §4.4). */
+function buildAdapterRequest(parts) {
+    const { route, candidate, systemPrompt, userDirective, nativeGrounded, opts } = parts;
+    // Request-path caching, two layers with a strict precedence (CE-1 spec §2.2):
+    //   (1) a CUSTOMER-supplied handle (RunOptions.cache) for the matching
+    //       provider WINS — it is a real provider-native resource the customer
+    //       owns. On gemini this is a `cachedContents/<id>`; the gemini adapter
+    //       then drops systemInstruction+tools by design (they are BAKED INTO the
+    //       cache at creation, and the API rejects setting both — gemini.ts:145).
+    //       That is correct API behavior, not a bug; the teaching doc explains it.
+    //       The WS-C gemini exclusion is untouched — it covers GENERATED keys only.
+    //   (2) else the WS-C `cache: auto` generated stamp — same pure gate the
+    //       recorder uses, so wire and telemetry never disagree (gemini excluded
+    //       here by that gate, not by prose).
+    // Absent RunOptions.cache, (1) is null and this is byte-identical to main.
+    const customerCache = (0, cache_handle_1.customerCacheHandle)(opts.cache, candidate, parts.suppressCustomerCache === true);
+    const cacheStamp = (0, cache_stamp_1.cacheStampForCandidate)(route, candidate);
+    const cacheDirective = customerCache ?? cacheStamp.request;
+    return {
+        candidate,
+        systemPrompt,
+        userPrompt: userDirective,
+        outputSchema: route.outputSchema,
+        requestedTier: route.policy.tier,
+        timeoutMs: route.policy.timeoutMs,
+        ...(cacheDirective !== null ? { cache: cacheDirective } : {}),
+        ...(route.require.includes("grounded") && nativeGrounded ? { grounding: true } : {}),
+        // CE-6: the route's declared sampling rides every primary attempt. Absent ⇒
+        // no `sampling` key ⇒ adapters keep their constants/omissions (byte-identical).
+        ...(route.policy.sampling !== undefined ? { sampling: route.policy.sampling } : {}),
+        ...(opts.tools !== undefined ? { tools: opts.tools } : {}),
+        ...(opts.toolChoice !== undefined ? { toolChoice: opts.toolChoice } : {}),
+    };
+}
+/** Build the repair-attempt AdapterRequest (no tools — repair re-asks for the
+ * structured object, never a tool call). */
+function buildRepairAdapterRequest(route, candidate, systemPrompt, repairDirective) {
+    // No cache stamp (WS-C): a repair re-asks with a DIFFERENT prompt (error
+    // feedback / repair-model framing), so it does not share the route's cacheable
+    // prefix identity. Sending the primary fingerprint as a routing key here would
+    // point dissimilar prompts at the same cache slot (openai explicitly warns
+    // against that) and would misfile the row in WS-B's warm-set. The recorder
+    // (record-attempt.ts) skips repair rows symmetrically.
+    return {
+        candidate,
+        systemPrompt,
+        userPrompt: repairDirective,
+        outputSchema: route.outputSchema,
+        requestedTier: route.policy.tier,
+        timeoutMs: route.policy.timeoutMs,
+        // CE-6: repair / JSON-extractor followups inherit the route's sampling — one
+        // knob per route, not per rung (spec §3). A repair re-ask at a different
+        // temperature than the primary would be a silent behaviour split.
+        ...(route.policy.sampling !== undefined ? { sampling: route.policy.sampling } : {}),
+    };
+}
+/**
+ * Dispatch a candidate. When a delta sink is supplied AND the adapter can
+ * stream, drain its stream — forwarding raw text deltas to the sink — and
+ * return the terminal `AdapterResult` (identical to what `call()` returns, so
+ * the run loop's cost/validation/telemetry logic is unchanged). Otherwise
+ * buffered `call()`.
+ */
+async function dispatchCandidate(adapter, req, onDelta) {
+    if (onDelta === undefined || adapter.stream === undefined) {
+        return adapter.call(req);
+    }
+    let final = null;
+    for await (const ev of adapter.stream(req)) {
+        if (ev.kind === "delta") {
+            if (ev.text !== "")
+                onDelta({ text: ev.text });
+        }
+        else {
+            final = ev.result;
+        }
+    }
+    return (final ?? {
+        ok: false,
+        failure: {
+            class: "network",
+            message: "adapter stream ended without a terminal result",
+            provider: req.candidate.provider,
+            model: req.candidate.model,
+        },
+    });
+}
+/**
+ * Record a tool-call turn and build its RunResult (spec §4.4). A tool call is
+ * NOT a schema-validated JSON turn: it records a normal (non-failure) telemetry
+ * row, then returns a result with `validated: false`, `output: null` (the caller
+ * reads `meta.toolCalls`, runs the tool, and continues the exchange), and the
+ * normalized calls surfaced on the meta. Recording goes through run.ts's own
+ * `recordAttempt` so the ledger/tenancy stamping is identical to every other row.
+ */
+function emitToolCallResult(record, parts) {
+    const { route, candidate, result, costUsd, latencyMs, attemptsByClass, servedVariant } = parts;
+    const inferenceId = record({
+        candidate,
+        servedTier: result.usage.servedTier,
+        tokensIn: result.usage.tokensIn,
+        tokensOut: result.usage.tokensOut,
+        tokensCached: result.usage.tokensCached,
+        ...(result.usage.tokensCacheWrite !== undefined
+            ? { tokensCacheWrite: result.usage.tokensCacheWrite }
+            : {}),
+        ...(result.usage.tokensCacheWrite1h !== undefined
+            ? { tokensCacheWrite1h: result.usage.tokensCacheWrite1h }
+            : {}),
+        costUsd,
+        latencyMs,
+        ...(result.usage.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
+        failure: null,
+        pricingMissing: parts.pricingMissing,
+    });
+    return {
+        output: null,
+        meta: {
+            inferenceId,
+            route: route.route,
+            routeVersion: route.version,
+            provider: candidate.provider,
+            model: candidate.model,
+            requestedTier: route.policy.tier,
+            servedTier: result.usage.servedTier,
+            tokensIn: result.usage.tokensIn,
+            tokensOut: result.usage.tokensOut,
+            tokensCached: result.usage.tokensCached,
+            costEstimateUsd: costUsd,
+            latencyMs,
+            validated: false,
+            attemptsByClass,
+            servedVariant,
+            repairedBy: null,
+            toolCalls: result.toolCalls,
+        },
+    };
+}

package/dist/run/raw.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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).
+ */
+import type { AdapterRequest, CandidateRef, ProviderId, ToolChoice, ToolDefinition } from "../types/provider";
+import type { RunResult, RunTags } from "../types/route";
+import type { RunStreamHandle } from "./stream";
+import type { TelemetryStore } from "../types/telemetry";
+/** Raw-lane request. `systemPrompt`/`userPrompt` are already flattened from the
+ * OpenAI `messages[]` by the caller; `tags` carries the caller's dimensions
+ * (the server stamps `key_ownership` here). `lane: "raw"` is stamped by this
+ * module and cannot be overridden. */
+export interface RawRunInput {
+    readonly provider: ProviderId;
+    readonly model: string;
+    /** The caller's BYOK provider secret, resolved fail-closed server-side. Held
+     * in memory for this one call, then dropped (never logged, never stored). */
+    readonly apiKey: string;
+    readonly systemPrompt: string;
+    readonly userPrompt: string;
+    readonly tags?: RunTags;
+    readonly maxOutputTokens?: number;
+    /** CE-6 sampling on the raw lane (spec §2). `temperature`/`topP` are the raw
+     * lane's exposure of the same knobs `RoutePolicy.sampling` gives the routed
+     * lane; `maxOutputTokens` above already existed. Absent ⇒ byte-identical raw
+     * dispatch (the params were previously dropped, per the header note). */
+    readonly temperature?: number;
+    readonly topP?: number;
+    readonly timeoutMs?: number;
+    readonly tools?: readonly ToolDefinition[];
+    readonly toolChoice?: ToolChoice;
+    /** CE-1 customer cache-handle pass-through on the Lane-B seam (spec §1.3
+     * success metric: "…passes its existing cachedContent handle through
+     * rig.run/runRaw"). The raw lane has exactly ONE provider (`provider` above),
+     * so the handle is unconditionally for it — no provider matching. Forwarded
+     * verbatim to `AdapterRequest.cache`; ModelRig never manages the resource. The
+     * stamped row carries the customer key with a null `prefix_fingerprint` (the
+     * raw lane runs no WS-C stamping), so provenance reads `customer` by the
+     * derivation rule. */
+    readonly cache?: {
+        readonly key: string;
+        readonly ttlSeconds?: number;
+    };
+}
+export interface RawRunDeps {
+    readonly telemetry: TelemetryStore;
+    /** Mirrors RunDeps: the conservative per-MTok rate for an unpriced model.
+     * Used only to keep `attemptCost` honest — the raw lane has no envelope, so
+     * it never charges the unpriced fallback; a missing price records `$0`. */
+    readonly unpricedRateUsdPerMTok?: number;
+}
+/** Pure raw-lane request shaping — exported for unit tests (no network). */
+export declare function buildRawRequest(candidate: CandidateRef, input: RawRunInput): AdapterRequest;
+/** Buffered raw dispatch (spec §4.2). Records telemetry, returns the RunResult,
+ * or throws `RigFailureError` on an adapter failure. */
+export declare function runRaw(deps: RawRunDeps, input: RawRunInput): Promise<RunResult>;
+/**
+ * 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.
+ */
+export declare function runRawStream(deps: RawRunDeps, input: RawRunInput): RunStreamHandle;
+//# sourceMappingURL=raw.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"raw.d.ts","sourceRoot":"","sources":["../../src/run/raw.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAYH,OAAO,KAAK,EACV,cAAc,EAGd,YAAY,EAGZ,UAAU,EACV,UAAU,EACV,cAAc,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAW,SAAS,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAkB,eAAe,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEvE;;;sCAGsC;AACtC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;iFAC6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;6EAGyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC;;;;;;;0BAOsB;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC;;+EAE2E;IAC3E,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AA0CD,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,GAAG,cAAc,CAyB3F;AA+ID;wDACwD;AACxD,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAMrF;AAcD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,eAAe,CAyClF"}

package/dist/run/raw.js

@@ -0,0 +1,286 @@
+"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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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,
+            });
+        }
+    }
+}
+/** 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
+        requestedTier: "standard",
+        timeoutMs: input.timeoutMs ?? DEFAULT_RAW_TIMEOUT_MS,
+        ...(input.maxOutputTokens !== undefined ? { maxOutputTokens: input.maxOutputTokens } : {}),
+        ...(sampling !== undefined ? { sampling } : {}),
+        ...(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: "standard",
+        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}`;
+    // 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,
+            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,
+        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: "standard",
+        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) {
+    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() {
+        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();
+        try {
+            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"}