modelrig 0.4.0 → 0.5.0

package/dist/routes/loader.js

@@ -5,8 +5,7 @@
  * resolves schema/prompt paths relative to the bundle file, freezes.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RouteConfigError = void 0;
-exports.arrayRootSchemaWarning = arrayRootSchemaWarning;
+exports.RouteConfigError = exports.unreferencedTrialCandidatesWarning = exports.arrayRootSchemaWarning = void 0;
 exports.loadRoutesWithExtra = loadRoutesWithExtra;
 exports.mergeLoadedRoutes = mergeLoadedRoutes;
 exports.validateRoutesDir = validateRoutesDir;
@@ -19,28 +18,13 @@ const fingerprint_1 = require("../registry/fingerprint");
 const template_1 = require("./template");
 const cache_lint_1 = require("./cache-lint");
 const sampling_config_1 = require("./sampling-config");
-/**
- * CE-2 A5 co-item: warn (non-fatal) when a route's output schema has an ARRAY
- * root. OpenAI strict structured output (`response_format: json_schema`, strict)
- * requires a top-level OBJECT — an array-root schema cannot use strict
- * enforcement on OpenAI candidates and silently falls back to non-strict there
- * (the walkthrough §10 provider-matrix gap). The route still LOADS and serves as
- * declared; the fix is to wrap the array in an object property so strict
- * enforcement holds across every provider. Returns the warning line, or null.
- * Pure — unit-tested directly.
- */
-function arrayRootSchemaWarning(route, outputSchema) {
-    if (outputSchema === null)
-        return null;
-    const rootType = outputSchema.type;
-    if (rootType !== "array")
-        return null;
-    return (`route "${route}" declares an output schema whose ROOT is type: "array". OpenAI strict ` +
-        `structured output requires a top-level object, so strict enforcement cannot apply on OpenAI ` +
-        `candidates (they fall back to non-strict there). Wrap the array in an object property ` +
-        `(e.g. { "type": "object", "properties": { "items": <your array> } }) to keep strict ` +
-        `enforcement across providers. The route loads and serves as declared.`);
-}
+const loader_warnings_1 = require("./loader-warnings");
+// Re-exported so existing importers of "./loader" keep resolving these pure
+// advisories (they now live in ./loader-warnings to hold loader.ts under the
+// 700-LOC cap).
+var loader_warnings_2 = require("./loader-warnings");
+Object.defineProperty(exports, "arrayRootSchemaWarning", { enumerable: true, get: function () { return loader_warnings_2.arrayRootSchemaWarning; } });
+Object.defineProperty(exports, "unreferencedTrialCandidatesWarning", { enumerable: true, get: function () { return loader_warnings_2.unreferencedTrialCandidatesWarning; } });
 /**
  * Structured config error thrown for any invalid bundle (never a raw Error).
  * Load-time problems are deliberately NOT RigFailures — the failure taxonomy
@@ -101,7 +85,18 @@ function parseCandidates(raw, problems) {
             problems.push(`candidates[${i}].provider "${c.provider}" is not a known provider`);
             continue;
         }
-        out.push(Object.freeze({ provider: c.provider, model: c.model }));
+        // Declare-first `trial` flag (routing-console spec §4.4): declared, never
+        // live-served. Optional; only `true` is carried so an absent/false flag
+        // leaves the candidate byte-identical to a pre-R3 candidate.
+        if (c.trial !== undefined && typeof c.trial !== "boolean") {
+            problems.push(`candidates[${i}].trial must be a boolean`);
+            continue;
+        }
+        out.push(Object.freeze({
+            provider: c.provider,
+            model: c.model,
+            ...(c.trial === true ? { trial: true } : {}),
+        }));
     }
     return out;
 }
@@ -223,6 +218,13 @@ function parseRepair(raw, field, candidates, problems) {
             problems.push(`${field}.repair_model (${repairModel.provider}/${repairModel.model}) is not in the route's declared candidates`);
             repairModel = null;
         }
+        // Declare-first (spec §4.4): the repair model dispatches LIVE, so a `trial`
+        // candidate (declared, never live-served) must not be one — reject at load.
+        const rm = repairModel;
+        if (rm !== null && candidates.some((c) => c.provider === rm.provider && c.model === rm.model && c.trial === true)) {
+            problems.push(`${field}.repair_model (${rm.provider}/${rm.model}) is a trial candidate and cannot be a live repair model`);
+            repairModel = null;
+        }
     }
     if (maxRepairs === 2 && repairModel === null) {
         problems.push(`${field}.max_repairs=2 requires repair_model (attempt 2 is the designated repair model)`);
@@ -271,6 +273,14 @@ function parseVariants(raw, routeCandidates, problems) {
                 }
             }
         }
+        // trialOnly (routing-console spec §4.4): a variant whose candidates ALL map
+        // to declared `trial` candidates is a trial variant — valid for a bake-off,
+        // a live config error. Computed from the route-level trial flags (a variant
+        // narrows a subset; the flag lives on the declared candidate), so an empty
+        // or inherited candidate list is never trial-only.
+        const trialOnly = candidates !== undefined &&
+            candidates.length > 0 &&
+            candidates.every((vc) => routeCandidates.some((rc) => rc.provider === vc.provider && rc.model === vc.model && rc.trial === true));
         if (v.prompt_override !== undefined && v.prompt_append !== undefined) {
             problems.push(`${field} sets both prompt_override and prompt_append — they are mutually exclusive`);
         }
@@ -293,6 +303,7 @@ function parseVariants(raw, routeCandidates, problems) {
                 ? { json: v.json }
                 : {}),
             ...(repair !== undefined ? { repair } : {}),
+            ...(trialOnly ? { trialOnly: true } : {}),
         }));
     }
     return out;
@@ -440,10 +451,17 @@ function loadBundleFile(filePath) {
     }
     // CE-2 A5 co-item: an array-root schema cannot use OpenAI strict enforcement —
     // warn once at load so the incompatibility is deliberate, never silent.
-    const arrayRootWarning = arrayRootSchemaWarning(route, outputSchema);
+    const arrayRootWarning = (0, loader_warnings_1.arrayRootSchemaWarning)(route, outputSchema);
     if (arrayRootWarning !== null) {
         console.warn(`modelrig: ${arrayRootWarning}`);
     }
+    // Declare-first dead-declaration warning (spec §4.4): a trial candidate no
+    // variant references is unreachable — warn so the dangling declaration is
+    // deliberate, never silent.
+    const trialWarning = (0, loader_warnings_1.unreferencedTrialCandidatesWarning)(route, candidates, variants);
+    if (trialWarning !== null) {
+        console.warn(`modelrig: ${trialWarning}`);
+    }
     return Object.freeze({
         route: route,
         version: version,

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

@@ -0,0 +1,52 @@
+/**
+ * Raw-lane defaults (#245, spec R1–R3) — the SINGLE source of truth for what
+ * `rig.runRaw` sends when the caller omits a knob, and the generator behind the
+ * published defaults table.
+ *
+ * WHY ITS OWN FILE: `raw.ts` sits near the 700-LOC invariant cap, and this table
+ * is the CE-9/`raw-support.ts` pattern — a code constant the runtime reads AND
+ * the docs generator renders, so the published table can never drift from the
+ * behaviour. `raw.ts` imports `RAW_TIMEOUT_DEFAULT_MS` and resolves the effective
+ * timeout from it; the docs builder injects `renderRawDefaults()` at the
+ * `<!-- RAW_DEFAULTS -->` marker in `route-bundles.md` and into llms.txt. The
+ * drift test asserts the rendered `timeoutMs` default is read from THIS constant
+ * (never retyped), so the table and the dispatch agree by construction.
+ */
+import type { ServiceTier } from "../types/provider";
+/**
+ * R1 — the tier-aware raw-lane timeout default (ms). A raw passthrough should not
+ * be shorter-fused than the tier it advertises: `standard`/`priority` target up
+ * to 5 min (grounded + large prompts routinely exceed the old 120 s even at
+ * standard), `flex` targets the 15-minute budget ModelRig advertises. An explicit
+ * `RawRunInput.timeoutMs` always wins; this is only the fallback, and a `timeout`
+ * failure on the raw lane teaches the tier + budget in its `fixHint`.
+ */
+export declare const RAW_TIMEOUT_DEFAULT_MS: Record<ServiceTier, number>;
+/** One row of the generated defaults table (R2/R3). */
+export interface RawDefaultRow {
+    /** The `RawRunInput` field this row documents. */
+    readonly knob: string;
+    /** The value sent when the caller omits the knob — DERIVED from the constant
+     * the runtime uses where one exists (timeoutMs), so it cannot drift. */
+    readonly default: string;
+    /** The teaching note rendered in the table cell. */
+    readonly note: string;
+}
+/**
+ * The defaults table (R2/R3) — every behavioural `RawRunInput` knob and what the
+ * raw lane does when the caller omits it. `provider`/`model`/`apiKey`/
+ * `systemPrompt`/`userPrompt` are the call itself, not defaultable knobs, so they
+ * are not listed. Exhaustive over the optional knobs the raw lane exposes; a new
+ * knob added to `RawRunInput` should gain a row here (and the `route-bundles`
+ * coverage test guards the important ones).
+ */
+export declare const RAW_DEFAULTS: readonly RawDefaultRow[];
+/**
+ * Render the defaults table as a Markdown table, FROM `RAW_DEFAULTS` (never a
+ * hand-written twin — R2/R3). Consumed by the docs generator
+ * (scripts/build-docs-site.ts) at the `<!-- RAW_DEFAULTS -->` marker and in
+ * llms.txt, so the published table and the runtime defaults derive from one
+ * source.
+ */
+export declare function renderRawDefaults(): string;
+//# sourceMappingURL=raw-defaults.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"raw-defaults.d.ts","sourceRoot":"","sources":["../../src/run/raw-defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAI9D,CAAC;AAEF,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;4EACwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAeD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,aAAa,EA6DhD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C"}

