modelrig 0.3.0 → 0.5.0

package/dist/run/raw.js

@@ -29,10 +29,18 @@
  *    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).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertRawKnobsSupported = assertRawKnobsSupported;
@@ -47,11 +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
@@ -86,23 +120,29 @@ function buildRawAdapter(provider, apiKey) {
         }
     }
 }
-/** Providers that can honor a DECLARED raw-lane directive in v1 (spec §3
- * fail-closed matrix). Native grounding and reasoning are both gemini-only
- * today; the other adapters would silently ignore the field — exactly the bug
- * class CE-2 makes impossible. A new-provider entry here is a deliberate,
- * spec-gated widening, never an accident. */
-const NATIVE_GROUNDING_PROVIDERS = new Set(["gemini"]);
-const REASONING_PROVIDERS = new Set(["gemini"]);
 /**
- * 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.
  */
 function assertRawKnobsSupported(input) {
+    const support = raw_support_1.RAW_KNOB_SUPPORT[input.provider];
     const groundingMode = input.grounding?.mode;
     if (groundingMode !== undefined) {
         if (groundingMode !== "native") {
@@ -114,23 +154,35 @@ function assertRawKnobsSupported(input) {
                 fixHint: 'only { mode: "native" } grounding is supported on the raw lane in v1',
             });
         }
-        if (!NATIVE_GROUNDING_PROVIDERS.has(input.provider)) {
+        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 gemini-only in v1; remove grounding or switch provider",
+                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 && !REASONING_PROVIDERS.has(input.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,
-            fixHint: "reasoning control on the raw lane is gemini-only in v1; remove reasoning or switch provider",
+            // 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`,
         });
     }
 }
@@ -154,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.
@@ -163,6 +216,10 @@ function buildRawRequest(candidate, input) {
         ...(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 } : {}),
@@ -193,7 +250,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,
@@ -203,22 +263,66 @@ 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);
 }
+/**
+ * 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
+    // 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" };
+    // 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;
@@ -227,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,
@@ -239,8 +344,19 @@ function finalizeRaw(deps, input, result, latencyMs) {
             failureClass: result.failure.class,
             tags,
             pricingMissing,
+            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);
@@ -257,8 +373,10 @@ function finalizeRaw(deps, input, result, latencyMs) {
         failureClass: null,
         tags,
         pricingMissing,
+        callId,
         ...(input.cache !== undefined ? { cacheKey: input.cache.key } : {}),
     });
+    emitStep(id, null);
     const toolCalls = result.toolCalls;
     const isToolTurn = toolCalls !== undefined && toolCalls.length > 0;
     const meta = {
@@ -278,6 +396,7 @@ function finalizeRaw(deps, input, result, latencyMs) {
         attemptsByClass: {},
         servedVariant: null,
         repairedBy: null,
+        callId,
         ...(isToolTurn ? { toolCalls } : {}),
     };
     return { output: isToolTurn ? null : result.text, meta };
@@ -288,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 {
@@ -314,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) => {
@@ -350,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/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