modelrig 0.9.0 → 0.11.0

package/dist/run/record-attempt.js

@@ -14,10 +14,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.rungOf = rungOf;
 exports.createRecordAttempt = createRecordAttempt;
 const node_crypto_1 = require("node:crypto");
+const dispatch_1 = require("./dispatch");
+const destination_1 = require("./destination");
 const failures_1 = require("../types/failures");
 const cache_stamp_1 = require("./cache-stamp");
 const cache_handle_1 = require("./cache-handle");
 const attempt_meta_1 = require("../telemetry/attempt-meta");
+const telemetry_row_1 = require("./telemetry-row");
 /**
  * Classify a recorded row's ladder rung (R1 review, F1). `primaryDispatched`
  * carries the candidate indices already given a primary dispatch on this call —
@@ -109,6 +112,9 @@ function createRecordAttempt(deps) {
                 tokensIn: attempt.tokensIn,
                 tokensOut: attempt.tokensOut,
                 tokensCached: attempt.tokensCached,
+                // Issue #2 (L6 F1): the SERVED tier, so meta.cost components price at
+                // the same tier as cost_estimate_usd and still sum to the row (WI-1).
+                servedTier: attempt.servedTier,
                 ...(attempt.tokensCacheWrite !== undefined ? { tokensCacheWrite: attempt.tokensCacheWrite } : {}),
                 ...(attempt.tokensCacheWrite1h !== undefined ? { tokensCacheWrite1h: attempt.tokensCacheWrite1h } : {}),
             },
@@ -121,9 +127,13 @@ function createRecordAttempt(deps) {
         // stepKey ?? tags.step ?? the auto `route#n` key, so a caller's own step lands
         // unchanged and the tag agrees with the ground-truth step row.
         const stepTag = runCtx !== null && autoStepKey !== null ? { step: autoStepKey } : {};
-        const row = {
+        // U4: the row is assembled — and its tags serialized — by the ONE shared
+        // builder (./telemetry-row.ts). `rung` is stamped LAST inside stampRowTags so
+        // a caller's extraTags (Q1 quality tags) can never override the
+        // recorder-owned rung. Cache-write accounting (WS-A) + WS-C substrate + the
+        // CS-1 mask receipt ride the same builder unchanged.
+        const row = (0, telemetry_row_1.buildTelemetryRow)({
             id: (0, node_crypto_1.randomUUID)(),
-            ts: new Date().toISOString(),
             route: route.route,
             routeVersion: route.version,
             provider: attempt.candidate.provider,
@@ -133,31 +143,35 @@ function createRecordAttempt(deps) {
             tokensIn: attempt.tokensIn,
             tokensOut: attempt.tokensOut,
             tokensCached: attempt.tokensCached,
-            // Cache-write accounting (WS-A) + request-path substrate (WS-C).
             tokensCacheWrite: attempt.tokensCacheWrite ?? 0,
             tokensCacheWrite1h: attempt.tokensCacheWrite1h ?? 0,
-            cacheKey,
-            prefixFingerprint: cacheStamp?.prefixFingerprint ?? null,
             costEstimateUsd: attempt.costUsd,
             latencyMs: attempt.latencyMs,
             ttfbMs: attempt.ttfbMs ?? null,
             failureClass: attempt.failure?.class ?? null,
             attemptsJson: JSON.stringify(ledger.snapshot()),
-            // `rung` is stamped LAST so a caller's extraTags (Q1 quality tags) can
-            // never override the recorder-owned rung.
-            tagsJson: JSON.stringify({ ...stepTag, ...effectiveTags, ...attempt.extraTags, rung }),
+            // U3 (D-2) × U4: the serving `destination` tag rides the ONE shared row
+            // builder — `buildTelemetryRow` → `stampRowTags` serializes `tags_json` in a
+            // single place, and `rung` is stamped LAST there so a caller's extraTags can
+            // never override it. `destinationTag()` returns `{}` for the default `direct`,
+            // so a direct/absent routed row stays byte-identical; a `modelrig-served` row
+            // gains `destination`. Folded into `baseTags` here because `destination` is a
+            // routed-lane concept (the raw/search recorders have none).
+            baseTags: { ...stepTag, ...effectiveTags, ...(0, dispatch_1.destinationTag)(deps.destination ?? destination_1.DEFAULT_DESTINATION) },
+            extraTags: attempt.extraTags,
+            rung,
             fingerprintCell: route.fingerprintCell,
             servedVariant,
             repairedBy: attempt.repairedBy ?? null,
             pricingMissing: attempt.pricingMissing ?? false,
+            cacheKey,
+            prefixFingerprint: cacheStamp?.prefixFingerprint ?? null,
             callId: ladderKey.callId,
             attemptSeq: ladderKey.attemptSeq,
             candidateIndex: ladderKey.candidateIndex,
             meta,
-            // CS-1 (spec §6): the counts-only mask receipt for this attempt, or absent
-            // when the route does not mask. NEVER a matched value.
-            ...(attempt.mask !== undefined ? { mask: attempt.mask } : {}),
-        };
+            mask: attempt.mask,
+        });
         telemetry.record(row);
         // Mirror this inference into a ground-truth step attempt (fail-open — the
         // context swallows buffer errors; the run loop is never affected).

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

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

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

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

package/dist/run/record-call.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * OBS-1 — `rig.recordCall()`: record a provider call ModelRig did NOT dispatch
+ * (acceptance ruling M12, Option A). The customer's own code made the call with
+ * its own key; it reports what the provider returned (tokens, tier, latency,
+ * failure) and ModelRig writes ONE telemetry row for it, exactly the shape the
+ * raw lane writes — same builder, same cost function, same step emission — so
+ * the call shows on /inferences, joins its run and step, and can be graded.
+ *
+ * WHAT IS DIFFERENT FROM THE RAW LANE (and nothing else is):
+ *  - `tags.lane = "external"` (SDK-owned, stamped LAST — a caller tag cannot
+ *    override it). Named `external`, not `direct`: ruling D-2 already uses
+ *    "direct" for `destination`.
+ *  - `tags.key_ownership = "byok"` (SDK-owned). Gate B-0 (usage-aggregation.ts):
+ *    a BYOK seam must stamp the tag at that seam. A recorded call is always the
+ *    customer's key — ModelRig bore no provider cost — so it can never settle as
+ *    a managed charge.
+ *  - `meta.provenance = "caller-reported"`: the numbers are the caller's, not a
+ *    measurement. Nothing was validated (`validated` is never claimed).
+ *
+ * CONTRACT: synchronous (the row is written to the local store; the exporter
+ * ships it on its normal cadence) and NEVER throws into the caller. Bad input is
+ * warned with a teaching fix (P4) and returns `{ inferenceId: null, … }` with no
+ * row written.
+ *
+ * No route/registry/capability-gate dependency beyond the raw lane's own (cost
+ * + telemetry + run context) — the raw lane's no-hard-hot-path invariant holds.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_MS = exports.MAX_ROUTE_CHARS = exports.RECORD_CALL_DOCS_URL = exports.EXTERNAL_LANE = void 0;
+exports.resetRecordCallWarningsForTest = resetRecordCallWarningsForTest;
+exports.toCount = toCount;
+exports.recordCall = recordCall;
+const node_crypto_1 = require("node:crypto");
+const cost_1 = require("./cost");
+const raw_finalize_1 = require("./raw-finalize");
+const raw_search_cost_1 = require("./raw-search-cost");
+const attempt_meta_map_1 = require("../adapters/attempt-meta-map");
+const run_context_1 = require("../artifacts/run-context");
+const lanes_1 = require("../telemetry/lanes");
+const attempt_meta_1 = require("../telemetry/attempt-meta");
+const failures_teaching_1 = require("../types/failures-teaching");
+const provider_1 = require("../types/provider");
+/** The lane tag a recorded call carries (SDK-owned) — the shared classifier's constant. */
+var lanes_2 = require("../telemetry/lanes");
+Object.defineProperty(exports, "EXTERNAL_LANE", { enumerable: true, get: function () { return lanes_2.EXTERNAL_LANE; } });
+/** Where the warning's fix points (the "record them" section). */
+exports.RECORD_CALL_DOCS_URL = "https://modelrig.dev/not-captured.html";
+const REJECTED = { inferenceId: null, callId: null, costEstimateUsd: 0, pricingMissing: false };
+const SERVICE_TIERS = new Set(["standard", "flex", "priority"]);
+const FINISH_REASONS = new Set([
+    "stop", "length", "tool_calls", "content_filter", "refusal", "error", "other",
+]);
+const KNOWN_PROVIDERS = new Set(provider_1.PROVIDER_IDS);
+/** Server ingest's route cap (`modelrig-server` ingest.ts `isNonEmptyString(raw.route, 200)`). */
+exports.MAX_ROUTE_CHARS = 200;
+/** Max distinct rules the once-per-rule warning latch remembers (L6 NIT-3). */
+const WARN_LATCH_MAX = 100;
+const warned = new Set();
+/** Warn once per validation RULE. The latch key is the rule id — never a
+ * caller-supplied string — and the set is bounded, so a caller looping over bad
+ * input with varying values cannot grow it. */
+function warnOnce(rule, problem, fix) {
+    if (warned.has(rule))
+        return;
+    if (warned.size < WARN_LATCH_MAX)
+        warned.add(rule);
+    console.warn(`[modelrig recordCall] ${problem} — nothing was recorded. fix: ${fix} (${exports.RECORD_CALL_DOCS_URL})`);
+}
+/** Test-only: clear the once-per-rule warning latch. */
+function resetRecordCallWarningsForTest() {
+    warned.clear();
+}
+function isCount(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 0;
+}
+/** The ceiling for latency/ttfb (Postgres `integer`, 2³¹−1 ms ≈ 24.8 days). */
+exports.MAX_MS = 2147483647;
+/**
+ * L6 MUST-3 integer hygiene. Telemetry columns are integers, but a caller's
+ * `performance.now()` delta is fractional — so ROUND to the nearest integer
+ * (friendlier than rejecting) and CLAMP: latency/ttfb to ≤ 2³¹−1 ms, token
+ * counts to ≤ Number.MAX_SAFE_INTEGER. Applied before any check that compares
+ * token counts, so validation and the recorded row see the same numbers.
+ */
+function toCount(v, max) {
+    return Math.min(Math.round(v), max);
+}
+const tok = (v) => (typeof v === "number" ? toCount(v, Number.MAX_SAFE_INTEGER) : 0);
+function isNonEmpty(v, max) {
+    return typeof v === "string" && v.length > 0 && v.length <= max;
+}
+/** Validate the caller's input. Returns the failed rule, or null. */
+function validate(input) {
+    const p = validateShape(input);
+    return p === null ? null : { rule: p.fix, ...p };
+}
+/** The rule checks. Every `fix` string is built only from SDK constants and
+ * field names (never from a caller value), so it doubles as the rule id. */
+function validateShape(input) {
+    if (typeof input !== "object" || input === null) {
+        return { problem: "input is not an object", fix: "call rig.recordCall({ provider, model, usage, latencyMs })" };
+    }
+    const i = input;
+    if (!isNonEmpty(i.provider, 100)) {
+        return { problem: "provider is missing", fix: 'pass the provider id, e.g. provider: "gemini"' };
+    }
+    if (!isNonEmpty(i.model, 200)) {
+        return { problem: "model is missing", fix: 'pass the model id your code called, e.g. model: "gemini-3.1-pro-preview"' };
+    }
+    // L6 SHOULD-2: the row's route is `provider/model`; server ingest drops a
+    // route over 200 chars (ingest.ts), so refuse here instead of writing a row
+    // that would never arrive.
+    if (i.provider.length + 1 + i.model.length > exports.MAX_ROUTE_CHARS) {
+        return {
+            problem: `provider/model is longer than ${exports.MAX_ROUTE_CHARS} characters`,
+            fix: `shorten the provider or model id so "provider/model" is at most ${exports.MAX_ROUTE_CHARS} characters`,
+        };
+    }
+    const u = i.usage;
+    if (typeof u !== "object" || u === null || !isCount(u.tokensIn) || !isCount(u.tokensOut)) {
+        return {
+            problem: "usage.tokensIn / usage.tokensOut are missing or not non-negative numbers",
+            fix: "copy them from the provider response's usage block (Gemini usageMetadata.promptTokenCount / candidatesTokenCount; OpenAI usage.prompt_tokens / completion_tokens)",
+        };
+    }
+    for (const k of ["tokensCached", "tokensCacheWrite", "reasoningTokens"]) {
+        if (u[k] !== undefined && !isCount(u[k])) {
+            return { problem: `usage.${k} is not a non-negative number`, fix: `omit usage.${k} or pass a number ≥ 0` };
+        }
+    }
+    if (tok(u.tokensCached) + tok(u.tokensCacheWrite) > tok(u.tokensIn)) {
+        return {
+            problem: "usage.tokensCached + usage.tokensCacheWrite exceed usage.tokensIn",
+            fix: "tokensIn is the TOTAL input and includes cached and cache-write tokens (Anthropic reports input_tokens without them — add cache_read_input_tokens and cache_creation_input_tokens back)",
+        };
+    }
+    if (!isCount(i.latencyMs)) {
+        return { problem: "latencyMs is missing or not a non-negative number", fix: "measure the call's wall time in ms and pass latencyMs" };
+    }
+    if (i.ttfbMs !== undefined && !isCount(i.ttfbMs)) {
+        return { problem: "ttfbMs is not a non-negative number", fix: "omit ttfbMs or pass a number ≥ 0" };
+    }
+    for (const k of ["servedTier", "requestedTier"]) {
+        if (i[k] !== undefined && !(typeof i[k] === "string" && SERVICE_TIERS.has(i[k]))) {
+            return { problem: `${k} is not a service tier`, fix: `pass "standard", "flex" or "priority", or omit ${k}` };
+        }
+    }
+    if (i.failureClass !== undefined && i.failureClass !== null) {
+        if (typeof i.failureClass !== "string" || !Object.prototype.hasOwnProperty.call(failures_teaching_1.FAILURE_TEACHING, i.failureClass)) {
+            return {
+                problem: `failureClass "${String(i.failureClass)}" is not a ModelRig failure class`,
+                fix: `use one of ${Object.keys(failures_teaching_1.FAILURE_TEACHING).join(", ")}, or null for a success`,
+            };
+        }
+    }
+    if (i.webSearchCalls !== undefined && !(isCount(i.webSearchCalls) && Number.isInteger(i.webSearchCalls))) {
+        return { problem: "webSearchCalls is not a whole number ≥ 0", fix: "pass the count of billed web_search tool calls, or omit it" };
+    }
+    if (i.tags !== undefined) {
+        if (typeof i.tags !== "object" || i.tags === null || Array.isArray(i.tags)) {
+            return { problem: "tags is not an object", fix: 'pass tags as { key: "value" } strings' };
+        }
+        for (const [k, v] of Object.entries(i.tags)) {
+            if (v !== undefined && typeof v !== "string") {
+                return { problem: `tags.${k} is not a string`, fix: "tag values are strings — String() the value" };
+            }
+        }
+    }
+    for (const k of ["stepKey", "providerRequestId", "finishReason"]) {
+        if (i[k] !== undefined && typeof i[k] !== "string") {
+            return { problem: `${k} is not a string`, fix: `omit ${k} or pass a string` };
+        }
+    }
+    return null;
+}
+/** Normalize a caller finish reason: an enum value passes; a provider-native one
+ * maps through the adapters' own table; empty ⇒ absent. */
+function finishReasonOf(provider, raw) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    if (FINISH_REASONS.has(raw))
+        return raw;
+    return (0, attempt_meta_map_1.mapFinishReason)((KNOWN_PROVIDERS.has(provider) ? provider : "openai"), raw);
+}
+/**
+ * Record one call the caller made itself. See the module header for the
+ * contract. `deps` is the rig's raw-lane deps (telemetry + unpriced rate +
+ * manifest) — the same object `runRaw` receives.
+ */
+function recordCall(deps, input) {
+    try {
+        const bad = validate(input);
+        if (bad !== null) {
+            warnOnce(bad.rule, bad.problem, bad.fix);
+            return REJECTED;
+        }
+        return record(deps, input);
+    }
+    catch (err) {
+        // Instrumentation never throws into customer code (P4 graceful degradation).
+        warnOnce("unexpected", `unexpected error (${err instanceof Error ? err.message : String(err)})`, "report this to ModelRig");
+        return REJECTED;
+    }
+}
+function record(deps, input) {
+    // Same ALS-boundary read + step key resolution + dimension hygiene as runRaw.
+    const step = (0, raw_finalize_1.prepareRawStep)(deps, input);
+    const provider = input.provider;
+    const known = KNOWN_PROVIDERS.has(provider);
+    const rawModelId = `${provider}/${input.model}`;
+    const servedTier = input.servedTier ?? "standard";
+    const requestedTier = input.requestedTier ?? servedTier;
+    // MUST-3: integers only on the row (rounded + clamped — see toCount).
+    const usage = {
+        tokensIn: tok(input.usage.tokensIn),
+        tokensOut: tok(input.usage.tokensOut),
+        tokensCached: tok(input.usage.tokensCached),
+        ...(input.usage.tokensCacheWrite !== undefined ? { tokensCacheWrite: tok(input.usage.tokensCacheWrite) } : {}),
+        servedTier,
+        ...(input.ttfbMs !== undefined ? { ttfbMs: toCount(input.ttfbMs, exports.MAX_MS) } : {}),
+    };
+    const latencyMs = toCount(input.latencyMs, exports.MAX_MS);
+    // Priced exactly like the raw lane: list price at the SERVED tier. A provider
+    // ModelRig has no price table for is recorded honestly at $0, flagged.
+    const unpricedRatePerTok = (deps.unpricedRateUsdPerMTok ?? cost_1.DEFAULT_UNPRICED_RATE_USD_PER_MTOK) / 1000000;
+    const { costUsd, pricingMissing } = known
+        ? (0, cost_1.attemptCost)(provider, input.model, usage, unpricedRatePerTok)
+        : { costUsd: 0, pricingMissing: true };
+    // Tags: caller tags + the ambient step/run_id (same order as finalizeRaw), then
+    // the SDK-owned markers LAST so a caller value cannot override them.
+    const stepTag = step !== null ? { step: step.stepKey } : {};
+    const tags = {
+        ...stepTag,
+        ...(0, run_context_1.withRunIdTag)(input.tags ?? {}, step?.runCtx ?? null),
+        key_ownership: "byok",
+        lane: lanes_1.EXTERNAL_LANE,
+    };
+    const finishReason = finishReasonOf(provider, input.finishReason);
+    const adapterMeta = {
+        ...(finishReason !== undefined ? { finish_reason: finishReason } : {}),
+        ...(input.providerRequestId !== undefined ? { provider_request_id: input.providerRequestId } : {}),
+        ...(input.usage.reasoningTokens !== undefined ? { reasoning_tokens: tok(input.usage.reasoningTokens) } : {}),
+    };
+    // No rendered request and no output text: ModelRig never saw the content, so
+    // there is no input/output hash. Cost components only for a priced provider.
+    const meta = (0, attempt_meta_1.summarizeAttemptMeta)({
+        adapterMeta,
+        provenance: "caller-reported",
+        ...(known ? { provider: provider, model: input.model } : {}),
+        usage,
+    });
+    const id = (0, node_crypto_1.randomUUID)();
+    const callId = (0, node_crypto_1.randomUUID)();
+    const failureClass = input.failureClass ?? null;
+    (0, raw_finalize_1.recordRawRow)(deps.telemetry, {
+        id,
+        rawModelId,
+        provider,
+        model: input.model,
+        usage,
+        costUsd,
+        latencyMs,
+        requestedTier,
+        failureClass,
+        tags,
+        pricingMissing,
+        callId,
+        meta,
+    });
+    (0, raw_finalize_1.emitRawStep)(step, input.tags?.step ?? rawModelId, id, failureClass);
+    const searchCalls = input.webSearchCalls ?? 0;
+    if (searchCalls >= 1) {
+        (0, raw_search_cost_1.recordRawSearchCostRow)(deps.telemetry, { provider, rawModelId, tags, callId, searchCalls });
+    }
+    return { inferenceId: id, callId, costEstimateUsd: costUsd, pricingMissing };
+}

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

