modelrig 0.2.0 → 0.4.0

package/dist/run/raw.js

@@ -24,8 +24,26 @@
  *    `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).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertRawKnobsSupported = assertRawKnobsSupported;
 exports.buildRawRequest = buildRawRequest;
 exports.runRaw = runRaw;
 exports.runRawStream = runRawStream;
@@ -38,6 +56,7 @@ const openai_1 = require("../adapters/openai");
 const openai_compat_1 = require("../adapters/openai-compat");
 const cost_1 = require("./cost");
 const resolve_1 = require("./resolve");
+const 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. */
@@ -76,6 +95,72 @@ function buildRawAdapter(provider, apiKey) {
         }
     }
 }
+/**
+ * CE-2/CE-9 fail-closed guard (spec §3 F1/F3, CE-9 R1/R2/R4). A DECLARED
+ * directive is NEVER silently dropped: a `grounding`/`responseFormat` on a
+ * provider that cannot honor it, a `reasoning` on a provider with NO effort
+ * control (deepseek/anthropic), or a `grounding.mode` other than the
+ * v1-supported `"native"` throws `RigFailureError` `invariant_violation` (the
+ * existing TERMINAL class; no new FailureClass member) BEFORE any adapter is
+ * built, any provider call is made, or any telemetry row is written.
+ *
+ * The support facts come from `RAW_KNOB_SUPPORT` (run/raw-support.ts) — the ONE
+ * table the published docs matrix also reads, so the guard and the docs can
+ * never disagree (R5). What the guard does NOT reject (and why):
+ *  - reasoning on openai/deepinfra/fireworks is FORWARDED verbatim
+ *    (`kind: "forward"`) and the provider enforces — a rejection is classified
+ *    teachably by the adapter (no per-model allowlist, R1).
+ *  - reasoning on grok is a DISCLOSED coarsening (`kind: "coarsen"`).
+ *  - reasoning on gemini is model-gated (`kind: "model-gated"`) — the adapter
+ *    rejects a non-thinking model (`geminiReasoningUnsupported`).
+ * Exported so the guard is unit-testable without a network. Idempotent and
+ * side-effect-free.
+ */
+function assertRawKnobsSupported(input) {
+    const support = raw_support_1.RAW_KNOB_SUPPORT[input.provider];
+    const groundingMode = input.grounding?.mode;
+    if (groundingMode !== undefined) {
+        if (groundingMode !== "native") {
+            throw new failures_1.RigFailureError({
+                class: "invariant_violation",
+                message: `unsupported raw-lane grounding mode "${groundingMode}"`,
+                provider: input.provider,
+                model: input.model,
+                fixHint: 'only { mode: "native" } grounding is supported on the raw lane in v1',
+            });
+        }
+        if (!support.grounding.supported) {
+            throw new failures_1.RigFailureError({
+                class: "invariant_violation",
+                message: `native grounding on the raw lane is not supported for provider "${input.provider}"`,
+                provider: input.provider,
+                model: input.model,
+                fixHint: `native grounding on the raw lane is supported on ${(0, raw_support_1.groundingSupportedProviders)().join(", ")} only; remove grounding or switch provider`,
+            });
+        }
+    }
+    if (input.reasoning !== undefined && support.reasoning.kind === "fail-closed") {
+        throw new failures_1.RigFailureError({
+            class: "invariant_violation",
+            message: `reasoning control on the raw lane is not supported for provider "${input.provider}"`,
+            provider: input.provider,
+            model: input.model,
+            // Provider-specific teaching straight from the matrix (deepseek →
+            // deepseek-reasoner; anthropic → extended thinking unwired).
+            fixHint: support.reasoning.fixHint ??
+                "reasoning control is not available for this provider on the raw lane; remove reasoning",
+        });
+    }
+    if (input.responseFormat !== undefined && !support.responseFormat.supported) {
+        throw new failures_1.RigFailureError({
+            class: "invariant_violation",
+            message: `responseFormat on the raw lane is not supported for provider "${input.provider}"`,
+            provider: input.provider,
+            model: input.model,
+            fixHint: `responseFormat: "json_object" on the raw lane is supported on ${(0, raw_support_1.responseFormatSupportedProviders)().join(", ")} only; remove responseFormat or switch provider`,
+        });
+    }
+}
 /** Pure raw-lane request shaping — exported for unit tests (no network). */
 function buildRawRequest(candidate, input) {
     // CE-6: forward temperature/topP through AdapterRequest.sampling ONLY when the
@@ -93,10 +178,22 @@ function buildRawRequest(candidate, input) {
         systemPrompt: input.systemPrompt,
         userPrompt: input.userPrompt,
         outputSchema: null, // raw lane never validates — the product distinction
-        requestedTier: "standard",
+        // 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,
         ...(input.maxOutputTokens !== undefined ? { maxOutputTokens: input.maxOutputTokens } : {}),
         ...(sampling !== undefined ? { sampling } : {}),
+        // CE-2 F1: `{ mode: "native" }` → the adapter's native-grounding directive.
+        // Any other mode / unsupported provider never reaches here — the guard
+        // (assertRawKnobsSupported) rejects it pre-dispatch. Absent ⇒ no key added.
+        ...(input.grounding?.mode === "native" ? { grounding: true } : {}),
+        // CE-2 F3: forward reasoning verbatim; absent ⇒ no key added (byte-identical).
+        ...(input.reasoning !== undefined ? { reasoning: input.reasoning } : {}),
+        // CE-9 R4: forward the json_object directive verbatim; absent ⇒ no key added
+        // (byte-identical). An unsupported provider (anthropic) never reaches here —
+        // the guard (assertRawKnobsSupported) rejects it pre-dispatch.
+        ...(input.responseFormat !== undefined ? { responseFormat: input.responseFormat } : {}),
         ...(input.tools !== undefined ? { tools: input.tools } : {}),
         ...(input.toolChoice !== undefined ? { toolChoice: input.toolChoice } : {}),
         ...(input.cache !== undefined ? { cache: input.cache } : {}),
@@ -115,7 +212,7 @@ function recordRawRow(telemetry, p) {
         routeVersion: 0,
         provider: p.provider,
         model: p.model,
-        requestedTier: "standard",
+        requestedTier: p.requestedTier,
         servedTier: p.usage?.servedTier ?? "standard",
         tokensIn: p.usage?.tokensIn ?? 0,
         tokensOut: p.usage?.tokensOut ?? 0,
@@ -127,7 +224,10 @@ function recordRawRow(telemetry, p) {
         ttfbMs: p.usage?.ttfbMs ?? null,
         failureClass: p.failureClass,
         attemptsJson: "{}",
-        tagsJson: JSON.stringify(p.tags),
+        // Rung tag (R1 review, F1): the raw lane is a single primary dispatch. Raw
+        // rows carry `lane: "raw"` and are excluded from route rollups, but every row
+        // gets a rung for a uniform contract.
+        tagsJson: JSON.stringify({ ...p.tags, rung: "primary" }),
         fingerprintCell: null,
         servedVariant: null,
         repairedBy: null,
@@ -137,6 +237,10 @@ function recordRawRow(telemetry, p) {
         // provenance rule reads any non-null key here as `customer`.
         cacheKey: p.cacheKey ?? null,
         prefixFingerprint: null,
+        // Ladder key (spec §2.1 R0): raw lane = one row per call, seq 1, index 0.
+        callId: p.callId,
+        attemptSeq: 1,
+        candidateIndex: 0,
     };
     telemetry.record(row);
 }
@@ -149,6 +253,11 @@ function recordRawRow(telemetry, p) {
 function finalizeRaw(deps, input, result, latencyMs) {
     const unpricedRatePerTok = (deps.unpricedRateUsdPerMTok ?? cost_1.DEFAULT_UNPRICED_RATE_USD_PER_MTOK) / 1000000;
     const rawModelId = `${input.provider}/${input.model}`;
+    // One call_id for this raw invocation — shared by the (single) recorded row and
+    // the returned meta (spec §2.1 R0).
+    const callId = (0, node_crypto_1.randomUUID)();
+    // CE-2 F2: the declared tier is reported truthfully on the row AND the meta.
+    const requestedTier = input.serviceTier ?? "standard";
     // lane is SDK-owned and cannot be overridden by a caller-supplied tag.
     const tags = { ...(input.tags ?? {}), lane: "raw" };
     if (!result.ok) {
@@ -167,9 +276,11 @@ function finalizeRaw(deps, input, result, latencyMs) {
             ...(result.usage !== undefined ? { usage: result.usage } : {}),
             costUsd,
             latencyMs,
+            requestedTier,
             failureClass: result.failure.class,
             tags,
             pricingMissing,
+            callId,
             ...(input.cache !== undefined ? { cacheKey: input.cache.key } : {}),
         });
         throw new failures_1.RigFailureError(result.failure);
@@ -184,9 +295,11 @@ function finalizeRaw(deps, input, result, latencyMs) {
         usage: result.usage,
         costUsd,
         latencyMs,
+        requestedTier,
         failureClass: null,
         tags,
         pricingMissing,
+        callId,
         ...(input.cache !== undefined ? { cacheKey: input.cache.key } : {}),
     });
     const toolCalls = result.toolCalls;
@@ -197,7 +310,7 @@ function finalizeRaw(deps, input, result, latencyMs) {
         routeVersion: 0,
         provider: input.provider,
         model: input.model,
-        requestedTier: "standard",
+        requestedTier,
         servedTier: result.usage.servedTier,
         tokensIn: result.usage.tokensIn,
         tokensOut: result.usage.tokensOut,
@@ -208,6 +321,7 @@ function finalizeRaw(deps, input, result, latencyMs) {
         attemptsByClass: {},
         servedVariant: null,
         repairedBy: null,
+        callId,
         ...(isToolTurn ? { toolCalls } : {}),
     };
     return { output: isToolTurn ? null : result.text, meta };
@@ -215,6 +329,9 @@ function finalizeRaw(deps, input, result, latencyMs) {
 /** Buffered raw dispatch (spec §4.2). Records telemetry, returns the RunResult,
  * or throws `RigFailureError` on an adapter failure. */
 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);
     const adapter = buildRawAdapter(input.provider, input.apiKey);
     const candidate = (0, resolve_1.mintRawCandidate)(input.provider, input.model);
     const started = Date.now();
@@ -251,11 +368,15 @@ function runRawStream(deps, input) {
     // the events iterator surfaces the same error to whoever drains it.
     result.catch(() => { });
     async function* events() {
-        const adapter = buildRawAdapter(input.provider, input.apiKey);
-        const candidate = (0, resolve_1.mintRawCandidate)(input.provider, input.model);
-        const req = buildRawRequest(candidate, input);
-        const started = Date.now();
         try {
+            // CE-2 F1/F3: fail closed on an unsupported declared directive BEFORE any
+            // adapter/dispatch — surfaced through the handle (result rejects, the
+            // events iterator throws), so no meter, no provider call, no telemetry row.
+            assertRawKnobsSupported(input);
+            const adapter = buildRawAdapter(input.provider, input.apiKey);
+            const candidate = (0, resolve_1.mintRawCandidate)(input.provider, input.model);
+            const req = buildRawRequest(candidate, input);
+            const started = Date.now();
             let adapterResult;
             if (adapter.stream !== undefined) {
                 let final = null;

package/dist/run/rawonly.d.ts

@@ -0,0 +1,60 @@
+/**
+ * runRaw-only construction — CE-8 (ruling R1,
+ * `docs/ModelRig/customer-efficiency/ce8-runraw-only-rig-spec-plan.md`).
+ *
+ * A Lane-B customer who only calls `rig.runRaw`/`rig.runRawStream` has no routes.
+ * With `routesDir: null`, `createRig` SKIPS route loading, the `rig.yaml`
+ * manifest, and the serveable-candidate gate — so a stray route file (or a route
+ * whose provider key is absent in this deployment) can no longer down a rig that
+ * never serves it. The raw lane is unchanged; every route-dependent surface
+ * (`run`/`runStream`/`runBundle`/`replay`/`bakeoff`/`verifySwap`) fails with a
+ * TERMINAL `invariant_violation` that teaches the fix — Promise surfaces reject,
+ * the two streaming surfaces hand back a handle whose `result`/`events` fail
+ * (never a synchronous throw, matching the real `runStream` contract).
+ *
+ * This module holds the small pieces of that opt-out (the empty store, the
+ * teaching failure, the throwing route methods) so `index.ts` stays under the
+ * 700-LOC cap — `createRig` remains the ONE construction path (a separate
+ * `createRawRig()` factory was considered and REJECTED, spec §2 R1).
+ */
+import type { RigConfig } from "../config";
+import { type LoadedRoutes } from "../routes/loader";
+import { RigFailureError } from "../types/failures";
+import type { Rig } from "../index";
+/** The teaching remediation for a route-lane call on a runRaw-only rig (spec §2
+ * R1). One constant so the failure and the docs stay in lock-step. */
+export declare const RAW_ONLY_FIX_HINT = "this rig was constructed runRaw-only (routesDir: null); give createRig a routesDir to serve routes";
+/** Build the TERMINAL failure a route-dependent surface throws when the rig was
+ * constructed runRaw-only. Reuses `invariant_violation` (already TERMINAL + in
+ * the teaching table) — no new FailureClass (spec §3 rationale). */
+export declare function rawOnlyRouteFailure(surface: string): RigFailureError;
+/** Narrow a config's `routesDir` to a string for a route-REQUIRED context (the
+ * route-oriented CLI subcommands: bakeoff/watch/swap/init/observe/validate),
+ * throwing the teaching failure if the rig was built runRaw-only.
+ * `loadConfigFromEnv` always yields a string (R2), so this is unreachable for
+ * env-built configs — it guards a hand-built `routesDir: null` reaching a
+ * route-only command, and satisfies the `string | null` type at those seams. */
+export declare function requireRoutesDir(config: RigConfig, surface: string): string;
+/** The empty route store for a runRaw-only rig: `list()` is `[]` (so
+ * serveability, capture-detection, and the exported route mirror are all no-ops)
+ * and `get()` teaches, though no public surface reaches it — every route method
+ * is overridden by {@link rawOnlyRouteMethods}. */
+export declare function emptyRouteStore(): LoadedRoutes;
+/** Load routes from a real (string) `routesDir`, mirroring a malformed-bundle
+ * diagnosis to the console before re-throwing — the byte-for-byte behaviour the
+ * string path had inline in `createRig` before CE-8 extracted it here. */
+export declare function loadRoutesOrReport(config: RigConfig, routesDir: string): LoadedRoutes;
+/** The route-dependent slice of the {@link Rig} surface, replaced wholesale when
+ * `routesDir === null` so every one of them throws the teaching failure rather
+ * than dereferencing an empty store. Spread LAST over the real methods in
+ * `createRig`, so later keys win. */
+type RouteMethods = Pick<Rig, "run" | "runStream" | "runBundle" | "runBundleStream" | "replay" | "bakeoff" | "bakeoffFromEvalCases" | "verifySwap">;
+/** The throwing overrides for a runRaw-only rig (spec §2 R1). Each names the
+ * surface + the route/task the caller asked for, so the terminal error points at
+ * exactly the call that needs a `routesDir`. Promise-returning surfaces REJECT
+ * (matching the routed lane, where errors surface as rejections); the two
+ * streaming surfaces return a handle synchronously, so they throw synchronously
+ * — the caller never reaches an event to await. */
+export declare function rawOnlyRouteMethods(): RouteMethods;
+export {};
+//# sourceMappingURL=rawonly.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rawonly.d.ts","sourceRoot":"","sources":["../../src/run/rawonly.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAyC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE5F,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC;sEACsE;AACtE,eAAO,MAAM,iBAAiB,uGACwE,CAAC;AAEvG;;oEAEoE;AACpE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAMpE;AAsBD;;;;;gFAKgF;AAChF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAG3E;AAED;;;mDAGmD;AACnD,wBAAgB,eAAe,IAAI,YAAY,CAS9C;AAED;;0EAE0E;AAC1E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CASrF;AAED;;;qCAGqC;AACrC,KAAK,YAAY,GAAG,IAAI,CACtB,GAAG,EACD,KAAK,GACL,WAAW,GACX,WAAW,GACX,iBAAiB,GACjB,QAAQ,GACR,SAAS,GACT,sBAAsB,GACtB,YAAY,CACf,CAAC;AAEF;;;;;mDAKmD;AACnD,wBAAgB,mBAAmB,IAAI,YAAY,CAYlD"}

package/dist/run/rawonly.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * runRaw-only construction — CE-8 (ruling R1,
+ * `docs/ModelRig/customer-efficiency/ce8-runraw-only-rig-spec-plan.md`).
+ *
+ * A Lane-B customer who only calls `rig.runRaw`/`rig.runRawStream` has no routes.
+ * With `routesDir: null`, `createRig` SKIPS route loading, the `rig.yaml`
+ * manifest, and the serveable-candidate gate — so a stray route file (or a route
+ * whose provider key is absent in this deployment) can no longer down a rig that
+ * never serves it. The raw lane is unchanged; every route-dependent surface
+ * (`run`/`runStream`/`runBundle`/`replay`/`bakeoff`/`verifySwap`) fails with a
+ * TERMINAL `invariant_violation` that teaches the fix — Promise surfaces reject,
+ * the two streaming surfaces hand back a handle whose `result`/`events` fail
+ * (never a synchronous throw, matching the real `runStream` contract).
+ *
+ * This module holds the small pieces of that opt-out (the empty store, the
+ * teaching failure, the throwing route methods) so `index.ts` stays under the
+ * 700-LOC cap — `createRig` remains the ONE construction path (a separate
+ * `createRawRig()` factory was considered and REJECTED, spec §2 R1).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAW_ONLY_FIX_HINT = void 0;
+exports.rawOnlyRouteFailure = rawOnlyRouteFailure;
+exports.requireRoutesDir = requireRoutesDir;
+exports.emptyRouteStore = emptyRouteStore;
+exports.loadRoutesOrReport = loadRoutesOrReport;
+exports.rawOnlyRouteMethods = rawOnlyRouteMethods;
+const loader_1 = require("../routes/loader");
+const load_error_report_1 = require("../telemetry/load-error-report");
+const failures_1 = require("../types/failures");
+/** The teaching remediation for a route-lane call on a runRaw-only rig (spec §2
+ * R1). One constant so the failure and the docs stay in lock-step. */
+exports.RAW_ONLY_FIX_HINT = "this rig was constructed runRaw-only (routesDir: null); give createRig a routesDir to serve routes";
+/** Build the TERMINAL failure a route-dependent surface throws when the rig was
+ * constructed runRaw-only. Reuses `invariant_violation` (already TERMINAL + in
+ * the teaching table) — no new FailureClass (spec §3 rationale). */
+function rawOnlyRouteFailure(surface) {
+    return new failures_1.RigFailureError({
+        class: "invariant_violation",
+        message: `${surface} needs routes, but this rig was constructed runRaw-only (routesDir: null)`,
+        fixHint: exports.RAW_ONLY_FIX_HINT,
+    });
+}
+/** A `RunStreamHandle` that fails the runRaw-only way: `result` rejects and the
+ * `events` iterator throws — matching the real `runStream` contract, which NEVER
+ * throws synchronously (a stream surface always hands back a handle, errors ride
+ * `result`/`events`). A synchronous throw here would break the caller's
+ * `const h = rig.runStream(...); await h.result` shape. */
+function rawOnlyStreamHandle(surface) {
+    const err = rawOnlyRouteFailure(surface);
+    const result = Promise.reject(err);
+    // Keep the rejection handled so an unconsumed handle never becomes an
+    // unhandledRejection; the events iterator surfaces the same error.
+    result.catch(() => undefined);
+    const events = {
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async *[Symbol.asyncIterator]() {
+            throw err;
+        },
+    };
+    return { events, result };
+}
+/** Narrow a config's `routesDir` to a string for a route-REQUIRED context (the
+ * route-oriented CLI subcommands: bakeoff/watch/swap/init/observe/validate),
+ * throwing the teaching failure if the rig was built runRaw-only.
+ * `loadConfigFromEnv` always yields a string (R2), so this is unreachable for
+ * env-built configs — it guards a hand-built `routesDir: null` reaching a
+ * route-only command, and satisfies the `string | null` type at those seams. */
+function requireRoutesDir(config, surface) {
+    if (config.routesDir === null)
+        throw rawOnlyRouteFailure(surface);
+    return config.routesDir;
+}
+/** The empty route store for a runRaw-only rig: `list()` is `[]` (so
+ * serveability, capture-detection, and the exported route mirror are all no-ops)
+ * and `get()` teaches, though no public surface reaches it — every route method
+ * is overridden by {@link rawOnlyRouteMethods}. */
+function emptyRouteStore() {
+    return {
+        get(route) {
+            throw rawOnlyRouteFailure(`get("${route}")`);
+        },
+        list() {
+            return Object.freeze([]);
+        },
+    };
+}
+/** Load routes from a real (string) `routesDir`, mirroring a malformed-bundle
+ * diagnosis to the console before re-throwing — the byte-for-byte behaviour the
+ * string path had inline in `createRig` before CE-8 extracted it here. */
+function loadRoutesOrReport(config, routesDir) {
+    try {
+        return (0, loader_1.loadRoutesWithExtra)(routesDir, config.extraRoutesDir);
+    }
+    catch (err) {
+        // A malformed bundle is teachable, not just fatal: mirror the diagnosis to
+        // the console before re-throwing (the rig still cannot serve).
+        if (err instanceof loader_1.RouteConfigError)
+            (0, load_error_report_1.reportLoadError)(config, err);
+        throw err;
+    }
+}
+/** The throwing overrides for a runRaw-only rig (spec §2 R1). Each names the
+ * surface + the route/task the caller asked for, so the terminal error points at
+ * exactly the call that needs a `routesDir`. Promise-returning surfaces REJECT
+ * (matching the routed lane, where errors surface as rejections); the two
+ * streaming surfaces return a handle synchronously, so they throw synchronously
+ * — the caller never reaches an event to await. */
+function rawOnlyRouteMethods() {
+    return {
+        run: (route) => Promise.reject(rawOnlyRouteFailure(`run("${route}")`)),
+        runStream: (route) => rawOnlyStreamHandle(`runStream("${route}")`),
+        runBundle: (bundle) => Promise.reject(rawOnlyRouteFailure(`runBundle("${bundle.route}")`)),
+        runBundleStream: (bundle) => rawOnlyStreamHandle(`runBundleStream("${bundle.route}")`),
+        replay: (route) => Promise.reject(rawOnlyRouteFailure(`replay("${route}")`)),
+        bakeoff: (route) => Promise.reject(rawOnlyRouteFailure(`bakeoff("${route}")`)),
+        bakeoffFromEvalCases: (task) => Promise.reject(rawOnlyRouteFailure(`bakeoffFromEvalCases("${task}")`)),
+        verifySwap: (route) => Promise.reject(rawOnlyRouteFailure(`verifySwap("${route}")`)),
+    };
+}

package/dist/run/record-attempt.d.ts

@@ -13,11 +13,17 @@ import type { AttemptTelemetry } from "./dispatch";
 import type { ActiveRunContext } from "../artifacts/run-context";
 import type { RetryLedger } from "./retry";
 import type { RouteBundle, RunOptions, RunTags } from "../types/route";
-import type { TelemetryStore } from "../types/telemetry";
+import type { TelemetryRung, TelemetryStore } from "../types/telemetry";
+import type { LadderKeyMinter } from "./ladder-key";
 export interface RecordAttemptDeps {
     readonly telemetry: TelemetryStore;
     readonly route: RouteBundle;
     readonly ledger: RetryLedger;
+    /** Per-call ladder-key minter (spec §2.1 R0) — every row this recorder writes
+     * is stamped with the call's id, its 1-based attempt_seq, and the current
+     * candidate index. Shared by reference with the run loop, which advances the
+     * candidate index as the iterator moves. */
+    readonly ladder: LadderKeyMinter;
     readonly effectiveTags: RunTags;
     readonly servedVariant: string | null;
     /** Active run context (E2 chunk A) or null when the artifact namespace is off. */
@@ -33,6 +39,13 @@ export interface RecordAttemptDeps {
      * uncached), exactly matching the request builder's suppression. */
     readonly droppedCacheHandle: ReadonlySet<string>;
 }
+/**
+ * Classify a recorded row's ladder rung (R1 review, F1). `primaryDispatched`
+ * carries the candidate indices already given a primary dispatch on this call —
+ * mutated here so the next same-index non-repair dispatch reads `retry`.
+ * Exported for unit tests; the run loop reaches it only through the recorder.
+ */
+export declare function rungOf(attempt: AttemptTelemetry, preDispatch: boolean, candidateIndex: number | null, primaryDispatched: Set<number>): TelemetryRung;
 /** Build the run loop's `recordAttempt(attempt) => inferenceId` over this run's
  * state. Records one inference row and, with an active run context, mirrors it
  * as a ground-truth step (fail-open). */

package/dist/run/record-attempt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record-attempt.d.ts","sourceRoot":"","sources":["../../src/run/record-attempt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIvE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;qFAEiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IACrC;;;wEAGoE;IACpE,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAClD;AAED;;yCAEyC;AACzC,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,CA6ElG"}
+{"version":3,"file":"record-attempt.d.ts","sourceRoot":"","sources":["../../src/run/record-attempt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAgB,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGtF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;gDAG4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;qFAEiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IACrC;;;wEAGoE;IACpE,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAClD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,gBAAgB,EACzB,WAAW,EAAE,OAAO,EACpB,cAAc,EAAE,MAAM,GAAG,IAAI,EAC7B,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,GAC7B,aAAa,CAUf;AAED;;yCAEyC;AACzC,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,CA+FlG"}

package/dist/run/record-attempt.js

@@ -11,17 +11,45 @@
  * in-flight E4 / capture-write work (plan coordination note).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.rungOf = rungOf;
 exports.createRecordAttempt = createRecordAttempt;
 const node_crypto_1 = require("node:crypto");
 const failures_1 = require("../types/failures");
 const cache_stamp_1 = require("./cache-stamp");
 const cache_handle_1 = require("./cache-handle");
+/**
+ * Classify a recorded row's ladder rung (R1 review, F1). `primaryDispatched`
+ * carries the candidate indices already given a primary dispatch on this call —
+ * mutated here so the next same-index non-repair dispatch reads `retry`.
+ * Exported for unit tests; the run loop reaches it only through the recorder.
+ */
+function rungOf(attempt, preDispatch, candidateIndex, primaryDispatched) {
+    if (attempt.rung !== undefined)
+        return attempt.rung; // explicit (tool-call path)
+    if (attempt.repairedBy !== undefined)
+        return "repair";
+    if (preDispatch)
+        return "predispatch_fail";
+    // A real primary/retry candidate dispatch. First time this index is dispatched
+    // ⇒ primary; any later dispatch of the same index ⇒ retry.
+    if (candidateIndex === null)
+        return "primary";
+    if (primaryDispatched.has(candidateIndex))
+        return "retry";
+    primaryDispatched.add(candidateIndex);
+    return "primary";
+}
 /** Build the run loop's `recordAttempt(attempt) => inferenceId` over this run's
  * state. Records one inference row and, with an active run context, mirrors it
  * as a ground-truth step (fail-open). */
 function createRecordAttempt(deps) {
     const { telemetry, route, ledger, effectiveTags, servedVariant, runCtx, autoStepKey } = deps;
-    const { cache, droppedCacheHandle } = deps;
+    const { cache, droppedCacheHandle, ladder } = deps;
+    // The candidate indices for which a real primary dispatch has already been
+    // recorded on THIS call — so the SECOND non-repair dispatch of a candidate
+    // stamps `retry` rather than a second `primary` (R1 review, F1). Held in the
+    // per-call closure (the recorder is built once per invocation).
+    const primaryDispatched = new Set();
     return function recordAttempt(attempt) {
         // Request-path cache substrate (WS-C): derived from the SAME pure gate the
         // dispatcher stamps the request with, so `cache_key`/`prefix_fingerprint` on
@@ -53,6 +81,16 @@ function createRecordAttempt(deps) {
         const dropped = droppedCacheHandle.has(`${attempt.candidate.provider} ${attempt.candidate.model}`);
         const customer = isPrimary && !preDispatch ? (0, cache_handle_1.customerCacheHandle)(cache, attempt.candidate, dropped) : null;
         const cacheKey = customer?.key ?? cacheStamp?.cacheKey ?? null;
+        // Ladder key (spec §2.1 R0): one stamp per row — shared call_id, monotonic
+        // attempt_seq, and the current candidate_index (the candidate being repaired
+        // for a repair row, since the iterator has not advanced during its turn).
+        const ladderKey = ladder.stamp();
+        // Rung tag (R1 review, F1): the row's place on the ladder, so the rollup and
+        // ladder view never guess. Precedence: an explicit hint from the caller
+        // (only the tool-call path sets one) wins; then a repair row, then a
+        // pre-dispatch terminal failure, then primary-vs-retry by whether this
+        // candidate index was already dispatched on this call.
+        const rung = rungOf(attempt, preDispatch, ladderKey.candidateIndex, primaryDispatched);
         const row = {
             id: (0, node_crypto_1.randomUUID)(),
             ts: new Date().toISOString(),
@@ -75,11 +113,14 @@ function createRecordAttempt(deps) {
             ttfbMs: attempt.ttfbMs ?? null,
             failureClass: attempt.failure?.class ?? null,
             attemptsJson: JSON.stringify(ledger.snapshot()),
-            tagsJson: JSON.stringify(effectiveTags),
+            tagsJson: JSON.stringify({ ...effectiveTags, rung }),
             fingerprintCell: route.fingerprintCell,
             servedVariant,
             repairedBy: attempt.repairedBy ?? null,
             pricingMissing: attempt.pricingMissing ?? false,
+            callId: ladderKey.callId,
+            attemptSeq: ladderKey.attemptSeq,
+            candidateIndex: ladderKey.candidateIndex,
         };
         telemetry.record(row);
         // Mirror this inference into a ground-truth step attempt (fail-open — the

package/dist/run/resolve.d.ts

@@ -12,6 +12,10 @@ export type CapabilityLookup = (provider: ProviderId, model: string) => Readonly
 export interface CandidateIterator {
     /** Next eligible candidate, or null when the set is exhausted. */
     next(): CandidateRef | null;
+    /** Position in the EFFECTIVE eligible list of the candidate the most recent
+     * `next()` returned (0 = first eligible; ladder key, spec §2.1). `-1` before
+     * the first `next()`; unchanged by a `next()` that returns null. */
+    readonly index: number;
 }
 /**
  * Request-time candidate filters (G-2) — optional, applied by resolveCandidates

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;CAC7B;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,CAkFnB;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":"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"}

package/dist/run/resolve.js

@@ -124,10 +124,17 @@ function resolveCandidates(route, capabilities, costUsdPerMTok, searchAvailable
     // minted. The cast below is the single sanctioned exception to the
     // "no `as CandidateRef`" grep (scoped to run/resolve.ts in CI).
     const refs = ordered.map((c) => Object.freeze({ provider: c.provider, model: c.model }));
-    let index = 0;
+    let cursor = 0;
+    let lastIndex = -1;
     return {
         next() {
-            return index < refs.length ? refs[index++] : null;
+            if (cursor >= refs.length)
+                return null;
+            lastIndex = cursor;
+            return refs[cursor++];
+        },
+        get index() {
+            return lastIndex;
         },
     };
 }