modelrig 0.2.0 → 0.4.0

package/dist/run/dispatch.js

@@ -11,6 +11,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.recordSearchCostRow = recordSearchCostRow;
+exports.jsonModeCoaching = jsonModeCoaching;
 exports.buildAdapterRequest = buildAdapterRequest;
 exports.buildRepairAdapterRequest = buildRepairAdapterRequest;
 exports.dispatchCandidate = dispatchCandidate;
@@ -21,7 +22,11 @@ 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) {
+function recordSearchCostRow(telemetry, route, effectiveTags, servedVariant, searchProviderId, costUsd, ladder) {
+    // Ladder key (spec §2.1 R0): the search-cost row belongs to the same call and
+    // rides the same monotonic seq; candidate_index is the candidate this search
+    // grounds for (the current one — the run loop set it before the search).
+    const ladderKey = ladder.stamp();
     telemetry.record({
         id: (0, node_crypto_1.randomUUID)(),
         ts: new Date().toISOString(),
@@ -41,15 +46,33 @@ function recordSearchCostRow(telemetry, route, effectiveTags, servedVariant, sea
         ttfbMs: null,
         failureClass: null,
         attemptsJson: "{}",
-        tagsJson: JSON.stringify(effectiveTags),
+        // Rung tag (R1 review, F1): the grounding-inject search-cost row.
+        tagsJson: JSON.stringify({ ...effectiveTags, rung: "search" }),
         fingerprintCell: route.fingerprintCell,
         servedVariant,
         repairedBy: null,
         pricingMissing: false,
         cacheKey: null,
         prefixFingerprint: null,
+        callId: ladderKey.callId,
+        attemptSeq: ladderKey.attemptSeq,
+        candidateIndex: ladderKey.candidateIndex,
     });
 }
+/** Schema coaching for the json_mode rung — ported from the production DeepSeek
+ * provider's schema-in-prompt guidance (minLength-is-a-FLOOR etc.). Lives here
+ * with the other request-shaping helpers to keep run.ts under the LOC cap. */
+function jsonModeCoaching(schema) {
+    return ("\n\n---\nOUTPUT FORMAT (STRICT): Respond with a SINGLE valid JSON object and nothing else — " +
+        'no markdown fences, no introductory text, no sign-off. Your response MUST start with "{" and ' +
+        'end with "}". Sanitize every nested string so embedded quotes/brackets do not break the root ' +
+        "JSON escaping. The object MUST conform to this JSON Schema — match key names and types " +
+        "EXACTLY, include ALL required fields, and do not add commentary fields. CRITICAL: where the " +
+        "schema sets a minLength on a narrative/prose field, that is a FLOOR, not a target — write " +
+        "thorough, non-repetitive analysis that comfortably EXCEEDS the minimum (do not pad with " +
+        "repetition; add real substance). When unsure how long to make a prose field, write more, " +
+        `not less:\n\n${JSON.stringify(schema)}`);
+}
 /** Build the primary-attempt AdapterRequest — adds the grounding hint and the
  * unified tools/toolChoice passthrough (spec §4.4). */
 function buildAdapterRequest(parts) {
@@ -165,6 +188,11 @@ function emitToolCallResult(record, parts) {
         ...(result.usage.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
         failure: null,
         pricingMissing: parts.pricingMissing,
+        // Rung tag (R1 review, F1): a tool-call turn is a real model call but NOT a
+        // schema-validated serve — the recorder cannot tell it from a primary, so it
+        // is stamped explicitly. The rollup counts it as a tool-call turn, never a
+        // dispatch or a serve (its cost still counts).
+        rung: "tool_call",
     });
     return {
         output: null,
@@ -185,6 +213,7 @@ function emitToolCallResult(record, parts) {
             attemptsByClass,
             servedVariant,
             repairedBy: null,
+            callId: parts.callId,
             toolCalls: result.toolCalls,
         },
     };

package/dist/run/ladder-key.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The per-call telemetry ladder key — routing-console spec §2.1 / §4.1 (R0).
+ *
+ * One `callId` is minted per `rig.run` / `runStream` / `runBundle` / `runRaw`
+ * invocation and shared by EVERY telemetry row that call writes (primary, retry,
+ * repair, grounding-search, tool-call). `attemptSeq` is a 1-based counter that
+ * is monotonic across all of those rows, and `candidateIndex` is the position of
+ * the candidate the row is about within the call's effective declared list.
+ *
+ * The minter owns the seq counter and the current candidate index so the run
+ * loop does not have to thread them through every `recordAttempt` call site
+ * (run.ts sits at its LOC cap). The loop calls `setCandidateIndex` as the
+ * candidate iterator advances; the recorder (and the search-cost recorder) call
+ * `stamp()` once per row. A repair row is stamped DURING the current candidate's
+ * turn — before the iterator advances — so it inherits that candidate's index,
+ * which IS "the candidate being repaired" per spec §2.1.
+ */
+/** One stamped ladder key — the three fields persisted onto a telemetry row. */
+export interface LadderKey {
+    readonly callId: string;
+    readonly attemptSeq: number;
+    readonly candidateIndex: number | null;
+}
+/** Hands out ladder keys for a single call. Created once per invocation. */
+export interface LadderKeyMinter {
+    /** The `call_id` shared by every row of this invocation. */
+    readonly callId: string;
+    /** Record the candidate the run loop is currently attempting. Every later
+     * `stamp()` reads this value; a null clears it (no active candidate). */
+    setCandidateIndex(index: number | null): void;
+    /** Stamp the next row: bump `attempt_seq` (1-based, monotonic) and read the
+     * current `candidate_index`. */
+    stamp(): LadderKey;
+}
+/**
+ * Build a ladder-key minter. `callId` defaults to a fresh uuid; the raw lane and
+ * tests may pass one in. Pure but for the uuid — no I/O, no shared state.
+ */
+export declare function createLadderKeyMinter(callId?: string): LadderKeyMinter;
+//# sourceMappingURL=ladder-key.d.ts.map

package/dist/run/ladder-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ladder-key.d.ts","sourceRoot":"","sources":["../../src/run/ladder-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;6EACyE;IACzE,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9C;oCACgC;IAChC,KAAK,IAAI,SAAS,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,GAAE,MAAqB,GAAG,eAAe,CAapF"}

package/dist/run/ladder-key.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * The per-call telemetry ladder key — routing-console spec §2.1 / §4.1 (R0).
+ *
+ * One `callId` is minted per `rig.run` / `runStream` / `runBundle` / `runRaw`
+ * invocation and shared by EVERY telemetry row that call writes (primary, retry,
+ * repair, grounding-search, tool-call). `attemptSeq` is a 1-based counter that
+ * is monotonic across all of those rows, and `candidateIndex` is the position of
+ * the candidate the row is about within the call's effective declared list.
+ *
+ * The minter owns the seq counter and the current candidate index so the run
+ * loop does not have to thread them through every `recordAttempt` call site
+ * (run.ts sits at its LOC cap). The loop calls `setCandidateIndex` as the
+ * candidate iterator advances; the recorder (and the search-cost recorder) call
+ * `stamp()` once per row. A repair row is stamped DURING the current candidate's
+ * turn — before the iterator advances — so it inherits that candidate's index,
+ * which IS "the candidate being repaired" per spec §2.1.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLadderKeyMinter = createLadderKeyMinter;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Build a ladder-key minter. `callId` defaults to a fresh uuid; the raw lane and
+ * tests may pass one in. Pure but for the uuid — no I/O, no shared state.
+ */
+function createLadderKeyMinter(callId = (0, node_crypto_1.randomUUID)()) {
+    let attemptSeq = 0;
+    let candidateIndex = null;
+    return {
+        callId,
+        setCandidateIndex(index) {
+            candidateIndex = index;
+        },
+        stamp() {
+            attemptSeq += 1;
+            return { callId, attemptSeq, candidateIndex };
+        },
+    };
+}

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

@@ -0,0 +1,123 @@
+/**
+ * CE-9 (spec R5) — the raw-lane provider × knob support matrix, the SINGLE
+ * source of truth for which knobs each provider honors on `rig.runRaw`.
+ *
+ * BOTH the runtime guard (`assertRawKnobsSupported`, run/raw.ts) and the docs
+ * generator (scripts/build-docs-site.ts) import `RAW_KNOB_SUPPORT` — so the
+ * fail-closed behavior a customer hits at runtime and the published matrix they
+ * read beforehand can never disagree. The guard's provider sets are no longer
+ * inline literals; adding a provider (or widening a knob) is one edit here.
+ *
+ * The knob discipline this table encodes (spec R1/R2/R4):
+ *  - grounding: gemini honors native web grounding (grok's Live Search was retired by
+ *    xAI — 410 on the CE-9 live gate — so grok is fail-closed until CE-9b lands the
+ *    Responses-API web_search path); every other provider
+ *    FAILS CLOSED pre-dispatch (guarded).
+ *  - reasoning: NO per-model allowlist outside gemini (the drift cost the
+ *    customer flagged). openai/deepinfra/fireworks forward `level` verbatim as
+ *    `reasoning_effort` and let the provider enforce (a rejection is classified
+ *    teachably in each adapter); grok forwards a DISCLOSED coarsening
+ *    (`coarsenGrokReasoningEffort`); gemini stays model-gated (the adapter
+ *    rejects a non-thinking model); deepseek + anthropic FAIL CLOSED at the
+ *    guard with a provider-specific fixHint.
+ *  - responseFormat ("json_object"): the OpenAI-dialect providers + gemini
+ *    (mime-shaping only) honor it; anthropic FAILS CLOSED (guarded). This is
+ *    mime-shaping, NOT schema enforcement — F4 stands (no validation/repair,
+ *    `meta.validated` stays false).
+ *  - cache + serviceTier are INFORMATIONAL here (never a hard fail): the cache
+ *    directive is provider-neutral (a resource HANDLE on gemini, a routing HINT
+ *    on the prompt_cache_key providers) and serviceTier forwards everywhere.
+ */
+import type { ProviderId, ReasoningLevel } from "../types/provider";
+/** How a provider treats a declared `reasoning.level` on the raw lane (R1). */
+export type ReasoningSupportKind = 
+/** openai / deepinfra / fireworks — `level` → `reasoning_effort` 1:1,
+ * forwarded verbatim; an "unsupported parameter" rejection is classified
+ * teachably by the adapter (no per-model allowlist). */
+"forward"
+/** grok — `level` coarsened to xAI's `low|high` via
+ * `coarsenGrokReasoningEffort` (a DISCLOSED lossy mapping, never silent). */
+ | "coarsen"
+/** gemini — honored only on a thinking-capable model; the adapter rejects a
+ * non-thinking model classified (`geminiReasoningUnsupported`). */
+ | "model-gated"
+/** deepseek / anthropic — no effort control exists; rejected pre-dispatch by
+ * the guard with a provider-specific fixHint. */
+ | "fail-closed";
+/** Cache-directive semantics per provider (R3) — documentation only; the raw
+ * lane never fails a call over the cache directive. */
+export type CacheSemantics = 
+/** gemini — `cache.key` is a `cachedContent` resource HANDLE (customer-owned;
+ * ModelRig never creates/refreshes/deletes it). */
+"handle"
+/** openai / grok / deepinfra / fireworks — `cache.key` → `prompt_cache_key`, a
+ * routing HINT (openai also maps `ttlSeconds ≥ 86400` → 24h retention). */
+ | "hint"
+/** deepseek — automatic prefix cache; the key is not used. */
+ | "implicit"
+/** anthropic — prefix caching via `cache_control` markers; the key is not
+ * used (out of scope for the raw lane). */
+ | "marker";
+/** A guarded knob (grounding / responseFormat): boolean support + the matrix
+ * cell text. The guard computes its thrown fixHint from the matrix (the list of
+ * supported providers), so widening the matrix updates the error too. */
+export interface KnobFact {
+    readonly supported: boolean;
+    /** Human teaching string rendered in the docs matrix cell. */
+    readonly note: string;
+}
+/** Reasoning support per provider (R1) — `kind` drives the guard (only
+ * `fail-closed` throws) and the docs. */
+export interface ReasoningFact {
+    readonly kind: ReasoningSupportKind;
+    readonly note: string;
+    /** Rendered by the guard's thrown error when `kind === "fail-closed"`. */
+    readonly fixHint?: string;
+}
+export interface CacheFact {
+    readonly semantics: CacheSemantics;
+    readonly note: string;
+}
+export interface RawKnobSupport {
+    /** GUARDED — a declared `grounding` on an unsupported provider throws. */
+    readonly grounding: KnobFact;
+    /** GUARDED only when `kind === "fail-closed"` (deepseek/anthropic). */
+    readonly reasoning: ReasoningFact;
+    /** GUARDED — a declared `responseFormat` on an unsupported provider throws. */
+    readonly responseFormat: KnobFact;
+    /** INFORMATIONAL — the cache directive never hard-fails on the raw lane. */
+    readonly cache: CacheFact;
+    /** INFORMATIONAL — serviceTier forwards to every adapter; the served tier
+     * reports the truth. */
+    readonly serviceTier: KnobFact;
+}
+/**
+ * The grok reasoning coarsening (R1): xAI's `reasoning_effort` accepts only
+ * `"low" | "high"`, so the four-level neutral vocabulary is coarsened —
+ * `minimal, low → "low"`; `medium, high → "high"`. This is a DISCLOSED, lossy
+ * mapping (it appears in the matrix note, the grok field's doc comment, and the
+ * `grok.test.ts` test), never a silent semantic drop. Kept here — beside the
+ * matrix that documents it — as the ONE place the algorithm lives (grok.ts
+ * imports it).
+ */
+export declare function coarsenGrokReasoningEffort(level: ReasoningLevel): "low" | "high";
+/** The matrix. Exhaustive over ProviderId — a new provider forces a compile
+ * error here (Record<ProviderId, …>), so it can never be silently unlisted. */
+export declare const RAW_KNOB_SUPPORT: Record<ProviderId, RawKnobSupport>;
+/** Pure lookup into the matrix (spec R6, exported from the package root). A
+ * customer's multi-provider dispatcher ASKS this instead of duplicating the
+ * provider lists. */
+export declare function rawKnobSupport(provider: ProviderId): RawKnobSupport;
+/** Providers that honor a knob, in PROVIDER_IDS order — used by the guard to
+ * build a "supported on X, Y only" fixHint from the matrix (so the error text
+ * can never drift from the table). */
+export declare function groundingSupportedProviders(): readonly ProviderId[];
+export declare function responseFormatSupportedProviders(): readonly ProviderId[];
+/** Matrix-level notes rendered below the table (spec §3.2 restated in docs). */
+export declare const RAW_KNOB_MATRIX_NOTES: readonly string[];
+/** Render the provider × knob matrix as a Markdown table + notes, FROM the
+ * matrix (never a hand-written table — R5). Consumed by the docs generator
+ * (scripts/build-docs-site.ts) so the published matrix and the runtime guard
+ * derive from the same source. */
+export declare function renderRawKnobMatrix(): string;
+//# sourceMappingURL=raw-support.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"raw-support.d.ts","sourceRoot":"","sources":["../../src/run/raw-support.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEpE,+EAA+E;AAC/E,MAAM,MAAM,oBAAoB;AAC9B;;wDAEwD;AACtD,SAAS;AACX;6EAC6E;GAC3E,SAAS;AACX;mEACmE;GACjE,aAAa;AACf;iDACiD;GAC/C,aAAa,CAAC;AAElB;uDACuD;AACvD,MAAM,MAAM,cAAc;AACxB;mDACmD;AACjD,QAAQ;AACV;2EAC2E;GACzE,MAAM;AACR,8DAA8D;GAC5D,UAAU;AACZ;2CAC2C;GACzC,QAAQ,CAAC;AAEb;;yEAEyE;AACzE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;yCACyC;AACzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B;4BACwB;IACxB,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,cAAc,GAAG,KAAK,GAAG,MAAM,CAEhF;AAED;+EAC+E;AAC/E,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,cAAc,CA+D/D,CAAC;AAEF;;qBAEqB;AACrB,wBAAgB,cAAc,CAAC,QAAQ,EAAE,UAAU,GAAG,cAAc,CAEnE;AAED;;sCAEsC;AACtC,wBAAgB,2BAA2B,IAAI,SAAS,UAAU,EAAE,CAEnE;AAED,wBAAgB,gCAAgC,IAAI,SAAS,UAAU,EAAE,CAExE;AAED,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAKlD,CAAC;AAEF;;;kCAGkC;AAClC,wBAAgB,mBAAmB,IAAI,MAAM,CAQ5C"}

package/dist/run/raw-support.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * CE-9 (spec R5) — the raw-lane provider × knob support matrix, the SINGLE
+ * source of truth for which knobs each provider honors on `rig.runRaw`.
+ *
+ * BOTH the runtime guard (`assertRawKnobsSupported`, run/raw.ts) and the docs
+ * generator (scripts/build-docs-site.ts) import `RAW_KNOB_SUPPORT` — so the
+ * fail-closed behavior a customer hits at runtime and the published matrix they
+ * read beforehand can never disagree. The guard's provider sets are no longer
+ * inline literals; adding a provider (or widening a knob) is one edit here.
+ *
+ * The knob discipline this table encodes (spec R1/R2/R4):
+ *  - grounding: gemini honors native web grounding (grok's Live Search was retired by
+ *    xAI — 410 on the CE-9 live gate — so grok is fail-closed until CE-9b lands the
+ *    Responses-API web_search path); every other provider
+ *    FAILS CLOSED pre-dispatch (guarded).
+ *  - reasoning: NO per-model allowlist outside gemini (the drift cost the
+ *    customer flagged). openai/deepinfra/fireworks forward `level` verbatim as
+ *    `reasoning_effort` and let the provider enforce (a rejection is classified
+ *    teachably in each adapter); grok forwards a DISCLOSED coarsening
+ *    (`coarsenGrokReasoningEffort`); gemini stays model-gated (the adapter
+ *    rejects a non-thinking model); deepseek + anthropic FAIL CLOSED at the
+ *    guard with a provider-specific fixHint.
+ *  - responseFormat ("json_object"): the OpenAI-dialect providers + gemini
+ *    (mime-shaping only) honor it; anthropic FAILS CLOSED (guarded). This is
+ *    mime-shaping, NOT schema enforcement — F4 stands (no validation/repair,
+ *    `meta.validated` stays false).
+ *  - cache + serviceTier are INFORMATIONAL here (never a hard fail): the cache
+ *    directive is provider-neutral (a resource HANDLE on gemini, a routing HINT
+ *    on the prompt_cache_key providers) and serviceTier forwards everywhere.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAW_KNOB_MATRIX_NOTES = exports.RAW_KNOB_SUPPORT = void 0;
+exports.coarsenGrokReasoningEffort = coarsenGrokReasoningEffort;
+exports.rawKnobSupport = rawKnobSupport;
+exports.groundingSupportedProviders = groundingSupportedProviders;
+exports.responseFormatSupportedProviders = responseFormatSupportedProviders;
+exports.renderRawKnobMatrix = renderRawKnobMatrix;
+const provider_1 = require("../types/provider");
+/**
+ * The grok reasoning coarsening (R1): xAI's `reasoning_effort` accepts only
+ * `"low" | "high"`, so the four-level neutral vocabulary is coarsened —
+ * `minimal, low → "low"`; `medium, high → "high"`. This is a DISCLOSED, lossy
+ * mapping (it appears in the matrix note, the grok field's doc comment, and the
+ * `grok.test.ts` test), never a silent semantic drop. Kept here — beside the
+ * matrix that documents it — as the ONE place the algorithm lives (grok.ts
+ * imports it).
+ */
+function coarsenGrokReasoningEffort(level) {
+    return level === "minimal" || level === "low" ? "low" : "high";
+}
+/** The matrix. Exhaustive over ProviderId — a new provider forces a compile
+ * error here (Record<ProviderId, …>), so it can never be silently unlisted. */
+exports.RAW_KNOB_SUPPORT = {
+    gemini: {
+        grounding: { supported: true, note: "native — Google Search (`googleSearch` tool)" },
+        reasoning: { kind: "model-gated", note: "`level` → `thinkingConfig.thinkingLevel`, thinking-capable models only (see `GEMINI_THINKING_CAPABLE_MODELS`)" },
+        responseFormat: { supported: true, note: "`responseMimeType: application/json` (mime-shaping only — no schema, `validated` stays false)" },
+        cache: { semantics: "handle", note: "`cache.key` = a `cachedContent` resource handle (customer-owned lifecycle)" },
+        serviceTier: { supported: true, note: "`flex` / `standard` / `priority` honored" },
+    },
+    openai: {
+        grounding: { supported: false, note: "fail-closed" },
+        reasoning: { kind: "forward", note: "`level` → `reasoning_effort` (1:1); a non-reasoning model's rejection is classified teachably" },
+        responseFormat: { supported: true, note: "`response_format: { type: json_object }`" },
+        cache: { semantics: "hint", note: "`cache.key` → `prompt_cache_key`; `ttlSeconds ≥ 86400` → `prompt_cache_retention: 24h`" },
+        serviceTier: { supported: true, note: "`flex` (allowlist) / `priority`; flex→standard is a customer-side degrade (§3.2)" },
+    },
+    grok: {
+        grounding: { supported: false, note: "fail-closed — xAI retired Live Search (HTTP 410, 2026-08-21); native `web_search` needs the Responses API, tracked as CE-9b" },
+        reasoning: { kind: "coarsen", note: 'coarsened (disclosed): `minimal,low → "low"`; `medium,high → "high"` → `reasoning_effort`' },
+        responseFormat: { supported: true, note: "`response_format: { type: json_object }`" },
+        cache: { semantics: "hint", note: "`cache.key` → `prompt_cache_key` (routing hint)" },
+        serviceTier: { supported: false, note: "no tiers — always `standard`" },
+    },
+    deepseek: {
+        grounding: { supported: false, note: "fail-closed" },
+        reasoning: {
+            kind: "fail-closed",
+            note: "no effort control — reasoning is model selection (`deepseek-reasoner`)",
+            fixHint: "DeepSeek has no reasoning-effort control — select the deepseek-reasoner model instead and remove reasoning",
+        },
+        responseFormat: { supported: true, note: "`response_format: { type: json_object }` — the prompt must contain the word \"JSON\" (caller's responsibility on the raw lane)" },
+        cache: { semantics: "implicit", note: "automatic prefix cache — the key is not used" },
+        serviceTier: { supported: false, note: "no tiers — always `standard`" },
+    },
+    anthropic: {
+        grounding: { supported: false, note: "fail-closed" },
+        reasoning: {
+            kind: "fail-closed",
+            note: "extended thinking is not wired on the raw lane (future work)",
+            fixHint: "Anthropic extended thinking is not wired on the raw lane in v1 — remove reasoning",
+        },
+        responseFormat: {
+            supported: false,
+            note: "fail-closed — no json_object equivalent (structured output is a forced tool call)",
+        },
+        cache: { semantics: "marker", note: "prefix caching via `cache_control` markers — the key is not used" },
+        serviceTier: { supported: false, note: "no tiers — always `standard`" },
+    },
+    deepinfra: {
+        grounding: { supported: false, note: "fail-closed" },
+        reasoning: { kind: "forward", note: "`level` → `reasoning_effort` (1:1); a non-reasoning model's rejection is classified teachably" },
+        responseFormat: { supported: true, note: "`response_format: { type: json_object }`" },
+        cache: { semantics: "hint", note: "`cache.key` → `prompt_cache_key` (routing hint)" },
+        serviceTier: { supported: false, note: "no tiers — always `standard`" },
+    },
+    fireworks: {
+        grounding: { supported: false, note: "fail-closed" },
+        reasoning: { kind: "forward", note: "`level` → `reasoning_effort` (1:1); a non-reasoning model's rejection is classified teachably" },
+        responseFormat: { supported: true, note: "`response_format: { type: json_object }`" },
+        cache: { semantics: "hint", note: "`cache.key` → `prompt_cache_key` (routing hint; caching is automatic host-side)" },
+        serviceTier: { supported: false, note: "no tiers — always `standard`" },
+    },
+};
+/** Pure lookup into the matrix (spec R6, exported from the package root). A
+ * customer's multi-provider dispatcher ASKS this instead of duplicating the
+ * provider lists. */
+function rawKnobSupport(provider) {
+    return exports.RAW_KNOB_SUPPORT[provider];
+}
+/** Providers that honor a knob, in PROVIDER_IDS order — used by the guard to
+ * build a "supported on X, Y only" fixHint from the matrix (so the error text
+ * can never drift from the table). */
+function groundingSupportedProviders() {
+    return provider_1.PROVIDER_IDS.filter((p) => exports.RAW_KNOB_SUPPORT[p].grounding.supported);
+}
+function responseFormatSupportedProviders() {
+    return provider_1.PROVIDER_IDS.filter((p) => exports.RAW_KNOB_SUPPORT[p].responseFormat.supported);
+}
+/** Matrix-level notes rendered below the table (spec §3.2 restated in docs). */
+exports.RAW_KNOB_MATRIX_NOTES = [
+    "**Fail-closed is discoverable, not a surprise.** A knob a provider cannot honor throws `RigFailureError` `invariant_violation` PRE-DISPATCH (no meter, no provider call, no telemetry row) — read this table before you call, not after.",
+    "**reasoning has NO per-model allowlist outside gemini.** openai/deepinfra/fireworks forward `level` verbatim and let the provider enforce; a rejection surfaces as a classified failure that names the fix. grok coarsens (disclosed above). deepseek reasoning is model selection (`deepseek-reasoner`); anthropic extended thinking is unwired.",
+    "**responseFormat is mime-shaping, not schema enforcement.** `json_object` forces syntactic JSON only — the raw lane still never validates or repairs, and `meta.validated` stays `false` (F4).",
+    "**§3.2 flex degrade is customer-side.** ModelRig does not replicate the gemini direct-path infra-retry wrapper on the raw lane; under `flex` a capacity rejection surfaces classified (`capacity_shed`) for your own `→ standard` retry ladder — a NAMED difference for your migration record, not a silent one.",
+];
+/** Render the provider × knob matrix as a Markdown table + notes, FROM the
+ * matrix (never a hand-written table — R5). Consumed by the docs generator
+ * (scripts/build-docs-site.ts) so the published matrix and the runtime guard
+ * derive from the same source. */
+function renderRawKnobMatrix() {
+    const header = "| Provider | grounding | reasoning | responseFormat | cache | serviceTier |";
+    const sep = "|---|---|---|---|---|---|";
+    const rows = provider_1.PROVIDER_IDS.map((p) => {
+        const s = exports.RAW_KNOB_SUPPORT[p];
+        return `| \`${p}\` | ${s.grounding.note} | ${s.reasoning.note} | ${s.responseFormat.note} | ${s.cache.note} | ${s.serviceTier.note} |`;
+    });
+    return [header, sep, ...rows, "", ...exports.RAW_KNOB_MATRIX_NOTES].join("\n");
+}

package/dist/run/raw.d.ts

@@ -23,8 +23,25 @@
  *    `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. `serviceTier`
+ *    forwards to every adapter's tier path and `meta.requestedTier` now reports
+ *    the DECLARED tier (an honesty fix — it previously hardcoded `"standard"`).
+ *  - CE-9: multi-provider parity. `grounding` now also serves grok (xAI Live
+ *    Search); `reasoning` generalizes beyond gemini WITHOUT a per-model
+ *    allowlist — openai/deepinfra/fireworks forward `level` → `reasoning_effort`
+ *    verbatim (provider enforces, rejection classified teachably), grok coarsens
+ *    (disclosed), gemini stays model-gated, deepseek/anthropic fail closed; a
+ *    new `responseFormat: "json_object"` knob mime-shapes on the OpenAI-dialect
+ *    providers + gemini (anthropic fails closed). The provider×knob support set
+ *    is ONE table (`run/raw-support.ts`) the guard AND the published docs matrix
+ *    both read — they can never disagree (R5).
  */
-import type { AdapterRequest, CandidateRef, ProviderId, ToolChoice, ToolDefinition } from "../types/provider";
+import type { AdapterRequest, CandidateRef, ProviderId, ReasoningParams, ServiceTier, ToolChoice, ToolDefinition } from "../types/provider";
 import type { RunResult, RunTags } from "../types/route";
 import type { RunStreamHandle } from "./stream";
 import type { TelemetryStore } from "../types/telemetry";
@@ -63,6 +80,39 @@ export interface RawRunInput {
         readonly key: string;
         readonly ttlSeconds?: number;
     };
+    /** CE-2 F1 — native provider grounding on the raw lane (spec §3 F1). Object
+     * form so `"inject"` can join later without reshaping; v1 accepts ONLY
+     * `"native"`, which maps to `AdapterRequest.grounding = true`. GEMINI-ONLY in
+     * v1: declared on any other provider throws `RigFailureError`
+     * `invariant_violation` pre-dispatch (`assertRawKnobsSupported`). Interplay
+     * with `cache.key`: no code needed here — the gemini adapter's `cachedContent`
+     * path excludes tools (the googleSearch tool is expected to be baked into the
+     * customer's cache resource at creation). */
+    readonly grounding?: {
+        readonly mode: "native";
+    };
+    /** CE-2 F2 — service tier on the raw lane (spec §3 F2). Forwarded to
+     * `AdapterRequest.requestedTier` (default `"standard"`). ModelRig does NOT
+     * perform flex→standard degrade on the raw lane — a capacity rejection
+     * surfaces CLASSIFIED (`capacity_shed`) and the customer's own ladder retries
+     * at `"standard"`. `meta.servedTier`/`meta.requestedTier` report the truth. */
+    readonly serviceTier?: ServiceTier;
+    /** CE-2 F3 — reasoning/thinking effort on the raw lane (spec §3 F3). Absent ⇒
+     * byte-identical (gemini keeps its hardcoded `"high"`). GEMINI-ONLY in v1 (and
+     * only on a thinking-capable model): declared on any other provider throws
+     * pre-dispatch (`assertRawKnobsSupported`); declared on a non-thinking gemini
+     * model is rejected classified by the adapter (`geminiReasoningUnsupported`). */
+    readonly reasoning?: ReasoningParams;
+    /** CE-9 R4 — syntactic-JSON response shaping on the raw lane. `"json_object"`
+     * maps to each provider's json_object / json-mime directive (OpenAI-dialect
+     * providers + gemini); ABSENT ⇒ byte-identical (no key added). This is
+     * MIME-SHAPING, NOT schema enforcement — F4 stands: no validation, no repair,
+     * `meta.validated` stays false. GUARDED: anthropic has no equivalent and is
+     * rejected fail-closed pre-dispatch (`assertRawKnobsSupported`). DeepSeek's
+     * documented wrinkle — its json_object mode 400s when the literal word "JSON"
+     * appears nowhere in the prompt — is the CALLER's prompt responsibility on the
+     * raw lane (documented in the R5 matrix, never injected here). */
+    readonly responseFormat?: "json_object";
 }
 export interface RawRunDeps {
     readonly telemetry: TelemetryStore;
@@ -71,6 +121,28 @@ export interface RawRunDeps {
      * it never charges the unpriced fallback; a missing price records `$0`. */
     readonly unpricedRateUsdPerMTok?: number;
 }
+/**
+ * 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;
 /** 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,

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

@@ -1 +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"}
+{"version":3,"file":"raw.d.ts","sourceRoot":"","sources":["../../src/run/raw.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAiBH,OAAO,KAAK,EACV,cAAc,EAGd,YAAY,EAGZ,UAAU,EACV,eAAe,EACf,WAAW,EACX,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,EAA+B,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEtF;;;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;IACxE;;;;;;;iDAO6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC;IACjD;;;;mFAI+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;;qFAIiF;IACjF,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC;;;;;;;;sEAQkE;IAClE,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC;CACzC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC;;+EAE2E;IAC3E,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AA0CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAiDhE;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,GAAG,cAAc,CAqC3F;AAsKD;wDACwD;AACxD,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CASrF;AAcD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,eAAe,CA6ClF"}