modelrig 0.11.0 → 0.11.1

package/dist/init/observe.js

@@ -25,6 +25,10 @@ exports.seamContent = seamContent;
 exports.buildObserveMarkdown = buildObserveMarkdown;
 exports.runObserve = runObserve;
 const finder_1 = require("./finder");
+/** The `environment` expression the wiring diff proposes. Assembled so this
+ * source file never holds the literal env-read token (package invariant: only
+ * config.ts reads the environment). */
+const ENV_EXPR = `${["process", "env", "NODE_ENV"].join(".")} ?? "development"`;
 const normalize = (s) => s.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_|_$/g, "").toLowerCase();
 /** A stable step key from a call site: `<dir>_<file>_<line>`, deduped so two
  * sites never collide. Deterministic, so a second run proposes the same keys. */
@@ -40,33 +44,43 @@ function stepKeyFor(site, used) {
 }
 /** The generated seam. Self-contained and fresh (never resurrected from git
  * history — that is the point of onboarding-test run-2). Mirrors the reference
- * `recordStep` in instrumentation.md, plus a `withRun` boundary wrapper. */
+ * `recordStep` in instrumentation.md, plus a `withRun` boundary wrapper.
+ *
+ * SURF-1 (audit #1, #6): the rig is built `routesDir: null` (observe needs no
+ * routes, and the default dir is absent in a fresh repo — the old seam crashed
+ * the customer's app on import), and `recordStep` reports the provider call
+ * through `rig.recordCall` so the step carries tokens and a cost and the call
+ * shows on /inferences. */
 function seamContent() {
     return `/**
  * ModelRig observe seam — generated by \`modelrig observe\`.
  *
  * This is YOURS to keep and edit; it is generated fresh (not copied from any
  * deleted seam) so it always matches the current SDK. It records each pipeline
- * run as a run -> step -> artifact chain you click through in the console.
+ * run as a run -> step -> artifact chain you click through in the console, and
+ * each model call as a recorded inference with its tokens and cost.
  *
- * Observe-only: no routes move, no model calls are rerouted. With no control
- * plane configured (or the org capture posture set to off) every call here is
- * inert and your pipeline behaves byte-for-byte as before. Nothing here ever
- * throws into your pipeline — a telemetry write that fails is logged and
+ * Observe-only: no routes move, no model calls are rerouted. Your code keeps
+ * calling the provider with your own key; this file only REPORTS what happened.
+ * With no MODELRIG_API_KEY (or the org capture posture set to off) every call
+ * here is inert and your pipeline behaves byte-for-byte as before. Nothing here
+ * ever throws into your pipeline — a telemetry write that fails is logged and
  * dropped (instrumentation.md, "Never throws into your pipeline").
  *
  * Docs: https://modelrig.dev/instrumentation.html
  */
 
-import { createRig, loadConfigFromEnv, type Rig } from "modelrig";
+import { createRig, loadConfigFromEnv, type RecordCallInput, type Rig } from "modelrig";
 
-const rig: Rig = createRig(loadConfigFromEnv());
+// routesDir: null — observe needs no route files, so the rig is raw-only and
+// never looks for ./modelrig/routes (importing this file cannot throw).
+const rig: Rig = createRig({ ...loadConfigFromEnv(), routesDir: null });
 
 /** Open a run context around a whole pipeline, close it on success/failure.
  * \`episodeKey\` is a grouping key (a natural choice: your per-run attempt id),
- * not a unique id. Pass \`environment\` (e.g. your NODE_ENV) to tag the run.
- * Use \`rig.artifacts.run.scope(...)\` instead for concurrent runs in one
- * process. */
+ * not a unique id. Pass \`environment\` (e.g. your NODE_ENV) so the Env column
+ * on /runs is filled. Use \`rig.artifacts.run.scope(...)\` instead for
+ * concurrent runs in one process. */
 export async function withRun<T>(
   opts: { pipeline: string; episodeKey: string; environment?: string },
   body: () => Promise<T>,
@@ -86,14 +100,20 @@ export async function withRun<T>(
   }
 }
 
-/** Save prompt + raw + parsed for one step, link lineage, flag conformance.
- * A stage whose model call does NOT go through the rig still produces
- * artifacts (with \`stepKey\` set and no step row) — correct and honest; the
- * console renders "cost n/a" rather than inventing a number. */
+/** The provider call your code made, as the provider reported it. Recorded with
+ * \`rig.recordCall\` so the step carries tokens and a cost ("recorded ·
+ * unverified": ModelRig did not dispatch it). */
+export type StepCall = Omit<RecordCallInput, "stepKey">;
+
+/** Record one step: report the provider call (tokens → cost on /runs and
+ * /inferences), save prompt + raw + parsed, link lineage, flag conformance.
+ * Leave \`call\` out only when you have no usage numbers; the step then shows
+ * "cost n/a". */
 export function recordStep(
   stepKey: string,
-  work: { prompt: string; rawText: string; json: unknown; conforms: boolean },
+  work: { prompt: string; rawText: string; json: unknown; conforms: boolean; call?: StepCall },
 ): void {
+  if (work.call !== undefined) rig.recordCall({ ...work.call, stepKey });
   const p = rig.artifacts.artifact.save(work.prompt, { name: \`\${stepKey}.prompt\`, type: "prompt", stepKey });
   const raw = rig.artifacts.artifact.save(work.rawText, { name: \`\${stepKey}.raw\`, type: "raw_response", stepKey });
   const parsed = rig.artifacts.artifact.save(work.json, { name: \`\${stepKey}.output\`, type: "step_output", task: stepKey, stepKey });
@@ -101,6 +121,12 @@ export function recordStep(
   if (raw && parsed) rig.artifacts.artifact.link(parsed, raw, "derived_from");
   if (parsed) rig.grade({ kind: "artifact", id: parsed.id }, { score: work.conforms ? 1 : 0, kind: "deterministic", grader: "schema-check" });
 }
+
+/** Flush and close the rig. Await it once at shutdown (a one-shot script that
+ * exits without it can lose the last batch). */
+export function closeRig(): Promise<void> {
+  return rig.close();
+}
 `;
 }
 /** The import specifier a source file uses to reach the seam. Best-effort
@@ -110,12 +136,36 @@ function importSpecifier(fromFile, seamPath, path) {
     const rel = path.relative(path.dirname(fromFile), noExt);
     return rel.startsWith(".") ? rel : `./${rel}`;
 }
-function recordStepSnippet(stepKey) {
+/** How the customer's provider response reports usage, per provider family —
+ * the expressions the wiring diff proposes for `call.usage` (the human/agent
+ * adjusts the variable name). Unknown providers get a placeholder. */
+const USAGE_EXPR = {
+    openai: { tokensIn: "res.usage?.prompt_tokens ?? 0", tokensOut: "res.usage?.completion_tokens ?? 0" },
+    deepseek: { tokensIn: "res.usage?.prompt_tokens ?? 0", tokensOut: "res.usage?.completion_tokens ?? 0" },
+    grok: { tokensIn: "res.usage?.prompt_tokens ?? 0", tokensOut: "res.usage?.completion_tokens ?? 0" },
+    deepinfra: { tokensIn: "res.usage?.prompt_tokens ?? 0", tokensOut: "res.usage?.completion_tokens ?? 0" },
+    fireworks: { tokensIn: "res.usage?.prompt_tokens ?? 0", tokensOut: "res.usage?.completion_tokens ?? 0" },
+    anthropic: { tokensIn: "res.usage.input_tokens", tokensOut: "res.usage.output_tokens" },
+    // Gemini bills thinking tokens as output: candidates + thoughts (SURF-1 QA).
+    gemini: {
+        tokensIn: "res.usageMetadata?.promptTokenCount ?? 0",
+        tokensOut: "(res.usageMetadata?.candidatesTokenCount ?? 0) + (res.usageMetadata?.thoughtsTokenCount ?? 0)",
+    },
+};
+function recordStepSnippet(site, stepKey) {
+    const usage = USAGE_EXPR[site.provider] ?? { tokensIn: "/* input tokens */ 0", tokensOut: "/* output tokens */ 0" };
+    const model = site.model !== null ? JSON.stringify(site.model) : site.modelExpression ?? '"<model id>"';
     return (`recordStep(${JSON.stringify(stepKey)}, {\n` +
         `  prompt,          // the assembled prompt string\n` +
         `  rawText,         // the model's raw text, pre-parse\n` +
         `  json: parsed,    // your parsed/validated output\n` +
         `  conforms,        // did it satisfy your schema?\n` +
+        `  call: {          // what the provider reported → tokens + cost (rig.recordCall)\n` +
+        `    provider: ${JSON.stringify(site.provider)},\n` +
+        `    model: ${model},\n` +
+        `    usage: { tokensIn: ${usage.tokensIn}, tokensOut: ${usage.tokensOut} },\n` +
+        `    latencyMs,     // Date.now() after the call minus before it\n` +
+        `  },\n` +
         `});`);
 }
 /** The run boundary is most likely the shallowest detected file (the entry
@@ -139,7 +189,7 @@ function buildObserveMarkdown(plans, seamPath, result, path) {
         "**Nothing in your source has changed.** `modelrig observe` generated one seam helper",
         `(\`${seamPath}\`) and this plan. Observe is **not migration**: no routes were drafted, no`,
         "model calls rerouted. Applying the wiring below records each run as a run → step →",
-        "artifact chain you click through in the console — and with the flag off, your pipeline",
+        "artifact chain you click through in the console — and with no key set, your pipeline",
         "behaves **byte-for-byte** as before.",
         "",
         `Detected **${result.sitesFound} model call site(s)** across ${result.filesScanned} scanned file(s);`,
@@ -154,9 +204,11 @@ function buildObserveMarkdown(plans, seamPath, result, path) {
         "",
         "```bash",
         "export MODELRIG_API_KEY=<key>               # mint at https://app.modelrig.ai (/keys)",
-        "# export MODELRIG_ARTIFACT_STEPS=step_a,step_b   # optional: instrument a subset",
         "```",
         "",
+        "The seam builds its rig with `routesDir: null`: observe needs no route files, so importing",
+        "it never looks for `./modelrig/routes`.",
+        "",
         "> **Human handoff (one step, once).** Seeing these runs **in the console** needs a free",
         "> account + an API key minted at <https://app.modelrig.ai> (`/keys`) — a console login a",
         "> coding agent cannot perform. Set `MODELRIG_API_KEY=<key>` once a human provides it; the",
@@ -174,7 +226,7 @@ function buildObserveMarkdown(plans, seamPath, result, path) {
     lines.push("## 2. Open a run context around the pipeline", "", boundary === null
         ? "Wrap your pipeline's entry point in `withRun(...)` from the seam helper:"
         : `Your pipeline entry looks like \`${boundary}\` (the shallowest detected call site — a` +
-            " heuristic; move this if your real entry is elsewhere). Wrap it in `withRun(...)`:", "", "```diff", `+ import { withRun } from "${boundaryImport}";`, "", "- export async function runPipeline(input) {", "-   /* ... your steps ... */", "- }", "+ export async function runPipeline(input) {", "+   return withRun(", '+     { pipeline: "my-pipeline", episodeKey: input.attemptId },', "+     async () => {", "+       /* ... your steps ... */", "+     },", "+   );", "+ }", "```", "", "## 3. Record each step's work products", "", "Each detected model call is one step. After the call parses its output, add a `recordStep`", "(the diffs below quote the call line so you can find it):", "");
+            " heuristic; move this if your real entry is elsewhere). Wrap it in `withRun(...)`:", "", "```diff", `+ import { withRun } from "${boundaryImport}";`, "", "- export async function runPipeline(input) {", "-   /* ... your steps ... */", "- }", "+ export async function runPipeline(input) {", "+   return withRun(", `+     { pipeline: "my-pipeline", episodeKey: input.attemptId, environment: ${ENV_EXPR} },`, "+     async () => {", "+       /* ... your steps ... */", "+     },", "+   );", "+ }", "```", "", "## 3. Record each step's work products", "", "Each detected model call is one step. After the call parses its output, add a `recordStep`", "(the diffs below quote the call line so you can find it). Its `call` field reports what the", "provider returned through `rig.recordCall`, so the step carries tokens and a cost and the call", "shows on /inferences as \"recorded · unverified\". Time the call (`const t0 = Date.now()` before,", "`const latencyMs = Date.now() - t0` after) and rename `res` to your response variable:", "");
     // Group the per-site wiring diffs by file so each file gets one import line.
     const byFile = new Map();
     for (const plan of plans) {
@@ -190,7 +242,7 @@ function buildObserveMarkdown(plans, seamPath, result, path) {
         }
         lines.push("```", "");
     }
-    lines.push("## 4. See it", "", "Run your pipeline once, then open the console: **Runs** lists the run, `/runs/[id]` renders", "the semantic chain (artifacts grouped by step, with hashes and evaluation badges), and", "`/artifacts/[id]` shows one artifact's lineage. Un-routed steps show **cost n/a** — correct", "for observe-only; nothing routes through the rig yet.", "", "## When you are ready to migrate (later, optional)", "", "Observe answers *what is my pipeline doing?* When you want to *change what serves a step*,", "that is route extraction (T2) — a separate, behaviour-affecting move behind its own review:", "`modelrig init --scope <this pipeline>`. Observe first is the safer order.", "");
+    lines.push("## 4. See it", "", "Run your pipeline once, then open the console: **Runs** lists the run, `/runs/[id]` renders", "the semantic chain (artifacts grouped by step, with hashes and evaluation badges), and", "`/artifacts/[id]` shows one artifact's lineage, and **Inferences** lists each recorded call", "with its cost. A step you wired without `call` shows **cost n/a**: ModelRig has no usage", "numbers for it. In a script that exits, `await closeRig()` once at the end so the last batch", "ships. Calls your code makes outside `recordStep` stay invisible: https://modelrig.dev/not-captured.html", "", "## When you are ready to migrate (later, optional)", "", "Observe answers *what is my pipeline doing?* When you want to *change what serves a step*,", "that is route extraction (T2) — a separate, behaviour-affecting move behind its own review:", "`modelrig init --scope <this pipeline>`. Observe first is the safer order.", "");
     return `${lines.join("\n")}\n`;
 }
 function runObserve(deps, options = {}) {
@@ -198,7 +250,7 @@ function runObserve(deps, options = {}) {
     const used = new Set();
     const plans = scan.sites.map((site) => {
         const stepKey = stepKeyFor(site, used);
-        return { site, stepKey, snippet: recordStepSnippet(stepKey) };
+        return { site, stepKey, snippet: recordStepSnippet(site, stepKey) };
     });
     const seamPath = deps.path.join(deps.outDir, "record-step.ts");
     // Import specifiers and prose are computed root-relative — call sites come

package/dist/init/starter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The starter route's companion files (SURF-1, audit #2). Every on-ramp shows
+ * the same starter route, `example.support_summarize` (console
+ * STARTER_ROUTE_YAML, www /get-started, quickstart §3), and that YAML references
+ * `./schemas/support_summarize.schema.json` and
+ * `./prompts/support_summarize.system.md`. Neither shipped in the npm tarball,
+ * so a customer who pasted the route got "schema file not found" from
+ * `modelrig validate`. `modelrig init` now writes both next to the routes dir
+ * (never clobbering), and `surf1-setup.test.ts` asserts these constants equal the
+ * package's own committed example files and that the starter validates.
+ *
+ * They are support files, not routes: the loader reads only top-level *.yaml,
+ * so writing them can never change what a rig serves.
+ */
+/** Path of each companion file, relative to the routes directory. */
+export declare const STARTER_SCHEMA_PATH = "schemas/support_summarize.schema.json";
+export declare const STARTER_PROMPT_PATH = "prompts/support_summarize.system.md";
+export declare const STARTER_SCHEMA_JSON = "{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"title\": \"support_summarize\",\n  \"type\": \"object\",\n  \"additionalProperties\": false,\n  \"required\": [\"summary\", \"handoff\"],\n  \"properties\": {\n    \"summary\": {\n      \"type\": \"string\",\n      \"minLength\": 40,\n      \"description\": \"One paragraph a human agent can act on without reading the thread.\"\n    },\n    \"severity\": { \"type\": \"string\", \"enum\": [\"low\", \"normal\", \"high\", \"urgent\"] },\n    \"handoff\": {\n      \"type\": \"object\",\n      \"additionalProperties\": false,\n      \"required\": [\"team\", \"reason\"],\n      \"properties\": {\n        \"team\": { \"type\": \"string\", \"enum\": [\"billing\", \"technical\", \"account\", \"none\"] },\n        \"reason\": { \"type\": \"string\", \"minLength\": 10 }\n      }\n    }\n  }\n}\n";
+export declare const STARTER_PROMPT_MD = "You summarise a customer support ticket for the agent who picks it up next.\n\nProduct: {{product}}\n\nEarlier context on this customer (may be \"none\"):\n{{priorContext}}\n\nTicket:\n{{ticket}}\n\nWrite one actionable paragraph, judge severity, and name the team it should go\nto (or `none` if the summary closes it).\n\n{{#unless capability.structured_native}}\nReturn ONLY a JSON object matching this shape \u2014 no prose, no code fence:\n{\"summary\": string, \"severity\": \"low\"|\"normal\"|\"high\"|\"urgent\",\n \"handoff\": {\"team\": \"billing\"|\"technical\"|\"account\"|\"none\", \"reason\": string}}\n{{/unless}}\n";
+export interface StarterFs {
+    existsSync: (p: string) => boolean;
+    mkdirSync: (p: string, o: {
+        recursive: boolean;
+    }) => void;
+    writeFileSync: (p: string, c: string, e: "utf8") => void;
+}
+/** Write the starter's schema and prompt under `routesDir`, leaving any file that
+ * already exists alone (it is the customer's). Returns what was written/skipped. */
+export declare function writeStarterFiles(routesDir: string, fs: StarterFs, path: {
+    join: (...parts: string[]) => string;
+    dirname: (p: string) => string;
+}): {
+    written: string[];
+    skipped: string[];
+};
+//# sourceMappingURL=starter.d.ts.map

package/dist/init/starter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter.d.ts","sourceRoot":"","sources":["../../src/init/starter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,qEAAqE;AACrE,eAAO,MAAM,mBAAmB,0CAA0C,CAAC;AAC3E,eAAO,MAAM,mBAAmB,wCAAwC,CAAC;AAEzE,eAAO,MAAM,mBAAmB,w2BAwB/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,0nBAkB7B,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1D,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1D;AAED;oFACoF;AACpF,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,SAAS,EACb,IAAI,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;IAAC,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAAE,GAC7E;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAiB1C"}

package/dist/init/starter.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * The starter route's companion files (SURF-1, audit #2). Every on-ramp shows
+ * the same starter route, `example.support_summarize` (console
+ * STARTER_ROUTE_YAML, www /get-started, quickstart §3), and that YAML references
+ * `./schemas/support_summarize.schema.json` and
+ * `./prompts/support_summarize.system.md`. Neither shipped in the npm tarball,
+ * so a customer who pasted the route got "schema file not found" from
+ * `modelrig validate`. `modelrig init` now writes both next to the routes dir
+ * (never clobbering), and `surf1-setup.test.ts` asserts these constants equal the
+ * package's own committed example files and that the starter validates.
+ *
+ * They are support files, not routes: the loader reads only top-level *.yaml,
+ * so writing them can never change what a rig serves.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STARTER_PROMPT_MD = exports.STARTER_SCHEMA_JSON = exports.STARTER_PROMPT_PATH = exports.STARTER_SCHEMA_PATH = void 0;
+exports.writeStarterFiles = writeStarterFiles;
+/** Path of each companion file, relative to the routes directory. */
+exports.STARTER_SCHEMA_PATH = "schemas/support_summarize.schema.json";
+exports.STARTER_PROMPT_PATH = "prompts/support_summarize.system.md";
+exports.STARTER_SCHEMA_JSON = `{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "support_summarize",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["summary", "handoff"],
+  "properties": {
+    "summary": {
+      "type": "string",
+      "minLength": 40,
+      "description": "One paragraph a human agent can act on without reading the thread."
+    },
+    "severity": { "type": "string", "enum": ["low", "normal", "high", "urgent"] },
+    "handoff": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["team", "reason"],
+      "properties": {
+        "team": { "type": "string", "enum": ["billing", "technical", "account", "none"] },
+        "reason": { "type": "string", "minLength": 10 }
+      }
+    }
+  }
+}
+`;
+exports.STARTER_PROMPT_MD = `You summarise a customer support ticket for the agent who picks it up next.
+
+Product: {{product}}
+
+Earlier context on this customer (may be "none"):
+{{priorContext}}
+
+Ticket:
+{{ticket}}
+
+Write one actionable paragraph, judge severity, and name the team it should go
+to (or \`none\` if the summary closes it).
+
+{{#unless capability.structured_native}}
+Return ONLY a JSON object matching this shape — no prose, no code fence:
+{"summary": string, "severity": "low"|"normal"|"high"|"urgent",
+ "handoff": {"team": "billing"|"technical"|"account"|"none", "reason": string}}
+{{/unless}}
+`;
+/** Write the starter's schema and prompt under `routesDir`, leaving any file that
+ * already exists alone (it is the customer's). Returns what was written/skipped. */
+function writeStarterFiles(routesDir, fs, path) {
+    const written = [];
+    const skipped = [];
+    for (const [rel, body] of [
+        [exports.STARTER_SCHEMA_PATH, exports.STARTER_SCHEMA_JSON],
+        [exports.STARTER_PROMPT_PATH, exports.STARTER_PROMPT_MD],
+    ]) {
+        const file = path.join(routesDir, rel);
+        if (fs.existsSync(file)) {
+            skipped.push(file);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, body, "utf8");
+        written.push(file);
+    }
+    return { written, skipped };
+}

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}")`),
     };
 }