modelrig 0.8.1 → 0.10.0

package/dist/run/raw-finalize.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Raw-lane finalize + telemetry (spec §4.2/§4.3), extracted from raw.ts (Unified
+ * Route U4) to keep raw.ts under the 700-LOC cap (dev-rule P1). PURE MOVE in
+ * Phase A — `prepareRawStep`, `finalizeRaw`, `recordRawRow`, and the tier-aware
+ * timeout fixHint are byte-identical to their former raw.ts definitions.
+ *
+ * Raw-lane no-hard-hot-path-dependency invariant preserved: this module imports
+ * cost/telemetry/run-context/attempt-meta helpers and the native-search cost
+ * recorder — NO route/registry/capability-gate dependency.
+ */
+import { type ActiveRunContext } from "../artifacts/run-context";
+import type { AdapterResult, ServiceTier } from "../types/provider";
+import type { RunResult } from "../types/route";
+import type { RawRunDeps, RawRunInput } from "./raw";
+/** R1 — the teaching `fixHint` attached to a `timeout` failure on the raw lane:
+ * it names the elapsed budget, the tier, that tier's advertised target, and the
+ * two fixes (raise `timeoutMs`, or drop to `standard`). Built from
+ * `RAW_TIMEOUT_DEFAULT_MS` so the default it quotes can never drift. */
+export declare function rawTimeoutFixHint(input: RawRunInput, tier: ServiceTier): string;
+/** The active-run-context binding a raw call resolves ONCE at entry (the ALS
+ * boundary — read synchronously before the stream generator defers), so
+ * `finalizeRaw` can mirror the call into a ground-truth step (G1 spec §4). Null
+ * when there is no `run.start` on this path (the common, uninstrumented case). */
+export interface RawStepContext {
+    readonly runCtx: ActiveRunContext;
+    readonly stepKey: string;
+    readonly startedAtIso: string;
+}
+/**
+ * Read the ambient run context at the ENTRY of a raw call (spec §4) and, if
+ * present, resolve the step key `input.stepKey ?? tags.step ?? provider/model#n`
+ * (validated) — so `finalizeRaw` records a ground-truth step exactly like the
+ * routed lane. Also runs the required-dimension hygiene warning (spec §4),
+ * unconditionally, as the routed lane does. Fail-open: no context ⇒ null and no
+ * step is ever recorded; the dispatch is byte-identical to pre-G1.
+ */
+export declare function prepareRawStep(deps: RawRunDeps, input: RawRunInput): RawStepContext | null;
+/**
+ * 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.
+ *
+ * G1: when a run context was captured at entry (`step`), a ground-truth step is
+ * emitted after the telemetry row on BOTH branches (success and failure) —
+ * fail-open, so a buffer error there never affects the returned result. No
+ * artifact CONTENT is written on the raw lane (spec F3): steps are metadata.
+ */
+export declare function finalizeRaw(deps: RawRunDeps, input: RawRunInput, result: AdapterResult, latencyMs: number, step: RawStepContext | null): RunResult;
+//# sourceMappingURL=raw-finalize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"raw-finalize.d.ts","sourceRoot":"","sources":["../../src/run/raw-finalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,aAAa,EAGb,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAW,SAAS,EAAW,MAAM,gBAAgB,CAAC;AAKlE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAErD;;;wEAGwE;AACxE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAS/E;AA6ED;;;kFAGkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,cAAc,GAAG,IAAI,CAU1F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,cAAc,GAAG,IAAI,GAC1B,SAAS,CA6JX"}

