modelrig 0.10.0 → 0.11.1

package/dist/index.js

@@ -25,11 +25,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.redactApiKey = exports.looksLikeApiKey = exports.hashApiKeySecret = exports.API_KEY_SECRET_BYTES = exports.API_KEY_SCOPES = exports.API_KEY_PREFIX = exports.resolveArtifactsConfig = exports.createToolRegistry = exports.SlotResolutionError = exports.assemblePrompt = exports.createEmbeddedPrompts = exports.createPromptResolver = exports.parseServedPrompt = exports.createPromptCache = exports.createApiPromptFetcher = exports.promptTemplateSha = exports.normalizeManifest = exports.parseAuthoringDoc = exports.assertValidManifest = exports.validateManifest = exports.resolveOtlpConfig = exports.parseOtlpHeaders = exports.decodeOtlpProtobufTraces = exports.looksLikeLogsPayload = exports.normalizeOtlpTraces = exports.startOtlpEmitterIfConfigured = exports.createOtlpEmitter = exports.TRACEPARENT_TAG = exports.parseTraceparent = exports.buildExportTraceRequest = exports.inferenceToSpan = exports.SEMCONV_VERSION = exports.SinkSendError = exports.createDirectSink = exports.createApiSink = exports.createTelemetryExporter = exports.RESERVED_TAG_KEYS = exports.resolvePipelineSha = exports.reservedTagNearMisses = exports.renderRequestForHash = exports.sanitizeMetaForWire = exports.isMetaSafeString = exports.summarizeAttemptMeta = exports.DEFAULT_INGEST_URL = exports.INGEST_PROTOCOL_VERSION_V1 = exports.INGEST_PROTOCOL_VERSION = exports.INGEST_PATH = exports.foreignOrgGrades = exports.stampBatch = exports.loadConfigFromEnv = void 0;
-exports.computeProposal = exports.mirrorBakeoff = exports.runBakeoff = exports.replayVariant = exports.openTelemetryStore = exports.openCaptureStore = exports.SSE_DONE = exports.MODELRIG_REQUEST_HEADERS = exports.MODELRIG_HEADERS = exports.GATEWAY_PROTOCOL_VERSION = exports.MODELS_PATH = exports.CHAT_COMPLETIONS_PATH = exports.classifyLane = exports.ALL_CAPABILITY_FLAGS = exports.PROVIDER_IDS = exports.RAW_ONLY_FIX_HINT = exports.rawOnlyRouteFailure = exports.requireRoutesDir = exports.runRawStream = exports.runRaw = exports.resolveCallConfigForRun = exports.hashUnitKey = exports.armName = exports.drawArm = exports.narrowExperiment = exports.pinFromResolved = exports.parseCallConfig = exports.narrowCallConfigPin = exports.getCallConfig = exports.createCallConfigResolver = exports.createApiCallConfigFetcher = exports.applyCallConfig = exports.assertMirrorSafe = exports.hashResolvedBundle = exports.resolveRouteBundle = exports.bundleFromResolved = exports.runStream = exports.evalCaseCaptureStore = exports.selectEvalCaseCaptures = exports.runBakeoffFromEvalCases = exports.extractEvidenceQuotes = exports.groundednessScore = exports.resolveDeterministicQuality = exports.fieldAccuracy = exports.exactMatch = exports.KEY_SHAPED_PREFIXES = exports.containsKeyShapedString = exports.scrubSecrets = exports.hasScope = exports.parseScopes = void 0;
-exports.servedDestinations = exports.DEFAULT_DESTINATION = exports.DESTINATIONS = exports.GEMINI_THINKING_CAPABLE_MODELS = exports.createGeminiAdapter = exports.PROVIDER_KEY_ENV = exports.serveabilityWarnings = exports.checkServeability = exports.writeRouteDraft = exports.buildRouteDraft = exports.splitModelKey = exports.seedCandidates = exports.loadRegistryRows = exports.signatureFor = exports.PROVIDER_SIGNATURES = exports.readObjectLiteral = exports.findCallSitesInText = exports.scanRepoForCallSites = exports.capabilitiesFor = exports.routeNameFor = exports.buildMigrationMarkdown = exports.runInit = exports.renderConfigErrorForTerminal = exports.describeConfigFailure = exports.teachConfigError = exports.classifyConfigProblem = exports.CONFIG_TEACHING = exports.mergeLoadedRoutes = exports.loadRoutesWithExtra = exports.loadRoutes = exports.RouteConfigError = exports.renderFailureForTerminal = exports.teach = exports.FAILURE_TEACHING = exports.isRigFailure = exports.RigFailureError = exports.extractCitations = exports.createTavilySearchProvider = exports.sampleQuality = exports.pairedRegret = exports.wilson95 = exports.aggregateVariantMetrics = exports.OUTPUT_MAX_BYTES = exports.retentionExpiry = exports.truncateOutput = exports.selectArmsToKeep = exports.buildBakeoffSamples = exports.createBakeoffSamplesClient = exports.deriveSwapDirection = exports.bakeoffEvidence = void 0;
-exports.PROPOSAL_TTL_DAYS = exports.regretBreachTriggerHash = exports.upgradeTriggerHash = exports.manualChallengerTriggerHash = exports.triggerHash = exports.evaluateEvents = exports.RUNG1_MIN_GRADES = exports.computeCoverage = exports.computeParity = exports.factsUnderCredential = exports.factsFor = exports.PROBE_FRESHNESS_SLO_DAYS = exports.stalenessSentence = exports.probeFreshness = exports.callNotesFor = exports.evaluateChallengerEligibility = exports.requirementPredicates = exports.PREDICATE_GLOSS = exports.ALL_CAPABILITY_PREDICATES = exports.explainEmptySelection = exports.hasCapability = exports.selectModels = exports.parseCapabilityQuery = exports.capabilityFactsFromEntry = exports.loadRegistryFacts = exports.fingerprintSchema = exports.loadManifest = exports.SNAPSHOT_BASIS = exports.describePricingV2 = exports.tierRates = exports.synthesizeFromFlat = exports.seededCachePolicyProviders = exports.getCachePolicy = exports.DEFAULT_CACHE_HYSTERESIS = exports.classifyCacheVerdict = exports.effectiveInputRate = exports.estimateCostUsd = exports.getPricingV2 = exports.getPricing = exports.resolveCandidates = exports.OPENAI_COMPAT_HOSTS = exports.shapeFireworksModelId = exports.classifyCompatFailure = exports.buildOpenAICompatParams = exports.createOpenAICompatAdapter = exports.createGrokAdapter = exports.createAnthropicAdapter = exports.createDeepSeekAdapter = exports.createOpenAIAdapter = exports.destinationSupported = void 0;
-exports.RESERVED_DIMENSION_NAMES = exports.METRIC_COLUMNS = exports.DIMENSION_COLUMNS = exports.sinceIsoFor = exports.savedQueryById = exports.SAVED_QUERIES = exports.ANALYTICS_SCAN_CAP = exports.selectableColumnsAreMetaSafe = exports.planAnalyticsRead = exports.evaluateAnalyticsQuery = exports.describeAnalyticsSchema = exports.parseQuery = exports.QueryGrammarError = exports.compileQuery = exports.writePriorsCells = exports.aggregatePairwiseFromTelemetry = exports.aggregatePriors = exports.DEFAULT_WATCH_MONTHLY_USD = exports.watchEnvelopeKey = exports.reserveWatchBudget = exports.WATCH_STATE_KEY = exports.createFileWatchStateStore = exports.createControlPlaneWatchStateStore = exports.createWatchStateStore = exports.saveWatchState = exports.loadWatchState = exports.computeWatchEvents = exports.buildPriceUniverse = exports.runWatchCycle = exports.DEFAULT_MONITOR_CONFIG = exports.createMonitorReads = exports.rollupConformRate = exports.evaluateConformDegradation = exports.runMonitorCycle = exports.assertTransition = exports.createProposalsClient = exports.MONITOR_SOURCE_PREFIX = exports.MONITOR_CYCLE_MARKER = exports.REGRET_MONITOR_MARGIN = exports.REGRET_MONITOR_MIN_N = exports.REGRET_MONITOR_BASELINE_DAYS = exports.REGRET_MONITOR_WINDOW_DAYS = exports.createRegretMonitorReads = exports.regretMonitorConfig = exports.cyclePointFromArtifact = exports.aggregateRegretBand = exports.evaluateRegretDrift = exports.runRegretMonitorCycle = exports.evaluateUpgradeOpportunities = exports.explainCacheContext = void 0;
-exports.computeOdometer = exports.createSwapsClient = exports.executeSwap = exports.trialVariantName = exports.buildDeclareTrialChange = exports.buildRestoreYaml = exports.buildSwapChange = exports.runTelemetryQuery = void 0;
+exports.SSE_DONE = exports.MODELRIG_REQUEST_HEADERS = exports.MODELRIG_HEADERS = exports.GATEWAY_PROTOCOL_VERSION = exports.MODELS_PATH = exports.CHAT_COMPLETIONS_PATH = exports.classifyLane = exports.ALL_CAPABILITY_FLAGS = exports.PROVIDER_IDS = exports.RAW_ONLY_FIX_HINT = exports.rawOnlyRouteFailure = exports.requireRoutesDir = exports.RECORDED_TOOLTIP = exports.RECORDED_BADGE = exports.EXTERNAL_LANE = exports.RAW_LANE = exports.callLaneOf = exports.isRoutedLane = exports.runRawStream = exports.runRaw = exports.resolveCallConfigForRun = exports.hashUnitKey = exports.armName = exports.drawArm = exports.narrowExperiment = exports.pinFromResolved = exports.parseCallConfig = exports.narrowCallConfigPin = exports.getCallConfig = exports.createCallConfigResolver = exports.createApiCallConfigFetcher = exports.applyCallConfig = exports.assertMirrorSafe = exports.hashResolvedBundle = exports.resolveRouteBundle = exports.bundleFromResolved = exports.runStream = exports.evalCaseCaptureStore = exports.selectEvalCaseCaptures = exports.runBakeoffFromEvalCases = exports.extractEvidenceQuotes = exports.groundednessScore = exports.resolveDeterministicQuality = exports.fieldAccuracy = exports.exactMatch = exports.KEY_SHAPED_PREFIXES = exports.containsKeyShapedString = exports.scrubSecrets = exports.hasScope = exports.parseScopes = void 0;
+exports.serveabilityWarnings = exports.checkServeability = exports.writeRouteDraft = exports.buildRouteDraft = exports.splitModelKey = exports.seedCandidates = exports.loadRegistryRows = exports.signatureFor = exports.PROVIDER_SIGNATURES = exports.readObjectLiteral = exports.findCallSitesInText = exports.scanRepoForCallSites = exports.capabilitiesFor = exports.routeNameFor = exports.buildMigrationMarkdown = exports.runInit = exports.renderConfigErrorForTerminal = exports.describeConfigFailure = exports.teachConfigError = exports.classifyConfigProblem = exports.CONFIG_TEACHING = exports.mergeLoadedRoutes = exports.loadRoutesWithExtra = exports.loadRoutes = exports.RouteConfigError = exports.renderFailureForTerminal = exports.teach = exports.FAILURE_TEACHING = exports.isRigFailure = exports.RigFailureError = exports.extractCitations = exports.createTavilySearchProvider = exports.sampleQuality = exports.pairedRegret = exports.wilson95 = exports.aggregateVariantMetrics = exports.OUTPUT_MAX_BYTES = exports.retentionExpiry = exports.truncateOutput = exports.selectArmsToKeep = exports.buildBakeoffSamples = exports.createBakeoffSamplesClient = exports.deriveSwapDirection = exports.bakeoffEvidence = exports.computeProposal = exports.mirrorBakeoff = exports.runBakeoff = exports.replayVariant = exports.openTelemetryStore = exports.openCaptureStore = void 0;
+exports.RUNG1_MIN_GRADES = exports.computeCoverage = exports.computeParity = exports.factsUnderCredential = exports.factsFor = exports.PROBE_FRESHNESS_SLO_DAYS = exports.stalenessSentence = exports.probeFreshness = exports.callNotesFor = exports.evaluateChallengerEligibility = exports.requirementPredicates = exports.PREDICATE_GLOSS = exports.ALL_CAPABILITY_PREDICATES = exports.explainEmptySelection = exports.hasCapability = exports.selectModels = exports.parseCapabilityQuery = exports.capabilityFactsFromEntry = exports.loadRegistryFacts = exports.fingerprintSchema = exports.loadManifest = exports.SNAPSHOT_BASIS = exports.describePricingV2 = exports.tierRates = exports.synthesizeFromFlat = exports.seededCachePolicyProviders = exports.getCachePolicy = exports.DEFAULT_CACHE_HYSTERESIS = exports.classifyCacheVerdict = exports.effectiveInputRate = exports.estimateCostUsd = exports.getPricingV2 = exports.getPricing = exports.resolveCandidates = exports.OPENAI_COMPAT_HOSTS = exports.shapeFireworksModelId = exports.classifyCompatFailure = exports.buildOpenAICompatParams = exports.createOpenAICompatAdapter = exports.createGrokAdapter = exports.createAnthropicAdapter = exports.createDeepSeekAdapter = exports.createOpenAIAdapter = exports.destinationSupported = exports.servedDestinations = exports.DEFAULT_DESTINATION = exports.DESTINATIONS = exports.GEMINI_THINKING_CAPABLE_MODELS = exports.createGeminiAdapter = exports.PROVIDER_KEY_ENV = void 0;
+exports.ANALYTICS_SCAN_CAP = exports.selectableColumnsAreMetaSafe = exports.planAnalyticsRead = exports.evaluateAnalyticsQuery = exports.describeAnalyticsSchema = exports.parseQuery = exports.QueryGrammarError = exports.compileQuery = exports.writePriorsCells = exports.aggregatePairwiseFromTelemetry = exports.aggregatePriors = exports.DEFAULT_WATCH_MONTHLY_USD = exports.watchEnvelopeKey = exports.reserveWatchBudget = exports.WATCH_STATE_KEY = exports.createFileWatchStateStore = exports.createControlPlaneWatchStateStore = exports.createWatchStateStore = exports.saveWatchState = exports.loadWatchState = exports.computeWatchEvents = exports.buildPriceUniverse = exports.runWatchCycle = exports.DEFAULT_MONITOR_CONFIG = exports.createMonitorReads = exports.rollupConformRate = exports.evaluateConformDegradation = exports.runMonitorCycle = exports.assertTransition = exports.createProposalsClient = exports.MONITOR_SOURCE_PREFIX = exports.MONITOR_CYCLE_MARKER = exports.REGRET_MONITOR_MARGIN = exports.REGRET_MONITOR_MIN_N = exports.REGRET_MONITOR_BASELINE_DAYS = exports.REGRET_MONITOR_WINDOW_DAYS = exports.createRegretMonitorReads = exports.regretMonitorConfig = exports.cyclePointFromArtifact = exports.aggregateRegretBand = exports.evaluateRegretDrift = exports.runRegretMonitorCycle = exports.evaluateUpgradeOpportunities = exports.explainCacheContext = exports.PROPOSAL_TTL_DAYS = exports.regretBreachTriggerHash = exports.upgradeTriggerHash = exports.manualChallengerTriggerHash = exports.triggerHash = exports.evaluateEvents = void 0;
+exports.computeOdometer = exports.createSwapsClient = exports.executeSwap = exports.trialVariantName = exports.buildDeclareTrialChange = exports.buildRestoreYaml = exports.buildSwapChange = exports.runTelemetryQuery = exports.RESERVED_DIMENSION_NAMES = exports.METRIC_COLUMNS = exports.DIMENSION_COLUMNS = exports.sinceIsoFor = exports.savedQueryById = exports.SAVED_QUERIES = void 0;
 exports.createRig = createRig;
 const build_adapters_1 = require("./adapters/build-adapters");
 const config_1 = require("./config");
