modelrig 0.10.0 → 0.11.1

package/dist/run/raw-finalize.js

@@ -11,7 +11,9 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rawTimeoutFixHint = rawTimeoutFixHint;
+exports.recordRawRow = recordRawRow;
 exports.prepareRawStep = prepareRawStep;
+exports.emitRawStep = emitRawStep;
 exports.finalizeRaw = finalizeRaw;
 const node_crypto_1 = require("node:crypto");
 const cost_1 = require("./cost");
@@ -55,7 +57,7 @@ function recordRawRow(telemetry, p) {
         provider: p.provider,
         model: p.model,
         requestedTier: p.requestedTier,
-        servedTier: p.usage?.servedTier ?? "standard",
+        servedTier: p.usage?.servedTier ?? p.servedTier ?? "standard",
         tokensIn: p.usage?.tokensIn ?? 0,
         tokensOut: p.usage?.tokensOut ?? 0,
         tokensCached: p.usage?.tokensCached ?? 0,
@@ -106,6 +108,22 @@ function prepareRawStep(deps, input) {
     const stepKey = (0, run_context_1.resolveStepKey)(input.stepKey, input.tags?.step, () => runCtx.nextStepKey(rawModelId));
     return { runCtx, stepKey, startedAtIso: new Date().toISOString() };
 }
+/** G1: mirror one lane-B inference (raw, or an OBS-1 recorded call) into a
+ * ground-truth step — parity with the routed lane's record-attempt. No-op when
+ * no run context was captured at entry. Fail-open is handled inside
+ * `emitGroundTruthStep` (buffer errors are swallowed). */
+function emitRawStep(step, task, inferenceId, failureClass) {
+    if (step === null)
+        return;
+    step.runCtx.emitGroundTruthStep({
+        stepKey: step.stepKey,
+        task,
+        inferenceId,
+        startedAt: step.startedAtIso,
+        endedAt: new Date().toISOString(),
+        failureClass,
+    });
+}
 /**
  * Turn an `AdapterResult` into a RunResult, recording exactly one telemetry row.
  * Shared by the buffered and streaming paths so cost/telemetry are byte-identical.
@@ -132,7 +150,17 @@ function finalizeRaw(deps, input, result, latencyMs, step) {
     // caller set none — spread FIRST so a caller value wins, and omitted entirely
     // outside a run context so the row stays byte-identical (parity with RC-1).
     const stepTag = step !== null ? { step: step.stepKey } : {};
-    const tags = { ...stepTag, ...(0, run_context_1.withRunIdTag)(input.tags ?? {}, step?.runCtx ?? null), lane: "raw" };
+    // L6 (OBS-1 follow-up, architect ruling Q2): the raw lane dispatches ONLY on
+    // the caller's own provider key (`input.apiKey` — there is no managed-key path
+    // here; the hosted gateway resolves a BYOK vault key fail-closed), so every raw
+    // row is BYOK by construction. `key_ownership: "byok"` is SDK-owned and stamped
+    // LAST beside `lane`, so an in-process runRaw row can never settle as managed.
+    const tags = {
+        ...stepTag,
+        ...(0, run_context_1.withRunIdTag)(input.tags ?? {}, step?.runCtx ?? null),
+        key_ownership: "byok",
+        lane: "raw",
+    };
     // WI-1 (spec §2, §6.3 lane parity): the attempt envelope, built by the SAME
     // producer + rendered-request canonicalization the routed lane uses. R2: a
     // declared `responseSchema` joins the input_hash exactly as a route schema
@@ -154,18 +182,7 @@ function finalizeRaw(deps, input, result, latencyMs, step) {
     // 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,
-        });
-    };
+    const emitStep = (inferenceId, failureClass) => emitRawStep(step, input.tags?.step ?? rawModelId, inferenceId, failureClass);
     if (!result.ok) {
         let costUsd = 0;
         let pricingMissing = false;

package/dist/run/raw-search-cost.d.ts

@@ -25,8 +25,9 @@ import type { TelemetryStore } from "../types/telemetry";
  * provider is the real dispatch provider so the surcharge is attributed to it. */
 export declare const NATIVE_WEB_SEARCH_MODEL = "web_search";
 export interface RawSearchCostArgs {
-    /** The real dispatch provider (openai / grok) — the row's `provider`. */
-    readonly provider: ProviderId;
+    /** The real dispatch provider (openai / grok) — the row's `provider`. An
+     * OBS-1 recorded call may name a provider ModelRig has no rate for (⇒ $0). */
+    readonly provider: ProviderId | string;
     /** The `provider/model` handle the caller used — the row's `route`. */
     readonly rawModelId: string;
     /** The effective tags already stamped on the primary raw row (lane:"raw",

package/dist/run/raw-search-cost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"raw-search-cost.d.ts","sourceRoot":"","sources":["../../src/run/raw-search-cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIvE;;kFAEkF;AAClF,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;8EAC0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;kEAC8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAyC/F"}
+{"version":3,"file":"raw-search-cost.d.ts","sourceRoot":"","sources":["../../src/run/raw-search-cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIvE;;kFAEkF;AAClF,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC;kFAC8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC;IACvC,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;8EAC0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;kEAC8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CA0C/F"}

package/dist/run/raw-search-cost.js

@@ -36,6 +36,7 @@ exports.NATIVE_WEB_SEARCH_MODEL = "web_search";
  */
 function recordRawSearchCostRow(telemetry, args) {
     const searchCalls = Math.max(1, args.searchCalls);
+    // An unknown provider has no WEB_SEARCH_PRICING entry ⇒ webSearchPerCallUsd's `?.` yields 0.
     const costEstimateUsd = (0, web_search_pricing_1.webSearchPerCallUsd)(args.provider) * searchCalls;
     // U4: assembled by the ONE shared builder (./telemetry-row.ts). `rung:"search"`
     // and `attemptSeq: 2` (so it never collides with the primary raw row's

package/dist/run/rawonly.d.ts

@@ -17,7 +17,7 @@
  * 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 RigConfig } from "../config";
 import { type LoadedRoutes } from "../routes/loader";
 import { RigFailureError } from "../types/failures";
 import type { Rig } from "../index";
@@ -27,7 +27,12 @@ export declare const RAW_ONLY_FIX_HINT = "this rig was constructed runRaw-only (
 /** 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;
+/** Why a rig is raw-only: constructed with `routesDir: null`, or fell back
+ * because the default routes directory is absent (SURF-1). */
+export type RawOnlyReason = "routesDir-null" | "absent-default";
+/** The fix hint when the absent-default fallback made the rig raw-only. */
+export declare const ABSENT_DEFAULT_FIX_HINT = "create ./modelrig/routes with your route files (`npx modelrig init` drafts them), or set MODELRIG_ROUTES_DIR";
+export declare function rawOnlyRouteFailure(surface: string, reason?: RawOnlyReason): 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.
@@ -35,6 +40,21 @@ export declare function rawOnlyRouteFailure(surface: string): RigFailureError;
  * 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 warning createRig prints when it falls back to a raw-only rig because the
+ * DEFAULT routes directory does not exist (SURF-1, audit #1). One constant so
+ * the docs and the test quote the same words. */
+export declare const ABSENT_DEFAULT_ROUTES_WARNING: string;
+/**
+ * The routes directory createRig actually loads (SURF-1 ruling on audit #1):
+ *  - `null` stays `null` (CE-8 runRaw-only, silent);
+ *  - the UNCONFIGURED default (loadConfigFromEnv filled in `./modelrig/routes`;
+ *    no MODELRIG_ROUTES_DIR, no routesDir override, no `extraRoutesDir`) that
+ *    does not exist on disk → warn once, return `null`, so
+ *    a customer who only records calls never crashes on import;
+ *  - anything explicitly configured is returned as-is, and a missing one still
+ *    throws the teaching RouteConfigError from the loader.
+ */
+export declare function effectiveRoutesDir(config: RigConfig): string | null;
 /** 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
@@ -48,13 +68,17 @@ export declare function loadRoutesOrReport(config: RigConfig, routesDir: string)
  * `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
+type RouteMethods = Pick<Rig, "run" | "runStream" | "runBundle" | "runBundleStream" | "replay" | "bakeoff" | "verifySwap">;
+/** The throwing overrides for a runRaw-only rig (spec §2 R1).
+ * `bakeoffFromEvalCases` is deliberately NOT overridden (SURF-1, audit #12): it
+ * reads eval cases from the local store first, so with none promoted (or none
+ * rehydratable) it reports honestly without any routes dir; only a case that
+ * actually replays reaches `routes.get`, which teaches the same failure. 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 declare function rawOnlyRouteMethods(reason?: RawOnlyReason): RouteMethods;
 export {};
 //# sourceMappingURL=rawonly.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"rawonly.d.ts","sourceRoot":"","sources":["../../src/run/rawonly.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAC/D,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;8DAC8D;AAC9D,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAEhE,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,iHAC4E,CAAC;AAEjH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,aAAgC,GAAG,eAAe,CAS9G;AAsBD;;;;;gFAKgF;AAChF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAG3E;AAED;;iDAEiD;AACjD,eAAO,MAAM,6BAA6B,QAIW,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAQnE;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,YAAY,CACf,CAAC;AAEF;;;;;;;;;mDASmD;AACnD,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,aAAgC,GAAG,YAAY,CAW1F"}

package/dist/run/rawonly.js

@@ -19,26 +19,30 @@
  * `createRawRig()` factory was considered and REJECTED, spec §2 R1).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RAW_ONLY_FIX_HINT = void 0;
+exports.ABSENT_DEFAULT_ROUTES_WARNING = exports.ABSENT_DEFAULT_FIX_HINT = exports.RAW_ONLY_FIX_HINT = void 0;
 exports.rawOnlyRouteFailure = rawOnlyRouteFailure;
 exports.requireRoutesDir = requireRoutesDir;
+exports.effectiveRoutesDir = effectiveRoutesDir;
 exports.emptyRouteStore = emptyRouteStore;
 exports.loadRoutesOrReport = loadRoutesOrReport;
 exports.rawOnlyRouteMethods = rawOnlyRouteMethods;
+const node_fs_1 = require("node:fs");
+const config_1 = require("../config");
 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) {
+/** The fix hint when the absent-default fallback made the rig raw-only. */
+exports.ABSENT_DEFAULT_FIX_HINT = "create ./modelrig/routes with your route files (`npx modelrig init` drafts them), or set MODELRIG_ROUTES_DIR";
+function rawOnlyRouteFailure(surface, reason = "routesDir-null") {
     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,
+        message: reason === "absent-default"
+            ? `${surface} needs routes, but there is no routes directory at ./modelrig/routes, so this rig is raw-only`
+            : `${surface} needs routes, but this rig was constructed runRaw-only (routesDir: null)`,
+        fixHint: reason === "absent-default" ? exports.ABSENT_DEFAULT_FIX_HINT : exports.RAW_ONLY_FIX_HINT,
     });
 }
 /** A `RunStreamHandle` that fails the runRaw-only way: `result` rejects and the
@@ -46,8 +50,8 @@ function rawOnlyRouteFailure(surface) {
  * 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);
+function rawOnlyStreamHandle(surface, reason) {
+    const err = rawOnlyRouteFailure(surface, reason);
     const result = Promise.reject(err);
     // Keep the rejection handled so an unconsumed handle never becomes an
     // unhandledRejection; the events iterator surfaces the same error.
@@ -71,6 +75,33 @@ function requireRoutesDir(config, surface) {
         throw rawOnlyRouteFailure(surface);
     return config.routesDir;
 }
+/** The warning createRig prints when it falls back to a raw-only rig because the
+ * DEFAULT routes directory does not exist (SURF-1, audit #1). One constant so
+ * the docs and the test quote the same words. */
+exports.ABSENT_DEFAULT_ROUTES_WARNING = "[modelrig] no routes directory at ./modelrig/routes, so this rig is raw-only: rig.runRaw, " +
+    "rig.runRawStream and rig.recordCall work, and rig.run / rig.runBundle need routes. " +
+    "Create routes with `npx modelrig init`, set MODELRIG_ROUTES_DIR, or pass `routesDir: null` " +
+    "to say raw-only on purpose and silence this line.";
+/**
+ * The routes directory createRig actually loads (SURF-1 ruling on audit #1):
+ *  - `null` stays `null` (CE-8 runRaw-only, silent);
+ *  - the UNCONFIGURED default (loadConfigFromEnv filled in `./modelrig/routes`;
+ *    no MODELRIG_ROUTES_DIR, no routesDir override, no `extraRoutesDir`) that
+ *    does not exist on disk → warn once, return `null`, so
+ *    a customer who only records calls never crashes on import;
+ *  - anything explicitly configured is returned as-is, and a missing one still
+ *    throws the teaching RouteConfigError from the loader.
+ */
+function effectiveRoutesDir(config) {
+    const dir = config.routesDir;
+    if (dir === null)
+        return null;
+    if (config.extraRoutesDir === undefined && (0, config_1.isDefaultRoutesDir)(config) && !(0, node_fs_1.existsSync)(dir)) {
+        console.warn(exports.ABSENT_DEFAULT_ROUTES_WARNING);
+        return null;
+    }
+    return dir;
+}
 /** 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
@@ -100,21 +131,25 @@ function loadRoutesOrReport(config, routesDir) {
         throw err;
     }
 }
-/** The throwing overrides for a runRaw-only rig (spec §2 R1). Each names the
+/** The throwing overrides for a runRaw-only rig (spec §2 R1).
+ * `bakeoffFromEvalCases` is deliberately NOT overridden (SURF-1, audit #12): it
+ * reads eval cases from the local store first, so with none promoted (or none
+ * rehydratable) it reports honestly without any routes dir; only a case that
+ * actually replays reaches `routes.get`, which teaches the same failure. 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() {
+function rawOnlyRouteMethods(reason = "routesDir-null") {
+    const fail = (surface) => Promise.reject(rawOnlyRouteFailure(surface, reason));
     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}")`)),
+        run: (route) => fail(`run("${route}")`),
+        runStream: (route) => rawOnlyStreamHandle(`runStream("${route}")`, reason),
+        runBundle: (bundle) => fail(`runBundle("${bundle.route}")`),
+        runBundleStream: (bundle) => rawOnlyStreamHandle(`runBundleStream("${bundle.route}")`, reason),
+        replay: (route) => fail(`replay("${route}")`),
+        bakeoff: (route) => fail(`bakeoff("${route}")`),
+        verifySwap: (route) => fail(`verifySwap("${route}")`),
     };
 }

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

@@ -0,0 +1,104 @@
+/**
+ * OBS-1 — `rig.recordCall()`: record a provider call ModelRig did NOT dispatch
+ * (acceptance ruling M12, Option A). The customer's own code made the call with
+ * its own key; it reports what the provider returned (tokens, tier, latency,
+ * failure) and ModelRig writes ONE telemetry row for it, exactly the shape the
+ * raw lane writes — same builder, same cost function, same step emission — so
+ * the call shows on /inferences, joins its run and step, and can be graded.
+ *
+ * WHAT IS DIFFERENT FROM THE RAW LANE (and nothing else is):
+ *  - `tags.lane = "external"` (SDK-owned, stamped LAST — a caller tag cannot
+ *    override it). Named `external`, not `direct`: ruling D-2 already uses
+ *    "direct" for `destination`.
+ *  - `tags.key_ownership = "byok"` (SDK-owned). Gate B-0 (usage-aggregation.ts):
+ *    a BYOK seam must stamp the tag at that seam. A recorded call is always the
+ *    customer's key — ModelRig bore no provider cost — so it can never settle as
+ *    a managed charge.
+ *  - `meta.provenance = "caller-reported"`: the numbers are the caller's, not a
+ *    measurement. Nothing was validated (`validated` is never claimed).
+ *
+ * CONTRACT: synchronous (the row is written to the local store; the exporter
+ * ships it on its normal cadence) and NEVER throws into the caller. Bad input is
+ * warned with a teaching fix (P4) and returns `{ inferenceId: null, … }` with no
+ * row written.
+ *
+ * No route/registry/capability-gate dependency beyond the raw lane's own (cost
+ * + telemetry + run context) — the raw lane's no-hard-hot-path invariant holds.
+ */
+import type { FailureClass } from "../types/failures";
+import type { ProviderId, ServiceTier } from "../types/provider";
+import type { RunTags } from "../types/route";
+import type { RawRunDeps } from "./raw";
+/** The lane tag a recorded call carries (SDK-owned) — the shared classifier's constant. */
+export { EXTERNAL_LANE } from "../telemetry/lanes";
+/** Where the warning's fix points (the "record them" section). */
+export declare const RECORD_CALL_DOCS_URL = "https://modelrig.dev/not-captured.html";
+/** Usage the caller's provider response reported. Same convention as every
+ * adapter (`AdapterUsage`): `tokensIn` is the TOTAL input and INCLUDES
+ * `tokensCached` and `tokensCacheWrite` as subsets. Token counts (and
+ * `latencyMs`/`ttfbMs`) are ROUNDED to the nearest integer and clamped
+ * (tokens ≤ Number.MAX_SAFE_INTEGER, milliseconds ≤ 2³¹−1) before recording. */
+export interface RecordCallUsage {
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly tokensCached?: number;
+    readonly tokensCacheWrite?: number;
+    readonly reasoningTokens?: number;
+}
+export interface RecordCallInput {
+    /** A ModelRig `ProviderId` is priced; any other non-empty provider id is
+     * recorded at $0 with `pricingMissing: true`. */
+    readonly provider: ProviderId | (string & {});
+    readonly model: string;
+    readonly usage: RecordCallUsage;
+    /** The tier that SERVED the call — the row is priced at it (flex is cheaper),
+     * exactly as the raw lane prices. Default `"standard"`. */
+    readonly servedTier?: ServiceTier;
+    /** The tier your code asked for. Default: `servedTier`. */
+    readonly requestedTier?: ServiceTier;
+    readonly latencyMs: number;
+    readonly ttfbMs?: number;
+    /** A failed attempt that the provider still billed is still a row. */
+    readonly failureClass?: FailureClass | null;
+    /** Native web-search tool calls billed on this call — writes the separate
+     * `rung:"search"` cost row, as the raw lane does for native grounding. */
+    readonly webSearchCalls?: number;
+    /** The ground-truth step inside an active run (same rule as `runRaw`). */
+    readonly stepKey?: string;
+    readonly tags?: RunTags;
+    readonly providerRequestId?: string;
+    /** The provider's native finish reason (`STOP`, `end_turn`, `stop`, …) or a
+     * normalized one; mapped to the envelope enum. */
+    readonly finishReason?: string;
+}
+export interface RecordCallResult {
+    /** The recorded inference id (pass it to `rig.grade`), or null when the input
+     * was rejected and nothing was recorded. */
+    readonly inferenceId: string | null;
+    readonly callId: string | null;
+    /** The token row's list-price cost (a `webSearchCalls` surcharge rides its own
+     * row, as on the raw lane). 0 when unpriced or rejected. */
+    readonly costEstimateUsd: number;
+    readonly pricingMissing: boolean;
+}
+/** Server ingest's route cap (`modelrig-server` ingest.ts `isNonEmptyString(raw.route, 200)`). */
+export declare const MAX_ROUTE_CHARS = 200;
+/** Test-only: clear the once-per-rule warning latch. */
+export declare function resetRecordCallWarningsForTest(): void;
+/** The ceiling for latency/ttfb (Postgres `integer`, 2³¹−1 ms ≈ 24.8 days). */
+export declare const MAX_MS = 2147483647;
+/**
+ * L6 MUST-3 integer hygiene. Telemetry columns are integers, but a caller's
+ * `performance.now()` delta is fractional — so ROUND to the nearest integer
+ * (friendlier than rejecting) and CLAMP: latency/ttfb to ≤ 2³¹−1 ms, token
+ * counts to ≤ Number.MAX_SAFE_INTEGER. Applied before any check that compares
+ * token counts, so validation and the recorded row see the same numbers.
+ */
+export declare function toCount(v: number, max: number): number;
+/**
+ * Record one call the caller made itself. See the module header for the
+ * contract. `deps` is the rig's raw-lane deps (telemetry + unpriced rate +
+ * manifest) — the same object `runRaw` receives.
+ */
+export declare function recordCall(deps: RawRunDeps, input: RecordCallInput): RecordCallResult;
+//# sourceMappingURL=record-call.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record-call.d.ts","sourceRoot":"","sources":["../../src/run/record-call.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAYH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAgB,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAExC,2FAA2F;AAC3F,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,kEAAkE;AAClE,eAAO,MAAM,oBAAoB,2CAA2C,CAAC;AAE7E;;;;gFAIgF;AAChF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B;qDACiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC;+DAC2D;IAC3D,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,CAAC,EAAE,WAAW,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5C;8EAC0E;IAC1E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;sDACkD;IAClD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B;gDAC4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;gEAC4D;IAC5D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AAQD,kGAAkG;AAClG,eAAO,MAAM,eAAe,MAAM,CAAC;AAcnC,wDAAwD;AACxD,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAMD,+EAA+E;AAC/E,eAAO,MAAM,MAAM,aAAgB,CAAC;AAEpC;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AA6GD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAarF"}