package/dist/run/raw-finalize.js

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * Raw-lane finalize + telemetry (spec §4.2/§4.3), extracted from raw.ts (Unified
+ * Route U4) to keep raw.ts under the 700-LOC cap (dev-rule P1). PURE MOVE in
+ * Phase A — `prepareRawStep`, `finalizeRaw`, `recordRawRow`, and the tier-aware
+ * timeout fixHint are byte-identical to their former raw.ts definitions.
+ *
+ * Raw-lane no-hard-hot-path-dependency invariant preserved: this module imports
+ * cost/telemetry/run-context/attempt-meta helpers and the native-search cost
+ * recorder — NO route/registry/capability-gate dependency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rawTimeoutFixHint = rawTimeoutFixHint;
+exports.prepareRawStep = prepareRawStep;
+exports.finalizeRaw = finalizeRaw;
+const node_crypto_1 = require("node:crypto");
+const cost_1 = require("./cost");
+const raw_defaults_1 = require("./raw-defaults");
+const raw_request_1 = require("./raw-request");
+const raw_search_cost_1 = require("./raw-search-cost");
+const raw_schema_1 = require("./raw-schema");
+const failures_1 = require("../types/failures");
+const run_context_1 = require("../artifacts/run-context");
+const manifest_1 = require("../routes/manifest");
+const attempt_meta_1 = require("../telemetry/attempt-meta");
+const telemetry_row_1 = require("./telemetry-row");
+/** R1 — the teaching `fixHint` attached to a `timeout` failure on the raw lane:
+ * it names the elapsed budget, the tier, that tier's advertised target, and the
+ * two fixes (raise `timeoutMs`, or drop to `standard`). Built from
+ * `RAW_TIMEOUT_DEFAULT_MS` so the default it quotes can never drift. */
+function rawTimeoutFixHint(input, tier) {
+    const deadlineSec = (0, raw_request_1.resolveRawTimeoutMs)(input) / 1000;
+    const budgetMin = raw_defaults_1.RAW_TIMEOUT_DEFAULT_MS[tier] / 60000;
+    const defaultSec = raw_defaults_1.RAW_TIMEOUT_DEFAULT_MS[tier] / 1000;
+    // Only flex has a cheaper-latency tier to drop to; at standard/priority the
+    // only fix is a longer deadline (never tell a caller to switch to the tier
+    // they are already on).
+    const tail = tier === "flex" ? ' or use serviceTier: "standard"' : "";
+    return `timed out at the ${deadlineSec}s deadline at tier ${tier} — ${tier} targets up to ${budgetMin} min; raise timeoutMs (default ${defaultSec}s)${tail}`;
+}
+/** 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) {
+    // U4: assembled by the ONE shared builder (./telemetry-row.ts). The raw lane's
+    // former hardcodes are now EXPLICIT inputs to the shared builder rather than
+    // literals hidden here: routeVersion 0, attemptsJson "{}", servedVariant null,
+    // rung "primary", attemptSeq 1, candidateIndex 0. `lane: "raw"` rides p.tags.
+    const row = (0, telemetry_row_1.buildTelemetryRow)({
+        id: p.id,
+        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: "{}",
+        // Rung tag (R1 review, F1): the raw lane is a single primary dispatch. Raw
+        // rows carry `lane: "raw"` (in p.tags) and are excluded from route rollups,
+        // but every row gets a rung for a uniform contract.
+        baseTags: p.tags,
+        rung: "primary",
+        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,
+        // Ladder key (spec §2.1 R0): raw lane = one row per call, seq 1, index 0.
+        callId: p.callId,
+        attemptSeq: 1,
+        candidateIndex: 0,
+        meta: p.meta,
+    });
+    telemetry.record(row);
+}
+/**
+ * Read the ambient run context at the ENTRY of a raw call (spec §4) and, if
+ * present, resolve the step key `input.stepKey ?? tags.step ?? provider/model#n`
+ * (validated) — so `finalizeRaw` records a ground-truth step exactly like the
+ * routed lane. Also runs the required-dimension hygiene warning (spec §4),
+ * unconditionally, as the routed lane does. Fail-open: no context ⇒ null and no
+ * step is ever recorded; the dispatch is byte-identical to pre-G1.
+ */
+function prepareRawStep(deps, input) {
+    const runCtx = (0, run_context_1.getActiveRunContext)();
+    // Warn on the EFFECTIVE tags: an auto-stamped run_id (RC-1) is not missing.
+    (0, manifest_1.warnMissingRequiredDimensions)(deps.manifest ?? null, (0, run_context_1.withRunIdTag)(input.tags ?? {}, runCtx));
+    if (runCtx === null)
+        return null;
+    const rawModelId = `${input.provider}/${input.model}`;
+    const stepKey = (0, run_context_1.resolveStepKey)(input.stepKey, input.tags?.step, () => runCtx.nextStepKey(rawModelId));
+    return { runCtx, stepKey, startedAtIso: new Date().toISOString() };
+}
+/**
+ * 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.
+ *
+ * G1: when a run context was captured at entry (`step`), a ground-truth step is
+ * emitted after the telemetry row on BOTH branches (success and failure) —
+ * fail-open, so a buffer error there never affects the returned result. No
+ * artifact CONTENT is written on the raw lane (spec F3): steps are metadata.
+ */
+function finalizeRaw(deps, input, result, latencyMs, step) {
+    const unpricedRatePerTok = (deps.unpricedRateUsdPerMTok ?? cost_1.DEFAULT_UNPRICED_RATE_USD_PER_MTOK) / 1000000;
+    const rawModelId = `${input.provider}/${input.model}`;
+    // One call_id for this raw invocation — shared by the (single) recorded row and
+    // the returned meta (spec §2.1 R0).
+    const callId = (0, node_crypto_1.randomUUID)();
+    // CE-2 F2: the declared tier is reported truthfully on the row AND the meta.
+    const requestedTier = input.serviceTier ?? "standard";
+    // RC-1: `run_id` from the ambient run (caller's value wins); lane is SDK-owned
+    // and cannot be overridden by a caller-supplied tag.
+    // GS-1: `tags.step` from the ambient step key (step.stepKey = caller's stepKey
+    // ?? tags.step ?? the auto provider/model#n key) when a run is active and the
+    // caller set none — spread FIRST so a caller value wins, and omitted entirely
+    // outside a run context so the row stays byte-identical (parity with RC-1).
+    const stepTag = step !== null ? { step: step.stepKey } : {};
+    const tags = { ...stepTag, ...(0, run_context_1.withRunIdTag)(input.tags ?? {}, step?.runCtx ?? null), lane: "raw" };
+    // WI-1 (spec §2, §6.3 lane parity): the attempt envelope, built by the SAME
+    // producer + rendered-request canonicalization the routed lane uses. R2: a
+    // declared `responseSchema` joins the input_hash exactly as a route schema
+    // does (lane parity), and its canonical sha rides `meta.schema_sha`; absent ⇒
+    // schema null and no key — byte-identical to pre-R2.
+    const schema = input.responseSchema ?? null;
+    const schemaSha = schema !== null ? (0, raw_schema_1.rawSchemaSha)(schema) : undefined;
+    const declaredToolNames = input.tools?.map((t) => t.function.name);
+    const rawMeta = (usage) => (0, attempt_meta_1.summarizeAttemptMeta)({
+        ...(result.meta !== undefined ? { adapterMeta: result.meta } : {}),
+        renderedRequest: (0, attempt_meta_1.renderRequestForHash)({ system: input.systemPrompt, user: input.userPrompt, schema }),
+        outputText: result.ok ? result.text : null,
+        ...(declaredToolNames !== undefined ? { declaredToolNames } : {}),
+        ...(schemaSha !== undefined ? { schemaSha } : {}),
+        provider: input.provider,
+        model: input.model,
+        ...(usage !== undefined ? { usage } : {}),
+    });
+    // G1: mirror this raw inference into a ground-truth step (parity with the
+    // routed lane's record-attempt). task = tags.step ?? provider/model (spec F1).
+    // Fail-open is handled inside emitGroundTruthStep (buffer errors are swallowed).
+    const emitStep = (inferenceId, failureClass) => {
+        if (step === null)
+            return;
+        step.runCtx.emitGroundTruthStep({
+            stepKey: step.stepKey,
+            task: input.tags?.step ?? rawModelId,
+            inferenceId,
+            startedAt: step.startedAtIso,
+            endedAt: new Date().toISOString(),
+            failureClass,
+        });
+    };
+    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;
+        }
+        const failId = (0, node_crypto_1.randomUUID)();
+        recordRawRow(deps.telemetry, {
+            id: failId,
+            rawModelId,
+            provider: input.provider,
+            model: input.model,
+            ...(result.usage !== undefined ? { usage: result.usage } : {}),
+            costUsd,
+            latencyMs,
+            requestedTier,
+            failureClass: result.failure.class,
+            tags,
+            pricingMissing,
+            callId,
+            meta: rawMeta(result.usage),
+            ...(input.cache !== undefined ? { cacheKey: input.cache.key } : {}),
+        });
+        emitStep(failId, result.failure.class);
+        // R1: a raw-lane timeout is the #245 footgun — attach the tier-aware teaching
+        // hint (the customer is looking at THIS error). Any other failure surfaces
+        // unchanged. Overrides any adapter-set hint: the tier + budget is the fix.
+        if (result.failure.class === "timeout") {
+            throw new failures_1.RigFailureError({
+                ...result.failure,
+                fixHint: rawTimeoutFixHint(input, requestedTier),
+            });
+        }
+        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)();
+    const toolCalls = result.toolCalls;
+    const isToolTurn = toolCalls !== undefined && toolCalls.length > 0;
+    // R2 (issue #6): a declared responseSchema is checked HERE, client-side, on a
+    // text turn (a tool-call turn is not schema-validated — parity with the run
+    // loop). A miss is a BILLED row of class content_invalid (the provider served
+    // and charged) + a thrown RigFailureError; the raw lane never repairs/retries.
+    const schemaOutcome = schema !== null && !isToolTurn ? (0, raw_schema_1.validateRawOutput)(schema, result.text) : { ok: true };
+    recordRawRow(deps.telemetry, {
+        id,
+        rawModelId,
+        provider: input.provider,
+        model: input.model,
+        usage: result.usage,
+        costUsd,
+        latencyMs,
+        requestedTier,
+        failureClass: schemaOutcome.ok ? null : "content_invalid",
+        tags,
+        pricingMissing,
+        callId,
+        meta: rawMeta(result.usage),
+        ...(input.cache !== undefined ? { cacheKey: input.cache.key } : {}),
+    });
+    emitStep(id, schemaOutcome.ok ? null : "content_invalid");
+    if (!schemaOutcome.ok)
+        throw new failures_1.RigFailureError((0, raw_schema_1.rawSchemaMismatchFailure)(input, schemaOutcome.errors));
+    // NWS N3: a NATIVE-grounded success writes one extra, legible `rung:"search"`
+    // cost row (the `web_search` surcharge) beside the token row — ZERO DDL,
+    // recorder in raw-search-cost.ts. Gated on native grounding (a non-grounded
+    // success writes none); searchCalls from the Responses usage, else 1 (disclosed).
+    if (input.grounding?.mode === "native") {
+        (0, raw_search_cost_1.recordRawSearchCostRow)(deps.telemetry, { provider: input.provider, rawModelId, tags, callId, searchCalls: result.searchCalls ?? 1 });
+    }
+    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,
+        callId,
+        ...(isToolTurn ? { toolCalls } : {}),
+        // NWS N2: first native citations on the raw lane (url_citation shape; a
+        // grounded response may carry an empty array — surfaced, never thrown). Absent
+        // on every non-grounded call ⇒ key omitted (byte-identical meta).
+        ...(result.citations !== undefined ? { citations: result.citations } : {}),
+    };
+    return { output: isToolTurn ? null : result.text, meta };
+}