@@ -41,6 +41,7 @@ const tools_register_1 = require("./prompts/tools-register");
 const run_1 = require("./run/run");
 const stream_1 = require("./run/stream");
 const raw_1 = require("./run/raw");
+const record_call_1 = require("./run/record-call");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
 const grounding_1 = require("./run/grounding");
@@ -69,10 +70,11 @@ const DEFAULT_REPLAY_ENVELOPE_USD = 10;
 function createRig(config) {
     // CE-8 (R1): `routesDir: null` is a first-class runRaw-only rig — skip route
     // loading, the manifest, and the serveability gate; route methods throw below.
-    const routes = config.routesDir === null ? (0, rawonly_1.emptyRouteStore)() : (0, rawonly_1.loadRoutesOrReport)(config, config.routesDir);
+    const routesDir = (0, rawonly_1.effectiveRoutesDir)(config); // SURF-1: absent DEFAULT dir ⇒ warn + raw-only; explicit ⇒ load (throws if missing)
+    const routes = routesDir === null ? (0, rawonly_1.emptyRouteStore)() : (0, rawonly_1.loadRoutesOrReport)(config, routesDir);
     // rig.yaml lives at the rig dir root, one level above routes/
     // (modelrig/rig.yaml next to modelrig/routes/ — cost-dimensions-design §2a).
-    const manifest = config.routesDir === null ? null : (0, manifest_1.loadManifest)((0, node_path_1.dirname)(config.routesDir));
+    const manifest = routesDir === null ? null : (0, manifest_1.loadManifest)((0, node_path_1.dirname)(routesDir));
     // Registry facts load BEFORE adapters: the A1 compat hosts take their
     // capability profile from the registry, never from the dialect.
     const registryFacts = (0, facts_1.loadRegistryFacts)(config.registryPath);
@@ -250,6 +252,7 @@ function createRig(config) {
         runRawStream(input) {
             return (0, raw_1.runRawStream)(rawDeps, input);
         },
+        recordCall: (input) => (0, record_call_1.recordCall)(rawDeps, input),
         grade: gradeApi.grade,
         replay(route, opts) {
             return (0, replay_1.replayVariant)(deps, captureStoreForReplay(), {
@@ -326,7 +329,7 @@ function createRig(config) {
         // CE-8 (R1): a runRaw-only rig (routesDir: null) has no routes — override
         // every route-dependent surface to throw a teaching invariant_violation.
         // Spread LAST so it wins over the real methods above; empty for a routed rig.
-        ...(config.routesDir === null ? (0, rawonly_1.rawOnlyRouteMethods)() : {}),
+        ...(routesDir === null ? (0, rawonly_1.rawOnlyRouteMethods)(config.routesDir === null ? "routesDir-null" : "absent-default") : {}),
     };
 }
 var config_2 = require("./config");
@@ -471,6 +474,13 @@ Object.defineProperty(exports, "resolveCallConfigForRun", { enumerable: true, ge
 var raw_2 = require("./run/raw");
 Object.defineProperty(exports, "runRaw", { enumerable: true, get: function () { return raw_2.runRaw; } });
 Object.defineProperty(exports, "runRawStream", { enumerable: true, get: function () { return raw_2.runRawStream; } });
+var lanes_1 = require("./telemetry/lanes");
+Object.defineProperty(exports, "isRoutedLane", { enumerable: true, get: function () { return lanes_1.isRoutedLane; } });
+Object.defineProperty(exports, "callLaneOf", { enumerable: true, get: function () { return lanes_1.callLaneOf; } });
+Object.defineProperty(exports, "RAW_LANE", { enumerable: true, get: function () { return lanes_1.RAW_LANE; } });
+Object.defineProperty(exports, "EXTERNAL_LANE", { enumerable: true, get: function () { return lanes_1.EXTERNAL_LANE; } });
+Object.defineProperty(exports, "RECORDED_BADGE", { enumerable: true, get: function () { return lanes_1.RECORDED_BADGE; } });
+Object.defineProperty(exports, "RECORDED_TOOLTIP", { enumerable: true, get: function () { return lanes_1.RECORDED_TOOLTIP; } });
 // CE-8 runRaw-only (routesDir: null): the string-narrowing guard route-required
 // consumers (server, oracle) use, plus the teaching failure it throws.
 var rawonly_2 = require("./run/rawonly");

package/dist/init/init-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-cli.d.ts","sourceRoot":"","sources":["../../src/init/init-cli.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAwFnD"}
+{"version":3,"file":"init-cli.d.ts","sourceRoot":"","sources":["../../src/init/init-cli.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAelD,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CA+FnD"}

package/dist/init/init-cli.js

@@ -15,13 +15,23 @@ const rawonly_1 = require("../run/rawonly");
 const rows_1 = require("../registry/rows");
 const observe_cli_1 = require("./observe-cli");
 const run_1 = require("./run");
+const starter_1 = require("./starter");
+/** Write the starter route's schema + prompt (SURF-1, audit #2) and say so. */
+function writeStarter(routesDir) {
+    const starter = (0, starter_1.writeStarterFiles)(routesDir, { existsSync: node_fs_1.existsSync, mkdirSync: node_fs_1.mkdirSync, writeFileSync: node_fs_1.writeFileSync }, { join: node_path_1.join, dirname: node_path_1.dirname });
+    if (starter.written.length > 0) {
+        console.log(`\nwrote the starter route's schema and prompt (${starter.written.join(", ")}), so the\n` +
+            "example.support_summarize route shown in the console and the docs validates as pasted.");
+    }
+}
 function cmdInit(flags) {
     // `init --observe` is the observe-first (T0/T1) alias for `modelrig observe`.
     if (flags.bare.has("observe"))
         return (0, observe_cli_1.cmdObserve)(flags);
     const root = (0, node_path_1.resolve)(flags.positional[0] ?? ".");
     const config = (0, config_1.loadConfigFromEnv)();
-    const draftsDir = flags.named.get("out") ?? (0, node_path_1.join)((0, rawonly_1.requireRoutesDir)(config, "modelrig init"), "drafts");
+    const routesDir = (0, rawonly_1.requireRoutesDir)(config, "modelrig init");
+    const draftsDir = flags.named.get("out") ?? (0, node_path_1.join)(routesDir, "drafts");
     const scope = (0, observe_cli_1.scopeFrom)(flags);
     // Registry rows seed the challenger candidates. A missing/unbuilt registry
     // is not fatal — drafts then carry the incumbent alone, and say so.
@@ -44,6 +54,9 @@ function cmdInit(flags) {
         ...(scope !== undefined ? { scope } : {}),
     });
     if (flags.bare.has("json")) {
+        const starter = flags.bare.has("dry-run")
+            ? { written: [], skipped: [] }
+            : (0, starter_1.writeStarterFiles)(routesDir, { existsSync: node_fs_1.existsSync, mkdirSync: node_fs_1.mkdirSync, writeFileSync: node_fs_1.writeFileSync }, { join: node_path_1.join, dirname: node_path_1.dirname });
         console.log(JSON.stringify({
             sitesFound: result.sitesFound,
             filesScanned: result.filesScanned,
@@ -56,17 +69,20 @@ function cmdInit(flags) {
                 model: d.site.model,
                 notes: d.site.notes,
             })),
-            written: result.written,
-            skipped: result.skipped,
+            written: [...result.written, ...starter.written],
+            skipped: [...result.skipped, ...starter.skipped],
         }, null, 2));
         return 0;
     }
     console.log(`modelrig init — scanned ${result.filesScanned} file(s) under ${root}` +
         (scope !== undefined ? ` (scoped to ${scope.join(", ")})` : "") +
         `\nfound ${result.sitesFound} provider call site(s)`);
+    const dryRun = flags.bare.has("dry-run");
     if (result.sitesFound === 0) {
         console.log("\nNothing to draft. If you know there are model calls here, they may sit behind a helper\n" +
             "that hides the SDK — point init at the file that actually calls the provider.");
+        if (!dryRun)
+            writeStarter(routesDir);
         return 0;
     }
     for (const draft of result.drafts) {
@@ -76,10 +92,11 @@ function cmdInit(flags) {
     if (result.filesSkipped.length > 0) {
         console.log(`\n${result.filesSkipped.length} file(s) skipped (too large or unreadable).`);
     }
-    if (flags.bare.has("dry-run")) {
+    if (dryRun) {
         console.log("\n--dry-run: nothing written.");
         return 0;
     }
+    writeStarter(routesDir);
     console.log(`\nwrote ${result.written.length} file(s) to ${draftsDir}` +
         (result.skipped.length > 0 ? ` (${result.skipped.length} left alone — already there)` : "") +
         `\nread ${(0, node_path_1.join)(draftsDir, "MIGRATION.md")} next. Your source was not touched.`);

package/dist/init/observe-cli.js

@@ -69,6 +69,6 @@ function cmdObserve(flags) {
     console.log(`\nwrote ${result.written.length} file(s) to ${outDir}` +
         (result.skipped.length > 0 ? ` (${result.skipped.length} left alone — already there)` : "") +
         `\nread ${(0, node_path_1.join)(outDir, "OBSERVE.md")} next — apply the wiring diffs one step at a time.` +
-        "\nObserve changes no behaviour; with no control plane configured your pipeline is byte-for-byte the same.");
+        "\nObserve changes no behaviour; with no MODELRIG_API_KEY set your pipeline is byte-for-byte the same.");
     return 0;
 }

package/dist/init/observe.d.ts

@@ -70,7 +70,13 @@ export interface ObserveDeps {
 export declare function stepKeyFor(site: CallSite, used: Set<string>): string;
 /** 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. */
 export declare function seamContent(): string;
 export declare function buildObserveMarkdown(plans: readonly ObservePlan[], seamPath: string, result: {
     sitesFound: number;

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

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/init/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;kFACkF;AAClF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,cAAc,GAAG;QAC5B,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;QACnC,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;YAAE,SAAS,EAAE,OAAO,CAAA;SAAE,KAAK,IAAI,CAAC;QAC1D,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;KAC1D,CAAC;IACF,QAAQ,CAAC,IAAI,EAAE;QACb,IAAI,EAAE,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;QACrC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;QAC/C,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;QAC/B,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;KAC/C,CAAC;CACH;AAKD;iFACiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAQpE;AAED;;4EAE4E;AAC5E,wBAAgB,WAAW,IAAI,MAAM,CA6DpC;AAoCD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EACrF,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GACxB,MAAM,CAmHR;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,cAAmB,GAAG,aAAa,CA6DzF"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/init/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;kFACkF;AAClF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,cAAc,GAAG;QAC5B,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;QACnC,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;YAAE,SAAS,EAAE,OAAO,CAAA;SAAE,KAAK,IAAI,CAAC;QAC1D,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;KAC1D,CAAC;IACF,QAAQ,CAAC,IAAI,EAAE;QACb,IAAI,EAAE,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;QACrC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;QAC/C,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;QAC/B,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;KAC/C,CAAC;CACH;AAUD;iFACiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAQpE;AAED;;;;;;;;2BAQ2B;AAC3B,wBAAgB,WAAW,IAAI,MAAM,CA6EpC;AA6DD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EACrF,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GACxB,MAAM,CA0HR;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,cAAmB,GAAG,aAAa,CA6DzF"}

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/raw-finalize.d.ts

@@ -9,14 +9,50 @@
  * recorder — NO route/registry/capability-gate dependency.
  */
 import { type ActiveRunContext } from "../artifacts/run-context";
-import type { AdapterResult, ServiceTier } from "../types/provider";
-import type { RunResult } from "../types/route";
+import type { AdapterResult, AdapterUsage, ProviderId, ServiceTier } from "../types/provider";
+import type { RunResult, RunTags } from "../types/route";
+import type { AttemptMetaV1 } from "../telemetry/attempt-meta";
+import type { TelemetryRow, TelemetryStore } from "../types/telemetry";
 import type { RawRunDeps, RawRunInput } from "./raw";
 /** 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. */
 export declare function rawTimeoutFixHint(input: RawRunInput, tier: ServiceTier): string;
+export interface RawRowParts {
+    readonly id: string;
+    readonly rawModelId: string;
+    /** A `ProviderId` on the raw lane; any non-empty string on a recorded call
+     * (OBS-1 `rig.recordCall` accepts providers ModelRig has no adapter for). */
+    readonly provider: ProviderId | string;
+    readonly model: string;
+    readonly usage?: AdapterUsage;
+    readonly costUsd: number;
+    readonly latencyMs: number;
+    /** CE-2 F2: the DECLARED service tier (default "standard"), reported truthfully
+     * on the row instead of the old hardcode. */
+    readonly requestedTier: ServiceTier;
+    /** OBS-1: the served tier when no `usage` is supplied — unused on the raw
+     * lane (absent ⇒ `usage.servedTier ?? "standard"`, byte-identical). */
+    readonly servedTier?: ServiceTier;
+    readonly failureClass: TelemetryRow["failureClass"];
+    readonly tags: RunTags;
+    readonly pricingMissing: boolean;
+    /** CE-1: the customer cache key applied to this raw dispatch, or null. */
+    readonly cacheKey?: string | null;
+    /** The per-call ladder key (spec §2.1 R0). The raw lane is a single-attempt,
+     * single-candidate dispatch: one call_id, attempt_seq 1, candidate_index 0. */
+    readonly callId: string;
+    /** WI-1 attempt envelope (spec §2) — built by the SAME producer the routed
+     * lane uses (lane parity), from the SAME rendered-request canonicalization. */
+    readonly meta?: AttemptMetaV1 | null;
+}
+/** Write the metered raw-lane telemetry row. Mirrors the run loop's minimal
+ * `recordSearchCostRow` shape: only load-bearing fields set, route = the
+ * `provider/model` handle the caller used, lane + key_ownership riding in
+ * `tags_json`. The exporter mirrors it on its normal cadence — no lane column,
+ * no schema change (telemetry map, 2026-08-10). */
+export declare function recordRawRow(telemetry: TelemetryStore, p: RawRowParts): void;
 /** The active-run-context binding a raw call resolves ONCE at entry (the ALS
  * boundary — read synchronously before the stream generator defers), so
  * `finalizeRaw` can mirror the call into a ground-truth step (G1 spec §4). Null
@@ -34,7 +70,17 @@ export interface RawStepContext {
  * 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.
  */
-export declare function prepareRawStep(deps: RawRunDeps, input: RawRunInput): RawStepContext | null;
+export declare function prepareRawStep(deps: Pick<RawRunDeps, "manifest">, input: {
+    readonly provider: string;
+    readonly model: string;
+    readonly stepKey?: string;
+    readonly tags?: RunTags;
+}): RawStepContext | null;
+/** 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). */
+export declare function emitRawStep(step: RawStepContext | null, task: string, inferenceId: string, failureClass: string | null): void;
 /**
  * Turn an `AdapterResult` into a RunResult, recording exactly one telemetry row.
  * Shared by the buffered and streaming paths so cost/telemetry are byte-identical.

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

@@ -1 +1 @@
-{"version":3,"file":"raw-finalize.d.ts","sourceRoot":"","sources":["../../src/run/raw-finalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,aAAa,EAGb,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAW,SAAS,EAAW,MAAM,gBAAgB,CAAC;AAKlE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAErD;;;wEAGwE;AACxE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAS/E;AA6ED;;;kFAGkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,cAAc,GAAG,IAAI,CAU1F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,cAAc,GAAG,IAAI,GAC1B,SAAS,CA6JX"}
+{"version":3,"file":"raw-finalize.d.ts","sourceRoot":"","sources":["../../src/run/raw-finalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAW,SAAS,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAErD;;;wEAGwE;AACxE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAS/E;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;iFAC6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;iDAC6C;IAC7C,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC;IACpC;2EACuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC;mFAC+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;mFAC+E;IAC/E,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;CACtC;AAED;;;;mDAImD;AACnD,wBAAgB,YAAY,CAAC,SAAS,EAAE,cAAc,EAAE,CAAC,EAAE,WAAW,GAAG,IAAI,CA4C5E;AAED;;;kFAGkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,EAClC,KAAK,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/G,cAAc,GAAG,IAAI,CAUvB;AAED;;;0DAG0D;AAC1D,wBAAgB,WAAW,CACzB,IAAI,EAAE,cAAc,GAAG,IAAI,EAC3B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,IAAI,CAUN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,cAAc,GAAG,IAAI,GAC1B,SAAS,CA8JX"}