@@ -0,0 +1,68 @@
+/**
+ * The routed lane's REPAIR RUNG (spec §4, WS2), extracted from run.ts as a
+ * factory over the run's per-call state — mirroring the `createRecordAttempt`
+ * factory pattern in ./record-attempt.ts, and for the same reason: run.ts sits
+ * at the 700-LOC cap (dev-rule P1), and the repair closure is a large,
+ * self-contained block (~157 LOC). This is a PURE MOVE (Unified Route U4,
+ * behavior-preserving): the logic, the record shapes, the throw conditions, and
+ * the returned `RunResult` meta are byte-identical to the former inline closure.
+ *
+ * The one mechanical change the move forces: the former closure read the run
+ * loop's mutable `injectedSources` binding directly; the factory-built function
+ * receives it as an explicit call argument instead (the run loop passes the
+ * value in scope for the candidate being repaired), so behavior is unchanged.
+ */
+import type { ProviderAdapter, CandidateRef } from "../types/provider";
+import type { RigFailure } from "../types/failures";
+import type { RouteBundle, RunResult } from "../types/route";
+import type { ScreenReceipt } from "../screen/types";
+import type { EnvelopeGuard } from "./envelope";
+import type { RunMode } from "./resolve";
+import type { RepairStep } from "./repair";
+import type { AttemptTelemetry } from "./dispatch";
+import type { SearchResultItem } from "./grounding";
+import type { LadderKeyMinter } from "./ladder-key";
+import type { RetryLedger } from "./retry";
+import type { Destination } from "./destination";
+/** User turn for repair calls (WS2) — same terse-trigger convention run.ts uses
+ * for the primary directive. Moved here with the repair closure. */
+export declare const REPAIR_DIRECTIVE = "Produce the corrected JSON object now, following the system instructions exactly.";
+/** The user turn of a SAME-MODEL repair re-ask (issue #5, R1): on a route that
+ * declares `prompt.user`, the rendered per-call user turn is kept ahead of the
+ * repair directive (the delta is content the model needs to correct against —
+ * dropping it would be the silent loss R1 closes); on every other route the
+ * directive alone, byte-identical to pre-R1. Pure; exported for the tests. */
+export declare function repairUserTurn(route: Pick<RouteBundle, "userTemplate">, originalUserPrompt: string): string;
+export interface RepairAttemptOutcome {
+    readonly done?: RunResult;
+    readonly invalid?: {
+        readonly text: string;
+        readonly errors: readonly string[];
+    };
+}
+export interface AttemptRepairDeps {
+    readonly adapters: ReadonlyMap<string, ProviderAdapter>;
+    readonly guard: EnvelopeGuard | null;
+    readonly unpricedRatePerTok: number;
+    readonly route: RouteBundle;
+    readonly mode: RunMode;
+    readonly recordAttempt: (attempt: AttemptTelemetry) => string;
+    readonly captureAttempt: (inferenceId: string, text: string) => void;
+    readonly ledger: RetryLedger;
+    readonly servedVariant: string | null;
+    readonly ladder: LadderKeyMinter;
+    readonly destination: Destination;
+    /** run.ts's `failRun` — records a pre-dispatch terminal row and throws. */
+    readonly failRun: (candidate: CandidateRef, failure: RigFailure, latencyMs: number, screen?: ScreenReceipt) => never;
+}
+/**
+ * Build the run loop's `attemptRepair`. Returns a function performing ONE repair
+ * dispatch: `{done}` on schema-valid output, `{invalid}` with the newest
+ * output+errors for chaining, or null when the dispatch itself failed (adapter
+ * failure / unmintable repair candidate). `injectedSources` is the run loop's
+ * current grounding-inject payload for the candidate under repair (null when the
+ * run is not spotlight-grounded) — passed in so the returned `done` meta carries
+ * the same `groundingMeta` the primary success path would.
+ */
+export declare function createAttemptRepair(deps: AttemptRepairDeps): (step: RepairStep, original: CandidateRef, originalSystemPrompt: string, invalidText: string, errors: readonly string[], injectedSources: readonly SearchResultItem[] | null, originalUserPrompt?: string) => Promise<RepairAttemptOutcome | null>;
+//# sourceMappingURL=repair-attempt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repair-attempt.d.ts","sourceRoot":"","sources":["../../src/run/repair-attempt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAG3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;oEACoE;AACpE,eAAO,MAAM,gBAAgB,sFAAsF,CAAC;AAEpH;;;;8EAI8E;AAC9E,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,EAAE,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAE3G;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;CAClF;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxD,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,CAAC;IAC9D,QAAQ,CAAC,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,KAAK,KAAK,CAAC;CACtH;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,iBAAiB,GACtB,CACD,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,YAAY,EACtB,oBAAoB,EAAE,MAAM,EAC5B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,eAAe,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,EACnD,kBAAkB,CAAC,EAAE,MAAM,KACxB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA0KxC"}