package/dist/run/raw-knobs.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Raw-lane fail-closed knob guard (CE-2/CE-9, spec §3 F1/F3, CE-9 R1/R2/R4),
+ * extracted from raw.ts (Unified Route U4) to keep raw.ts under the 700-LOC cap
+ * (dev-rule P1). PURE MOVE — behavior-preserving: the guard's checks, throw
+ * conditions, and teaching fixHints are byte-identical to the former inline
+ * `assertRawKnobsSupported`. Re-exported from ./raw so existing importers
+ * (`import { assertRawKnobsSupported } from "./raw"`) are unchanged.
+ *
+ * The raw lane's no-hard-hot-path-dependency invariant is preserved: this module
+ * pulls in only the capability vocabulary (`raw-support.ts`) and failure types —
+ * no route/registry/capability-gate dependency.
+ */
+import type { RawRunInput } from "./raw";
+/**
+ * CE-2/CE-9 fail-closed guard (spec §3 F1/F3, CE-9 R1/R2/R4). A DECLARED
+ * directive is NEVER silently dropped: a `grounding`/`responseFormat` on a
+ * provider that cannot honor it, a `reasoning` on a provider with NO effort
+ * control (deepseek/anthropic), or a `grounding.mode` other than the
+ * v1-supported `"native"` throws `RigFailureError` `invariant_violation` (the
+ * existing TERMINAL class; no new FailureClass member) BEFORE any adapter is
+ * built, any provider call is made, or any telemetry row is written.
+ *
+ * The support facts come from `RAW_KNOB_SUPPORT` (run/raw-support.ts) — the ONE
+ * table the published docs matrix also reads, so the guard and the docs can
+ * never disagree (R5). What the guard does NOT reject (and why):
+ *  - reasoning on openai/deepinfra/fireworks is FORWARDED verbatim
+ *    (`kind: "forward"`) and the provider enforces — a rejection is classified
+ *    teachably by the adapter (no per-model allowlist, R1).
+ *  - reasoning on grok is a DISCLOSED coarsening (`kind: "coarsen"`).
+ *  - reasoning on gemini is model-gated (`kind: "model-gated"`) — the adapter
+ *    rejects a non-thinking model (`geminiReasoningUnsupported`).
+ * Exported so the guard is unit-testable without a network. Idempotent and
+ * side-effect-free.
+ */
+export declare function assertRawKnobsSupported(input: RawRunInput): void;
+//# sourceMappingURL=raw-knobs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"raw-knobs.d.ts","sourceRoot":"","sources":["../../src/run/raw-knobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAkEhE"}

