modelrig 0.3.0 → 0.5.0

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

@@ -28,11 +28,20 @@
  *    Each is ADDITIVE: absent ⇒ byte-identical dispatch. A DECLARED directive is
  *    never silently dropped — `grounding`/`reasoning` on a provider that cannot
  *    honor it are rejected fail-closed PRE-DISPATCH (`assertRawKnobsSupported`),
- *    with no meter, no provider call, and no telemetry row. v1 support set for
- *    both = { gemini }. `serviceTier` forwards to every adapter's tier path and
- *    `meta.requestedTier` now reports the DECLARED tier (an honesty fix — it
- *    previously hardcoded `"standard"`).
+ *    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 RigManifest } from "../routes/manifest";
 import type { AdapterRequest, CandidateRef, ProviderId, ReasoningParams, ServiceTier, ToolChoice, ToolDefinition } from "../types/provider";
 import type { RunResult, RunTags } from "../types/route";
 import type { RunStreamHandle } from "./stream";
@@ -50,6 +59,13 @@ export interface RawRunInput {
     readonly systemPrompt: string;
     readonly userPrompt: string;
     readonly tags?: RunTags;
+    /** G1 (spec §3): names the ground-truth step this raw call records inside an
+     * active `run.start` context — the SAME field the routed lane exposes, so a
+     * raw call, a routed call, and an `artifact.save` can be composed into ONE
+     * step group. Resolution: `stepKey ?? tags.step ?? provider/model#n` (auto).
+     * Validated `[A-Za-z0-9_.:#-]{1,128}`; an invalid value is warned and dropped
+     * to the auto key. Outside a run context ⇒ ignored (no step is recorded). */
+    readonly stepKey?: string;
     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
@@ -95,6 +111,16 @@ export interface RawRunInput {
      * 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;
@@ -102,15 +128,31 @@ export interface RawRunDeps {
      * 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;
+    /** G1 (spec §4): the rig manifest, so the raw lane runs the SAME
+     * required-dimension hygiene warning the routed lane does. Null/absent (e.g. a
+     * `routesDir: null` runRaw-only rig) ⇒ the warning is a no-op. */
+    readonly manifest?: RigManifest | null;
 }
 /**
- * CE-2 fail-closed guard (spec §3 F1/F3). A DECLARED directive is NEVER silently
- * dropped: `grounding`/`reasoning` on a provider that cannot honor it — or a
- * `grounding.mode` other than the v1-supported `"native"` — throws
- * `RigFailureError` `invariant_violation` (the existing TERMINAL class; no new
- * FailureClass member, spec §3 rationale) BEFORE any adapter is built, any
- * provider call is made, or any telemetry row is written. Exported so the guard
- * is unit-testable without a network. Idempotent and side-effect-free.
+ * 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). */

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

@@ -1 +1 @@
-{"version":3,"file":"raw.d.ts","sourceRoot":"","sources":["../../src/run/raw.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAYH,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,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;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;CACtC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC;;+EAE2E;IAC3E,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AAkDD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAiChE;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,GAAG,cAAc,CAiC3F;AAsJD;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"}
+{"version":3,"file":"raw.d.ts","sourceRoot":"","sources":["../../src/run/raw.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAuBH,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACrF,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;;;;;iFAK6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,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;IACzC;;sEAEkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACxC;AAiED;;;;;;;;;;;;;;;;;;;;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,CAsC3F;AAoOD;wDACwD;AACxD,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAYrF;AAcD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,eAAe,CAiDlF"}