package/dist/run/raw-defaults.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Raw-lane defaults (#245, spec R1–R3) — the SINGLE source of truth for what
+ * `rig.runRaw` sends when the caller omits a knob, and the generator behind the
+ * published defaults table.
+ *
+ * WHY ITS OWN FILE: `raw.ts` sits near the 700-LOC invariant cap, and this table
+ * is the CE-9/`raw-support.ts` pattern — a code constant the runtime reads AND
+ * the docs generator renders, so the published table can never drift from the
+ * behaviour. `raw.ts` imports `RAW_TIMEOUT_DEFAULT_MS` and resolves the effective
+ * timeout from it; the docs builder injects `renderRawDefaults()` at the
+ * `<!-- RAW_DEFAULTS -->` marker in `route-bundles.md` and into llms.txt. The
+ * drift test asserts the rendered `timeoutMs` default is read from THIS constant
+ * (never retyped), so the table and the dispatch agree by construction.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAW_DEFAULTS = exports.RAW_TIMEOUT_DEFAULT_MS = void 0;
+exports.renderRawDefaults = renderRawDefaults;
+/**
+ * R1 — the tier-aware raw-lane timeout default (ms). A raw passthrough should not
+ * be shorter-fused than the tier it advertises: `standard`/`priority` target up
+ * to 5 min (grounded + large prompts routinely exceed the old 120 s even at
+ * standard), `flex` targets the 15-minute budget ModelRig advertises. An explicit
+ * `RawRunInput.timeoutMs` always wins; this is only the fallback, and a `timeout`
+ * failure on the raw lane teaches the tier + budget in its `fixHint`.
+ */
+exports.RAW_TIMEOUT_DEFAULT_MS = {
+    standard: 300000,
+    priority: 300000,
+    flex: 900000,
+};
+/** Render `${ms} ms` as whole seconds (both defaults are whole-second values). */
+function secs(ms) {
+    return `${ms / 1000} s`;
+}
+/** The tier-aware `timeoutMs` default, rendered FROM `RAW_TIMEOUT_DEFAULT_MS`
+ * (never a retyped literal — the drift test locks this to the constant). */
+function timeoutDefaultCell() {
+    return `${secs(exports.RAW_TIMEOUT_DEFAULT_MS.standard)} (standard, priority) · ${secs(exports.RAW_TIMEOUT_DEFAULT_MS.flex)} (flex)`;
+}
+/**
+ * The defaults table (R2/R3) — every behavioural `RawRunInput` knob and what the
+ * raw lane does when the caller omits it. `provider`/`model`/`apiKey`/
+ * `systemPrompt`/`userPrompt` are the call itself, not defaultable knobs, so they
+ * are not listed. Exhaustive over the optional knobs the raw lane exposes; a new
+ * knob added to `RawRunInput` should gain a row here (and the `route-bundles`
+ * coverage test guards the important ones).
+ */
+exports.RAW_DEFAULTS = [
+    {
+        knob: "timeoutMs",
+        default: timeoutDefaultCell(),
+        note: "tier-aware wall-clock deadline; an explicit `timeoutMs` always wins, and a `timeout` failure carries a `fixHint` naming the tier + budget",
+    },
+    {
+        knob: "serviceTier",
+        default: "standard",
+        note: "forwarded to the adapter; `meta.servedTier` reports what actually served. On `flex`, set `timeoutMs` in minutes (default 900 s)",
+    },
+    {
+        knob: "temperature",
+        default: "adapter default — not sent",
+        note: "absent ⇒ no `temperature` on the request (byte-identical dispatch)",
+    },
+    {
+        knob: "topP",
+        default: "adapter default — not sent",
+        note: "absent ⇒ no `topP` on the request (byte-identical dispatch)",
+    },
+    {
+        knob: "maxOutputTokens",
+        default: "adapter default — not sent",
+        note: "absent ⇒ no output-token cap on the request (byte-identical dispatch)",
+    },
+    {
+        knob: "grounding",
+        default: "absent ⇒ byte-identical",
+        note: "native provider grounding; provider support per the raw-lane knob matrix",
+    },
+    {
+        knob: "reasoning",
+        default: "absent ⇒ byte-identical",
+        note: "reasoning/thinking effort; provider support per the raw-lane knob matrix",
+    },
+    {
+        knob: "responseFormat",
+        default: "absent ⇒ byte-identical",
+        note: "syntactic-JSON forcing (mime-shaping only); provider support per the raw-lane knob matrix",
+    },
+    {
+        knob: "cache",
+        default: "none",
+        note: "customer cache handle passed through verbatim when supplied; ModelRig never creates, refreshes, or deletes the resource",
+    },
+    {
+        knob: "tags",
+        default: "none",
+        note: "`lane=raw` and `rung=primary` are stamped by the SDK and cannot be overridden by a caller tag",
+    },
+    {
+        knob: "tools / toolChoice",
+        default: "none",
+        note: "absent ⇒ no tools declared; on the raw lane a grounding-originated `functionCall` part is NOT a tool-call turn",
+    },
+    {
+        knob: "stepKey",
+        default: "auto — `tags.step`, else `<provider>/<model>#<n>` inside a run context",
+        note: "names the ground-truth step a run context records for this call (G1); explicit key wins; no run context ⇒ no step",
+    },
+];
+/**
+ * Render the defaults table as a Markdown table, FROM `RAW_DEFAULTS` (never a
+ * hand-written twin — R2/R3). Consumed by the docs generator
+ * (scripts/build-docs-site.ts) at the `<!-- RAW_DEFAULTS -->` marker and in
+ * llms.txt, so the published table and the runtime defaults derive from one
+ * source.
+ */
+function renderRawDefaults() {
+    const header = "| Knob | Default | Note |";
+    const sep = "|---|---|---|";
+    const rows = exports.RAW_DEFAULTS.map((r) => `| \`${r.knob}\` | ${r.default} | ${r.note} |`);
+    return [header, sep, ...rows].join("\n");
+}

package/dist/run/raw.d.ts

@@ -41,6 +41,7 @@
  *    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";
@@ -58,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
@@ -120,6 +128,10 @@ 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/CE-9 fail-closed guard (spec §3 F1/F3, CE-9 R1/R2/R4). A DECLARED

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

@@ -1 +1 @@
-{"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"}
+{"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"}

package/dist/run/raw.js

@@ -55,12 +55,37 @@ const grok_1 = require("../adapters/grok");
 const openai_1 = require("../adapters/openai");
 const openai_compat_1 = require("../adapters/openai-compat");
 const cost_1 = require("./cost");
+const raw_defaults_1 = require("./raw-defaults");
 const resolve_1 = require("./resolve");
 const raw_support_1 = require("./raw-support");
 const failures_1 = require("../types/failures");
-/** Absent a route timeout, the raw lane uses a generous default — a passthrough
- * should not be shorter-fused than the underlying provider SDK. */
-const DEFAULT_RAW_TIMEOUT_MS = 120000;
+const run_context_1 = require("../artifacts/run-context");
+const manifest_1 = require("../routes/manifest");
+/**
+ * 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"];
+}
+/** 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 = 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}`;
+}
 /** Conservative compat-host capability baseline — parity with createRig's
  * COMPAT_STATIC. Inconsequential for raw calls (outputSchema is always null, so
  * no JSON shaping fires), kept aligned so a raw and a routed compat call shape
@@ -181,7 +206,8 @@ function buildRawRequest(candidate, input) {
         // CE-2 F2: forward the DECLARED tier (default "standard"); the meta/row
         // honesty fix in finalizeRaw reports this same value, never a hardcode.
         requestedTier: input.serviceTier ?? "standard",
-        timeoutMs: input.timeoutMs ?? DEFAULT_RAW_TIMEOUT_MS,
+        // 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.
@@ -244,13 +270,35 @@ function recordRawRow(telemetry, p) {
     };
     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) {
+    (0, manifest_1.warnMissingRequiredDimensions)(deps.manifest ?? null, input.tags ?? {});
+    const runCtx = (0, run_context_1.getActiveRunContext)();
+    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) {
+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
@@ -260,6 +308,21 @@ function finalizeRaw(deps, input, result, latencyMs) {
     const requestedTier = input.serviceTier ?? "standard";
     // lane is SDK-owned and cannot be overridden by a caller-supplied tag.
     const tags = { ...(input.tags ?? {}), lane: "raw" };
+    // 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;
@@ -268,8 +331,9 @@ function finalizeRaw(deps, input, result, latencyMs) {
             costUsd = settled.costUsd;
             pricingMissing = settled.pricingMissing;
         }
+        const failId = (0, node_crypto_1.randomUUID)();
         recordRawRow(deps.telemetry, {
-            id: (0, node_crypto_1.randomUUID)(),
+            id: failId,
             rawModelId,
             provider: input.provider,
             model: input.model,
@@ -283,6 +347,16 @@ function finalizeRaw(deps, input, result, latencyMs) {
             callId,
             ...(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);
@@ -302,6 +376,7 @@ function finalizeRaw(deps, input, result, latencyMs) {
         callId,
         ...(input.cache !== undefined ? { cacheKey: input.cache.key } : {}),
     });
+    emitStep(id, null);
     const toolCalls = result.toolCalls;
     const isToolTurn = toolCalls !== undefined && toolCalls.length > 0;
     const meta = {
@@ -332,11 +407,14 @@ async function runRaw(deps, input) {
     // CE-2 F1/F3: fail closed on an unsupported declared directive BEFORE building
     // an adapter — no meter, no provider call, no telemetry row.
     assertRawKnobsSupported(input);
+    // G1: bind the ambient run context at ENTRY (ALS boundary) so a raw call inside
+    // a run.start records a ground-truth step (spec §4). Null ⇒ uninstrumented.
+    const step = prepareRawStep(deps, input);
     const adapter = buildRawAdapter(input.provider, input.apiKey);
     const candidate = (0, resolve_1.mintRawCandidate)(input.provider, input.model);
     const started = Date.now();
     const result = await adapter.call(buildRawRequest(candidate, input));
-    return finalizeRaw(deps, input, result, Date.now() - started);
+    return finalizeRaw(deps, input, result, Date.now() - started, step);
 }
 function streamEndedFailure(input) {
     return {
@@ -358,6 +436,10 @@ function streamEndedFailure(input) {
  * the raw lane has no schema and the streamed bytes ARE the answer.
  */
 function runRawStream(deps, input) {
+    // G1: read the ambient run context HERE — at the synchronous entry, the ALS
+    // boundary — NOT inside the async generator below (which defers to drain time,
+    // possibly on a different async context, where getActiveRunContext would miss).
+    const step = prepareRawStep(deps, input);
     let settle;
     let fail;
     const result = new Promise((res, rej) => {
@@ -394,7 +476,7 @@ function runRawStream(deps, input) {
             else {
                 adapterResult = await adapter.call(req);
             }
-            const runResult = finalizeRaw(deps, input, adapterResult, Date.now() - started);
+            const runResult = finalizeRaw(deps, input, adapterResult, Date.now() - started, step);
             settle(runResult);
             yield { type: "final", result: runResult };
         }

package/dist/run/resolve.d.ts

@@ -9,6 +9,16 @@ import type { RouteBundle, RunOptions } from "../types/route";
 import type { CandidateRef, CapabilityFlag, ProviderId } from "../types/provider";
 /** Static capability stub — replaced by the probed registry in Phase 2. */
 export type CapabilityLookup = (provider: ProviderId, model: string) => ReadonlySet<CapabilityFlag>;
+/**
+ * Resolution mode (routing-console spec §4.4, R3). `live` is every production
+ * path (`rig.run`, `runStream`, `runBundle`, the hosted gateway slug lane) and
+ * DROPS `trial` candidates before minting — a declared trial candidate is never
+ * served live. `trial` is the bake-off replay path ONLY (`replayVariant`), which
+ * keeps trial candidates so a customer can measure a new model on captured
+ * traffic before promoting it. Default `live` — every existing caller is
+ * byte-for-byte unchanged (no trial candidates ⇒ the filter is a no-op anyway).
+ */
+export type RunMode = "live" | "trial";
 export interface CandidateIterator {
     /** Next eligible candidate, or null when the set is exhausted. */
     next(): CandidateRef | null;
@@ -17,6 +27,12 @@ export interface CandidateIterator {
      * the first `next()`; unchanged by a `next()` that returns null. */
     readonly index: number;
 }
+/** The live-resolver capability filter. Exported so the declare-first challenger
+ * eligibility (`registry/select.ts` `requirementPredicates` +
+ * `evaluateChallengerEligibility`) can pin itself in agreement with what would
+ * actually serve — an eligibility that drifted from the live filter would offer
+ * a challenger the route could never dispatch. */
+export declare function satisfiesRequirements(route: RouteBundle, flags: ReadonlySet<CapabilityFlag>, searchAvailable: boolean): boolean;
 /**
  * Request-time candidate filters (G-2) — optional, applied by resolveCandidates
  * BEFORE the prefer:[cost] sort. Distinct from route.require (capability + ZDR):
@@ -60,7 +76,7 @@ export interface WarmthShadowLog {
     }[];
     readonly diverged: boolean;
 }
-export declare function resolveCandidates(route: RouteBundle, capabilities: CapabilityLookup, costUsdPerMTok: (provider: ProviderId, model: string) => number | null, searchAvailable?: boolean, filter?: CandidateFilter, shadowWarmth?: WarmthShadowOptions): CandidateIterator;
+export declare function resolveCandidates(route: RouteBundle, capabilities: CapabilityLookup, costUsdPerMTok: (provider: ProviderId, model: string) => number | null, searchAvailable?: boolean, filter?: CandidateFilter, shadowWarmth?: WarmthShadowOptions, mode?: RunMode): CandidateIterator;
 /**
  * Per-run requirement opt-ins (G-3). A caller can demand zero-retention routing
  * for a single run without editing the route bundle: `zero_retention` is unioned

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

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/run/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAElF,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,CAC7B,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,MAAM,KACV,WAAW,CAAC,cAAc,CAAC,CAAC;AAEjC,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,IAAI,YAAY,GAAG,IAAI,CAAC;IAC5B;;wEAEoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AA6CD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;oFAEgF;IAChF,QAAQ,CAAC,uBAAuB,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACzF,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;CACjD;AAED;kFACkF;AAClF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtF,QAAQ,CAAC,WAAW,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,gBAAgB,EAC9B,cAAc,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,EACtE,eAAe,UAAQ,EACvB,MAAM,CAAC,EAAE,eAAe,EACxB,YAAY,CAAC,EAAE,mBAAmB,GACjC,iBAAiB,CAwFnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,GAAG,WAAW,CAM5F;AAED;mFACmF;AACnF,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,UAAU,GAAG,eAAe,GAAG,SAAS,CAUxF;AAED;;gDAEgD;AAChD,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAElF;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9D,YAAY,GAAG,IAAI,CAMrB"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/run/resolve.ts"],"names":[],"mappings":"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"}

package/dist/run/resolve.js

@@ -7,12 +7,18 @@
  * retryable failure the run loop asks for the next candidate.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.satisfiesRequirements = satisfiesRequirements;
 exports.resolveCandidates = resolveCandidates;
 exports.applyRunRequirements = applyRunRequirements;
 exports.candidateFilterFromOptions = candidateFilterFromOptions;
 exports.filterSummary = filterSummary;
 exports.mintRawCandidate = mintRawCandidate;
 exports.resolveDeclaredCandidate = resolveDeclaredCandidate;
+/** The live-resolver capability filter. Exported so the declare-first challenger
+ * eligibility (`registry/select.ts` `requirementPredicates` +
+ * `evaluateChallengerEligibility`) can pin itself in agreement with what would
+ * actually serve — an eligibility that drifted from the live filter would offer
+ * a challenger the route could never dispatch. */
 function satisfiesRequirements(route, flags, searchAvailable) {
     for (const requirement of route.require) {
         switch (requirement) {
@@ -56,11 +62,21 @@ function satisfiesRequirements(route, flags, searchAvailable) {
     }
     return true;
 }
-function resolveCandidates(route, capabilities, costUsdPerMTok, searchAvailable = false, filter, shadowWarmth) {
-    // Filter order (spec §4.1): provider only → provider ignore → capability+ZDR
-    // → maxPrice → prefer:[cost]. When `filter` is absent every step is a no-op,
-    // so the path is byte-for-byte the pre-G-2 behavior (back-compat).
+function resolveCandidates(route, capabilities, costUsdPerMTok, searchAvailable = false, filter, shadowWarmth, mode = "live") {
+    // Filter order (spec §4.1): trial-drop → provider only → provider ignore →
+    // capability+ZDR → maxPrice → prefer:[cost]. When `filter` is absent every
+    // step is a no-op, so the path is byte-for-byte the pre-G-2 behavior
+    // (back-compat).
     let pool = route.candidates;
+    // Declare-first (spec §4.4): a `trial` candidate is declared but NEVER served
+    // live — drop it first, exactly as a `providers.ignore` entry is dropped, on
+    // every live path. Only bake-off replay (`mode: "trial"`) keeps it. The
+    // candidate-set invariant is untouched: `route.candidates` (the declared set
+    // the run loop's runtime guard checks against) still includes trial entries;
+    // they are simply never minted into a CandidateRef on a live path.
+    if (mode === "live") {
+        pool = pool.filter((c) => c.trial !== true);
+    }
     if (filter?.only && filter.only.length > 0) {
         const only = new Set(filter.only);
         pool = pool.filter((c) => only.has(c.provider));

package/dist/run/routing-docs.js

@@ -47,7 +47,7 @@ exports.ROUTING_BOUNDARY = [
         id: "B2",
         status: "not_built",
         capability: "Structure on the raw lane",
-        statement: '`runRaw` never validates or repairs; `responseFormat: "json_object"` shapes MIME, not schema, so `meta.validated` stays false (ruled schema-free in CE-2 F4b; re-requested #223 R2).',
+        statement: '`runRaw` never validates or repairs; `responseFormat: "json_object"` shapes MIME, not schema, so `meta.validated` stays false — structure on the raw lane is ruled out by design, and the path is to graduate that step to a route.',
         tracking: "ruled schema-free on the raw lane; re-request on file",
         tripwire: { file: "src/run/raw.ts", mustNotMatch: /readonly outputSchema\??:/ },
     },