package/dist/run/raw-knobs.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Raw-lane fail-closed knob guard (CE-2/CE-9, spec §3 F1/F3, CE-9 R1/R2/R4),
+ * extracted from raw.ts (Unified Route U4) to keep raw.ts under the 700-LOC cap
+ * (dev-rule P1). PURE MOVE — behavior-preserving: the guard's checks, throw
+ * conditions, and teaching fixHints are byte-identical to the former inline
+ * `assertRawKnobsSupported`. Re-exported from ./raw so existing importers
+ * (`import { assertRawKnobsSupported } from "./raw"`) are unchanged.
+ *
+ * The raw lane's no-hard-hot-path-dependency invariant is preserved: this module
+ * pulls in only the capability vocabulary (`raw-support.ts`) and failure types —
+ * no route/registry/capability-gate dependency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertRawKnobsSupported = assertRawKnobsSupported;
+const failures_1 = require("../types/failures");
+const raw_support_1 = require("./raw-support");
+const raw_schema_1 = require("./raw-schema");
+/**
+ * CE-2/CE-9 fail-closed guard (spec §3 F1/F3, CE-9 R1/R2/R4). A DECLARED
+ * directive is NEVER silently dropped: a `grounding`/`responseFormat` on a
+ * provider that cannot honor it, a `reasoning` on a provider with NO effort
+ * control (deepseek/anthropic), or a `grounding.mode` other than the
+ * v1-supported `"native"` throws `RigFailureError` `invariant_violation` (the
+ * existing TERMINAL class; no new FailureClass member) BEFORE any adapter is
+ * built, any provider call is made, or any telemetry row is written.
+ *
+ * The support facts come from `RAW_KNOB_SUPPORT` (run/raw-support.ts) — the ONE
+ * table the published docs matrix also reads, so the guard and the docs can
+ * never disagree (R5). What the guard does NOT reject (and why):
+ *  - reasoning on openai/deepinfra/fireworks is FORWARDED verbatim
+ *    (`kind: "forward"`) and the provider enforces — a rejection is classified
+ *    teachably by the adapter (no per-model allowlist, R1).
+ *  - reasoning on grok is a DISCLOSED coarsening (`kind: "coarsen"`).
+ *  - reasoning on gemini is model-gated (`kind: "model-gated"`) — the adapter
+ *    rejects a non-thinking model (`geminiReasoningUnsupported`).
+ * Exported so the guard is unit-testable without a network. Idempotent and
+ * side-effect-free.
+ */
+function assertRawKnobsSupported(input) {
+    const support = raw_support_1.RAW_KNOB_SUPPORT[input.provider];
+    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 (!support.grounding.supported) {
+            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 supported on ${(0, raw_support_1.groundingSupportedProviders)().join(", ")} only; remove grounding or switch provider`,
+            });
+        }
+    }
+    if (input.reasoning !== undefined && support.reasoning.kind === "fail-closed") {
+        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,
+            // Provider-specific teaching straight from the matrix (deepseek →
+            // deepseek-reasoner; anthropic → extended thinking unwired).
+            fixHint: support.reasoning.fixHint ??
+                "reasoning control is not available for this provider on the raw lane; remove reasoning",
+        });
+    }
+    if (input.responseFormat !== undefined && !support.responseFormat.supported) {
+        throw new failures_1.RigFailureError({
+            class: "invariant_violation",
+            message: `responseFormat on the raw lane is not supported for provider "${input.provider}"`,
+            provider: input.provider,
+            model: input.model,
+            fixHint: `responseFormat: "json_object" on the raw lane is supported on ${(0, raw_support_1.responseFormatSupportedProviders)().join(", ")} only; remove responseFormat or switch provider`,
+        });
+    }
+    // R2 (issue #6): a declared JSON Schema on a provider whose adapter has no
+    // NATIVE schema path (deepseek, the compat hosts) is rejected here — it would
+    // otherwise be silently dropped or degraded to json_object. Provider list from
+    // the matrix, so widening a cell widens the error. Then the SHAPE check (plain
+    // object, compiles, not alongside responseFormat) — raw-schema.ts.
+    if (input.responseSchema !== undefined && !support.responseSchema.supported) {
+        throw new failures_1.RigFailureError({
+            class: "invariant_violation",
+            message: `responseSchema on the raw lane is not supported for provider "${input.provider}"`,
+            provider: input.provider,
+            model: input.model,
+            fixHint: `responseSchema on the raw lane is supported on ${(0, raw_support_1.responseSchemaSupportedProviders)().join(", ")} only (native structured output); remove responseSchema, use responseFormat: "json_object" (mime-shaping only), or switch provider`,
+        });
+    }
+    (0, raw_schema_1.assertRawResponseSchemaShape)(input);
+}

package/dist/run/raw-request.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Raw-lane request shaping (spec §4.2), extracted from raw.ts (Unified Route U4)
+ * to keep raw.ts under the 700-LOC cap (dev-rule P1). PURE MOVE — the effective
+ * timeout resolution and the `AdapterRequest` shaping are byte-identical to the
+ * former inline `resolveRawTimeoutMs` / `buildRawRequest`. `buildRawRequest` is
+ * re-exported from ./raw so existing importers are unchanged.
+ *
+ * No route/registry/capability-gate dependency (raw-lane invariant preserved):
+ * only the tier-aware timeout table and provider types.
+ */
+import type { AdapterRequest, CandidateRef } from "../types/provider";
+import type { RawRunInput } from "./raw";
+/**
+ * R1 — resolve the effective raw-lane timeout. An explicit `timeoutMs` always
+ * wins; absent, the fallback is TIER-AWARE (`RAW_TIMEOUT_DEFAULT_MS`), because a
+ * passthrough should not be shorter-fused than the tier it advertises (a flex
+ * grounded prompt needs minutes, not the old 120 s). No pre-dispatch rejection —
+ * a short explicit timeout is a choice, and the teaching arrives on the first
+ * `timeout` failure (`rawTimeoutFixHint`), which is when the caller is looking.
+ */
+export declare function resolveRawTimeoutMs(input: RawRunInput): number;
+/** Pure raw-lane request shaping — exported for unit tests (no network). */
+export declare function buildRawRequest(candidate: CandidateRef, input: RawRunInput): AdapterRequest;
+//# sourceMappingURL=raw-request.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"raw-request.d.ts","sourceRoot":"","sources":["../../src/run/raw-request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEzC;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAE9D;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,GAAG,cAAc,CA0C3F"}

package/dist/run/raw-request.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Raw-lane request shaping (spec §4.2), extracted from raw.ts (Unified Route U4)
+ * to keep raw.ts under the 700-LOC cap (dev-rule P1). PURE MOVE — the effective
+ * timeout resolution and the `AdapterRequest` shaping are byte-identical to the
+ * former inline `resolveRawTimeoutMs` / `buildRawRequest`. `buildRawRequest` is
+ * re-exported from ./raw so existing importers are unchanged.
+ *
+ * No route/registry/capability-gate dependency (raw-lane invariant preserved):
+ * only the tier-aware timeout table and provider types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRawTimeoutMs = resolveRawTimeoutMs;
+exports.buildRawRequest = buildRawRequest;
+const raw_defaults_1 = require("./raw-defaults");
+/**
+ * R1 — resolve the effective raw-lane timeout. An explicit `timeoutMs` always
+ * wins; absent, the fallback is TIER-AWARE (`RAW_TIMEOUT_DEFAULT_MS`), because a
+ * passthrough should not be shorter-fused than the tier it advertises (a flex
+ * grounded prompt needs minutes, not the old 120 s). No pre-dispatch rejection —
+ * a short explicit timeout is a choice, and the teaching arrives on the first
+ * `timeout` failure (`rawTimeoutFixHint`), which is when the caller is looking.
+ */
+function resolveRawTimeoutMs(input) {
+    return input.timeoutMs ?? raw_defaults_1.RAW_TIMEOUT_DEFAULT_MS[input.serviceTier ?? "standard"];
+}
+/** 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,
+        // R2 (issue #6): a declared `responseSchema` rides the adapters' existing
+        // NATIVE schema path (outputSchema) — gemini responseJsonSchema, openai/grok
+        // strict json_schema, anthropic forced tool. Absent ⇒ null, byte-identical:
+        // the raw lane stays unvalidated unless the caller declares a schema.
+        outputSchema: input.responseSchema ?? null,
+        // 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",
+        // R1: tier-aware default (RAW_TIMEOUT_DEFAULT_MS); explicit timeoutMs wins.
+        timeoutMs: resolveRawTimeoutMs(input),
+        ...(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 } : {}),
+        // CE-9 R4: forward the json_object directive verbatim; absent ⇒ no key added
+        // (byte-identical). An unsupported provider (anthropic) never reaches here —
+        // the guard (assertRawKnobsSupported) rejects it pre-dispatch.
+        ...(input.responseFormat !== undefined ? { responseFormat: input.responseFormat } : {}),
+        ...(input.tools !== undefined ? { tools: input.tools } : {}),
+        ...(input.toolChoice !== undefined ? { toolChoice: input.toolChoice } : {}),
+        ...(input.cache !== undefined ? { cache: input.cache } : {}),
+    };
+}

package/dist/run/raw-schema.d.ts

@@ -0,0 +1,76 @@
+/**
+ * R2 (GitLab issue #6) — `responseSchema` on the raw lane: the schema helpers
+ * the guard (raw-knobs.ts) and the finalize path (raw-finalize.ts) share.
+ *
+ * What the knob IS: a JSON Schema the caller declares on `rig.runRaw`. It is
+ * forwarded as the provider's NATIVE structured-output directive (the adapters'
+ * existing `AdapterRequest.outputSchema` path — gemini `responseJsonSchema`,
+ * openai/grok strict `json_schema`, anthropic a forced tool call) AND the
+ * returned text is checked client-side by the SAME Ajv instance the routed lane
+ * uses (`createModelrigAjv`, 2020-12 + draft-07). A miss is `content_invalid`.
+ *
+ * What the knob is NOT: a ladder. The raw lane never repairs, never retries,
+ * and never falls through — a schema miss is a terminal, billed `content_invalid`
+ * row and a thrown `RigFailureError` whose `fixHint` names the first errors. F4
+ * is narrowed, not reversed: `meta.validated` stays `false` because no ladder
+ * stands behind the check (routing-docs.ts B2 states the boundary).
+ *
+ * Why its own file: raw-finalize.ts and raw-knobs.ts both sit under the 700-LOC
+ * cap (P1) and neither should pull Ajv + hashing into its header story; this
+ * module keeps the raw lane's no-route/registry dependency invariant (it imports
+ * only the shared Ajv factory and failure types).
+ */
+import type { RigFailure } from "../types/failures";
+import type { ProviderId } from "../types/provider";
+/** Canonical JSON — object keys sorted recursively, arrays in order, no
+ * whitespace — so two authored spellings of ONE schema hash identically and a
+ * reordered key never reads as drift. Pure; exported for the hash tests. */
+export declare function canonicalJson(value: unknown): string;
+/** `sha256:<hex>` of the canonical schema JSON — the value stamped on
+ * `inferences.meta.schema_sha` (a hash, never content; meta-safe by shape). */
+export declare function rawSchemaSha(schema: object): string;
+/** Root `type` of a schema when it declares one (the openai strict-mode
+ * object-root check reads this). `undefined` when absent or non-string. */
+export declare function schemaRootType(schema: object): string | undefined;
+/**
+ * Pre-dispatch SHAPE check (called from the knob guard): the schema must be a
+ * plain JSON-Schema object that Ajv can compile. Anything else throws the
+ * existing terminal class `invariant_violation` BEFORE any adapter is built —
+ * no meter, no provider call, no telemetry row — with a teaching fixHint. Also
+ * the one place the openai strict-root warning lives: strict `json_schema`
+ * requires an object root; a non-object root is WARNED (the provider enforces
+ * and its rejection is classified teachably by the adapter), never silently
+ * rewritten. Idempotent; side-effect-free apart from the warning + compile cache.
+ */
+export declare function assertRawResponseSchemaShape(input: {
+    readonly provider: ProviderId;
+    readonly model: string;
+    readonly responseSchema?: object;
+    readonly responseFormat?: string;
+}): void;
+export type RawSchemaOutcome = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly errors: readonly string[];
+};
+/** The one terminal-error rendering the raw lane makes (parity with run.ts's
+ * `content_invalid` message shape); exported for the finalize tests. */
+export declare const RAW_SCHEMA_MAX_ERRORS = 5;
+/**
+ * Validate the raw output text against the declared schema with the shared
+ * Ajv. Parity with the routed lane's `validateOutput`: a non-JSON body is a
+ * schema miss (one `parse` error), and Ajv errors render as `instancePath
+ * message`. Never throws — the shape check above already compiled the schema;
+ * a late compile failure (cache cleared + a schema that stopped compiling, which
+ * cannot happen for the same object) is reported as a miss, not a crash.
+ */
+export declare function validateRawOutput(schema: object, text: string): RawSchemaOutcome;
+/** The `content_invalid` failure a raw schema miss raises — the EXISTING class
+ * (its table teaching + docsUrl apply via `teach()`), with a raw-lane fixHint:
+ * this lane never repairs, so the fix is the prompt/schema or a route. */
+export declare function rawSchemaMismatchFailure(input: {
+    readonly provider: ProviderId;
+    readonly model: string;
+}, errors: readonly string[]): RigFailure;
+//# sourceMappingURL=raw-schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"raw-schema.d.ts","sourceRoot":"","sources":["../../src/run/raw-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;4EAE4E;AAC5E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CASpD;AAED;+EAC+E;AAC/E,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;2EAC2E;AAC3E,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGjE;AAmBD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,IAAI,CAqCP;AAED,MAAM,MAAM,gBAAgB,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAElH;wEACwE;AACxE,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAgBhF;AAED;;0EAE0E;AAC1E,wBAAgB,wBAAwB,CACtC,KAAK,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAChE,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,UAAU,CAWZ"}