modelrig 0.10.0 → 0.11.0

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

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

package/dist/run/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/telemetry/attempt-meta.d.ts

@@ -124,7 +124,15 @@ export interface AttemptMetaV1 {
     /** QA-S7 (issue #1, plan §7.3): the route's output contract on this attempt —
      * `json` | `text`. Route lane only; absent on raw rows. */
     readonly output_kind?: OutputKind;
+    /** OBS-1: where this row's numbers came from. `caller-reported` ⇒ the
+     * customer's own code made the provider call and reported its usage through
+     * `rig.recordCall()`; ModelRig neither dispatched nor validated it. Absent ⇒
+     * ModelRig dispatched the attempt and measured it (every other row). Additive
+     * — no version bump. */
+    readonly provenance?: AttemptProvenance;
 }
+/** OBS-1: the one non-default provenance value (see {@link AttemptMetaV1.provenance}). */
+export type AttemptProvenance = "caller-reported";
 export interface RunMetaV1 {
     readonly v: 1;
     readonly pipeline_sha?: string;
@@ -194,6 +202,9 @@ export interface AttemptMetaInputs {
      * through verbatim (already counts/enums/hashes — no free text). Absent ⇒ no
      * `screen` key ⇒ byte-identical to a non-screened row. */
     readonly screen?: ScreenReceipt;
+    /** OBS-1: stamp `meta.provenance` (`rig.recordCall` rows only). Absent ⇒ no
+     * key ⇒ byte-identical to every dispatched row. */
+    readonly provenance?: AttemptProvenance;
 }
 /** The classification-rule string test (spec §2, §5 wire backstop): a value is
  * an ENUM / IDENTIFIER / HASH only if it is at most 128 chars AND contains no

package/dist/telemetry/attempt-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attempt-meta.d.ts","sourceRoot":"","sources":["../../src/telemetry/attempt-meta.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"attempt-meta.d.ts","sourceRoot":"","sources":["../../src/telemetry/attempt-meta.ts"],"names":[],"mappings":"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"}

package/dist/telemetry/attempt-meta.js

@@ -270,6 +270,9 @@ function summarizeAttemptMeta(inputs) {
         if (typeof inputs.outputKind === "string" && exports.OUTPUT_KINDS.has(inputs.outputKind)) {
             meta.output_kind = inputs.outputKind;
         }
+        // OBS-1: caller-reported provenance — an enum; anything else is dropped.
+        if (inputs.provenance === "caller-reported")
+            meta.provenance = inputs.provenance;
         // Externally-sourced identifiers — gated by the classification rule.
         if (isMetaSafeString(a.model_snapshot))
             meta.model_snapshot = a.model_snapshot;

package/dist/telemetry/lanes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The ONE lane classifier every read surface uses (OBS-1). A telemetry row's
+ * `tags.lane` names how ModelRig came to hold it:
+ *   • absent / anything else — a ROUTED call (it walked a route's ladder; its
+ *     quality signal is schema conformance).
+ *   • `"raw"`      — a raw-lane BYOK passthrough ModelRig dispatched but never
+ *     validated (`rig.runRaw`).
+ *   • `"external"` — a RECORDED call: the customer's own code made it and
+ *     reported it through `rig.recordCall`; ModelRig neither dispatched nor
+ *     validated it.
+ * Raw and external rows are never routed: they never enter ladder or
+ * conformance math, and their quality signal is `rig.grade`.
+ *
+ * Pure, dependency-free (the console imports it through `@modelrig-core`).
+ * The billing path (`modelrig-server` usage-aggregation `laneOf`) deliberately
+ * keeps its own literal so a money decision imports nothing from here.
+ */
+export declare const RAW_LANE = "raw";
+export declare const EXTERNAL_LANE = "external";
+/** The call lane a read surface renders. */
+export type CallLane = "routes" | "raw" | "external";
+/** True when a row with this `tags.lane` walked a route (enters ladder and
+ * conformance math). False for `raw` and `external`. */
+export declare function isRoutedLane(lane: unknown): boolean;
+/** Three-way classification of a `tags.lane` value. */
+export declare function callLaneOf(lane: unknown): CallLane;
+/** Console badge copy for a recorded (external) call. User-facing copy says
+ * "recorded call", never "lane". */
+export declare const RECORDED_BADGE = "recorded \u00B7 unverified";
+export declare const RECORDED_TOOLTIP = "Your code made this call; ModelRig recorded what you reported (tokens, tier, latency). It did not dispatch or validate it.";
+//# sourceMappingURL=lanes.d.ts.map

package/dist/telemetry/lanes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lanes.d.ts","sourceRoot":"","sources":["../../src/telemetry/lanes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAC9B,eAAO,MAAM,aAAa,aAAa,CAAC;AAExC,4CAA4C;AAC5C,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;AAErD;wDACwD;AACxD,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAEnD;AAED,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAIlD;AAED;oCACoC;AACpC,eAAO,MAAM,cAAc,+BAA0B,CAAC;AACtD,eAAO,MAAM,gBAAgB,+HACiG,CAAC"}

package/dist/telemetry/lanes.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * The ONE lane classifier every read surface uses (OBS-1). A telemetry row's
+ * `tags.lane` names how ModelRig came to hold it:
+ *   • absent / anything else — a ROUTED call (it walked a route's ladder; its
+ *     quality signal is schema conformance).
+ *   • `"raw"`      — a raw-lane BYOK passthrough ModelRig dispatched but never
+ *     validated (`rig.runRaw`).
+ *   • `"external"` — a RECORDED call: the customer's own code made it and
+ *     reported it through `rig.recordCall`; ModelRig neither dispatched nor
+ *     validated it.
+ * Raw and external rows are never routed: they never enter ladder or
+ * conformance math, and their quality signal is `rig.grade`.
+ *
+ * Pure, dependency-free (the console imports it through `@modelrig-core`).
+ * The billing path (`modelrig-server` usage-aggregation `laneOf`) deliberately
+ * keeps its own literal so a money decision imports nothing from here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECORDED_TOOLTIP = exports.RECORDED_BADGE = exports.EXTERNAL_LANE = exports.RAW_LANE = void 0;
+exports.isRoutedLane = isRoutedLane;
+exports.callLaneOf = callLaneOf;
+exports.RAW_LANE = "raw";
+exports.EXTERNAL_LANE = "external";
+/** True when a row with this `tags.lane` walked a route (enters ladder and
+ * conformance math). False for `raw` and `external`. */
+function isRoutedLane(lane) {
+    return lane !== exports.RAW_LANE && lane !== exports.EXTERNAL_LANE;
+}
+/** Three-way classification of a `tags.lane` value. */
+function callLaneOf(lane) {
+    if (lane === exports.RAW_LANE)
+        return "raw";
+    if (lane === exports.EXTERNAL_LANE)
+        return "external";
+    return "routes";
+}
+/** Console badge copy for a recorded (external) call. User-facing copy says
+ * "recorded call", never "lane". */
+exports.RECORDED_BADGE = "recorded · unverified";
+exports.RECORDED_TOOLTIP = "Your code made this call; ModelRig recorded what you reported (tokens, tier, latency). It did not dispatch or validate it.";

package/dist/telemetry/org-identity.d.ts

@@ -33,8 +33,11 @@ export interface OrgIdentityInput {
     /** Override WHOAMI_TIMEOUT_MS (tests). */
     readonly timeoutMs?: number;
 }
-/** Build the one-line org banner from a successful whoami. */
-export declare function formatOrgLine(result: PreflightResult, apiKey: string): string;
+/** Build the one-line org banner from a successful whoami. Only an ok result
+ * reaches here, and an ok result always NAMES its org (QA N14: a 2xx without
+ * one is not ok), so `orgName` is required. Never prints a placeholder glyph:
+ * the slug is shown only when the server sent one that differs from the name. */
+export declare function formatOrgLine(orgName: string, result: PreflightResult, apiKey: string): string;
 /**
  * Record one successful flush. Returns immediately; the whoami (first flush
  * only) runs in the background. Exposed as a promise-returning helper ONLY so

package/dist/telemetry/org-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"org-identity.d.ts","sourceRoot":"","sources":["../../src/telemetry/org-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAwC,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGjG;oEACoE;AACpE,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAYtC,kFAAkF;AAClF,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC;IAC/B,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAO7E;AAgBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B1E"}
+{"version":3,"file":"org-identity.d.ts","sourceRoot":"","sources":["../../src/telemetry/org-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAwC,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGjG;oEACoE;AACpE,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAYtC,kFAAkF;AAClF,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC;IAC/B,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;iFAGiF;AACjF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAM9F;AAgBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B1E"}

package/dist/telemetry/org-identity.js

@@ -36,14 +36,16 @@ const states = new Map();
 function __resetOrgIdentityForTest() {
     states.clear();
 }
-/** Build the one-line org banner from a successful whoami. */
-function formatOrgLine(result, apiKey) {
-    const org = result.whoami?.org ?? null;
-    const name = org?.name ?? org?.id ?? "?";
-    const slug = org?.slug ?? "?";
+/** Build the one-line org banner from a successful whoami. Only an ok result
+ * reaches here, and an ok result always NAMES its org (QA N14: a 2xx without
+ * one is not ok), so `orgName` is required. Never prints a placeholder glyph:
+ * the slug is shown only when the server sent one that differs from the name. */
+function formatOrgLine(orgName, result, apiKey) {
+    const slugRaw = result.whoami?.org?.slug;
+    const slug = typeof slugRaw === "string" && slugRaw !== "" && slugRaw !== orgName ? ` (${slugRaw})` : "";
     const keyName = result.whoami?.key?.name;
     const keyLabel = typeof keyName === "string" && keyName !== "" ? `«${keyName}» ` : "";
-    return `[modelrig] exporting to org «${name}» (${slug}) as key ${keyLabel}${(0, api_key_format_1.redactApiKey)(apiKey)}`;
+    return `[modelrig] exporting to org «${orgName}»${slug} as key ${keyLabel}${(0, api_key_format_1.redactApiKey)(apiKey)}`;
 }
 function mismatchLine(actual, expectOrg) {
     return (`[modelrig] ORG MISMATCH: key resolves to «${actual}», expectOrg is «${expectOrg}» — ` +
@@ -81,10 +83,10 @@ function noteSuccessfulFlush(input) {
     if (s.flushes === 1) {
         return (0, doctor_preflight_1.whoamiPreflight)(input.ingestUrl, input.apiKey, input.fetchFn, AbortSignal.timeout(input.timeoutMs ?? exports.WHOAMI_TIMEOUT_MS))
             .then((result) => {
-            if (!result.ok)
+            if (!result.ok || result.orgName === undefined)
                 return; // silent: a 401 has its own loud line
             s.resolved = result;
-            console.log(formatOrgLine(result, input.apiKey));
+            console.log(formatOrgLine(result.orgName, result, input.apiKey));
             warnIfMismatch(result, input.expectOrg);
         })
             .catch(() => {

package/docs/agent-skill/SKILL.md

@@ -109,9 +109,11 @@ await rig.close(); // flushes the exporter — call once at shutdown
 <!-- /BLOCK:RUN_WRAP -->
 
 <!-- BLOCK:NOT_CAPTURED -->
-**What ModelRig does not see.** ModelRig records the calls your code makes through the SDK (`rig.run`, `rig.runBundle`, `rig.runRaw`, `rig.runRawStream`) or the gateway, and nothing else. Five things stay invisible or unattached: (1) direct provider SDK calls, with or without a JSON schema; (2) streams you read from a provider client yourself; (3) a fallback your code makes after the raw lane refuses a `responseSchema` it cannot enforce (deepseek, deepinfra, fireworks and zai fail closed with `invariant_violation`); (4) calls made outside `run.scope` / `run.start`, which land on /inferences but on no run; (5) embeddings. Details and the console tells: https://modelrig.dev/not-captured.html.
+**What ModelRig does not see unless you record it.** ModelRig records the calls your code makes through the SDK (`rig.run`, `rig.runBundle`, `rig.runRaw`, `rig.runRawStream`) or the gateway, plus any call your code makes itself and reports with `rig.recordCall`. Nothing else is seen. Five things stay invisible or unattached unless you record them: (1) direct provider SDK calls, with or without a JSON schema; (2) streams you read from a provider client yourself; (3) a fallback your code makes after the raw lane refuses a `responseSchema` it cannot enforce (deepseek, deepinfra, fireworks and zai fail closed with `invariant_violation`); (4) calls made outside `run.scope` / `run.start`, which land on /inferences but on no run; (5) embeddings. A recorded call shows as "recorded · unverified": ModelRig neither dispatched nor validated it, and its tokens are the numbers you reported. Details and the console tells: https://modelrig.dev/not-captured.html.
 <!-- /BLOCK:NOT_CAPTURED -->
 
+A provider call you can't move onto a lane (an unsupported client, a stream you read yourself, a fallback): record it with `rig.recordCall({ provider, model, usage, servedTier, latencyMs, stepKey })` right after it returns, never leave it invisible (modelrig ≥ 0.11.0; https://modelrig.dev/not-captured.html).
+
 Which lane fits a codebase (observe, the `runRaw` seam, or named routes):
 <https://modelrig.dev/choosing-a-lane.html>. Hosted workers:
 <https://modelrig.dev/deploying.html>.

package/docs/instrumentation.md

@@ -115,6 +115,23 @@ right for one run at a time on a request/async path.
   and honest. Never route a stage through the rig just to mint a step row; the
   console renders "cost n/a" for un-routed steps rather than inventing a number.
 
+### Record a call your code made itself (`rig.recordCall`)
+
+_Needs `modelrig` 0.11.0 or newer._
+
+If a stage's model call has to stay a direct provider call, report it instead:
+`rig.recordCall({ provider, model, usage: { tokensIn, tokensOut, tokensCached }, servedTier, latencyMs, stepKey })`
+right after the call returns. Inside a run context it records a step row for
+that `stepKey` (stored as `ground-truth`, the only joined-inference value),
+joined to the recorded inference, so the step gets a cost instead of "cost n/a".
+The console shows that step and its call as **recorded · unverified**, never as
+measured:
+ModelRig neither dispatched nor validated the call, and the tokens are the ones
+you reported. It is synchronous and never throws (bad input warns and returns
+`inferenceId: null`); the returned `inferenceId` is gradeable with `rig.grade`.
+Full contract, usage convention and cost notes:
+[Not captured → record them](not-captured.md#calls-your-code-makes-itself-record-them).
+
 ## Tags, dimensions, and the graph
 
 ModelRig has **two** grouping mechanisms, and they compose: