modelrig 0.10.0 → 0.11.1

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

@@ -65,14 +65,14 @@ MODELRIG_API_KEY=rig_sk_…
 <!-- /BLOCK:KEY -->
 
 <!-- BLOCK:CONFIRM_ORG -->
-**Confirm the org before you trust an empty console.** Run `modelrig doctor` from the same environment your app runs in. It asks GET /v1/whoami which organization the key belongs to, and the name it prints must match the org badge in the console header. If it names a different organization, your data is landing there: switch the console to that organization, or mint a key in the one you meant (https://modelrig.dev/orgs-and-keys.html).
+**Confirm the org before you trust an empty console.** Run `modelrig doctor` from the same environment your app runs in, once your app has started with the key. It asks GET /v1/whoami which organization the key belongs to and prints the org's name and, in parentheses, its slug; the name must match the org badge in the console header. If it names a different organization, your data is landing there: switch the console to that organization, or mint a key in the one you meant (https://modelrig.dev/orgs-and-keys.html).
 
 ```bash
 npx modelrig doctor
-# [modelrig] key rig_sk_…AbCd → org «Your Org» ✓  (ingest https://api.modelrig.ai, …)
+# [modelrig] key rig_sk_…AbCd → org «Your Org» (your-org) ✓  (ingest https://api.modelrig.ai, …)
 
-# No CLI in that environment? Ask the API directly:
-curl -H "Authorization: Bearer $MODELRIG_API_KEY" https://api.modelrig.ai/v1/whoami
+# No CLI in that environment? Ask the API directly (same host the SDK uses):
+curl -H "Authorization: Bearer $MODELRIG_API_KEY" "${MODELRIG_INGEST_URL:-https://api.modelrig.ai}/v1/whoami"
 ```
 <!-- /BLOCK:CONFIRM_ORG -->
 
@@ -109,9 +109,107 @@ 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, an embedding): record it right after it returns, never leave it invisible (https://modelrig.dev/not-captured.html):
+
+<!-- BLOCK:RECORD_CALL -->
+**Record a call your code makes itself.** A provider call your code makes directly (a client ModelRig has no lane for, a stream you read yourself, an embedding, a fallback) is invisible until you report it. Call `rig.recordCall` right after it returns, inside the run, with the tokens the provider reported: the call shows on /inferences as "recorded · unverified", joins its run and step, and counts toward cost. It is synchronous and never throws; invalid input warns once and records nothing (`inferenceId: null`). Spread optional fields only when the provider reported them, so the call type-checks under `exactOptionalPropertyTypes`.
+
+```ts
+const started = Date.now();
+const resp = await genai.models.generateContent({ model: "gemini-3.1-pro-preview", contents });
+const u = resp.usageMetadata;
+const finishReason = resp.candidates?.[0]?.finishReason;
+
+const rec = rig.recordCall({
+  provider: "gemini",
+  model: "gemini-3.1-pro-preview",
+  usage: {
+    tokensIn: u?.promptTokenCount ?? 0, // total input, cached included
+    tokensOut: (u?.candidatesTokenCount ?? 0) + (u?.thoughtsTokenCount ?? 0),
+    tokensCached: u?.cachedContentTokenCount ?? 0,
+    // optional fields: spread only when the provider reported them
+    ...(u?.thoughtsTokenCount !== undefined ? { reasoningTokens: u.thoughtsTokenCount } : {}),
+  },
+  servedTier: "standard", // the tier that SERVED the call: pass what the provider reports (flex, priority); it is priced at that tier
+  latencyMs: Date.now() - started,
+  stepKey: "summarize", // the step on /runs (inside run.scope / run.start)
+  ...(finishReason !== undefined ? { finishReason } : {}),
+});
+if (rec.inferenceId !== null) rig.grade({ kind: "inference", id: rec.inferenceId }, { score: 1, kind: "deterministic" });
+```
+<!-- /BLOCK:RECORD_CALL -->
+
+No routes yet (observe, or a `runRaw` seam)? Build the rig raw-only:
+
+<!-- BLOCK:RAW_RIG -->
+**No routes yet? Build the rig raw-only.** Observing a pipeline, or recording calls your code makes itself, needs no route files. Construct the rig with `routesDir: null`: `rig.runRaw`, `rig.runRawStream` and `rig.recordCall` work at once, and `rig.run` / `rig.runBundle` refuse with a teaching error until you add routes. Without it, createRig loads ./modelrig/routes: a directory you configured that is missing throws, and a missing default directory falls back to raw-only with a one-line warning.
+
+```ts
+import { createRig, loadConfigFromEnv } from "modelrig";
+
+// Raw-only on purpose: no route files needed. rig.runRaw, rig.runRawStream and
+// rig.recordCall work; rig.run needs routes (add them later, drop routesDir: null).
+const rig = createRig({ ...loadConfigFromEnv(), routesDir: null });
+```
+<!-- /BLOCK:RAW_RIG -->
+
+Grade from a signal you already have, and prove a cheaper model on your own traffic:
+
+<!-- BLOCK:GRADE_RUN -->
+**Attach a grade to a call or a whole run.** A grade is your judgment: a 0–1 score with an optional comment, from a validator, a downstream accept/reject, a human or a model. Grade one call by its inference id (`result.meta.inferenceId`, or the `inferenceId` rig.recordCall returns). Grade a whole run by its run id, `run.runId` on the handle `run.start` returns: that grade shows on the run page and on /projects. A run grade whose id is the run's `episodeKey` also shows, on the run page only. `run_id` is a reserved tag the SDK stamps, not a variable your code has. A grade whose id matches no call or run attaches to nothing. The write is synchronous and local and never throws into your pipeline.
+
+```ts
+const run = rig.artifacts.run.start({ pipeline: "support", episodeKey: ticketId, environment: "production" });
+const result = await rig.run("example.support_summarize", {
+  input: { ticket, product, priorContext },
+  tags: { subject: customer },
+  stepKey: "summarize",
+});
+run.end("succeeded");
+
+// one call: the inference id rides on every result
+rig.grade({ kind: "inference", id: result.meta.inferenceId }, { score: 1, kind: "deterministic", grader: "schema-check" });
+// the whole run: its id is run.runId from run.start (shows on the run page and on /projects)
+rig.grade({ kind: "run", id: run.runId }, { score: 0, kind: "human", comment: "missed the refund request" });
+```
+<!-- /BLOCK:GRADE_RUN -->
+
+<!-- BLOCK:BAKEOFF -->
+**Prove a cheaper model on your own traffic.** A bake-off replays your own inputs through the variants a route declares and reports the effective cost of conformance for each. `--variants` names entries in the route's `variants:` block (`default` is the route as declared), never model ids, and a variant can only narrow the route's candidates. Set `capture: true` first: replay works on traffic captured after that, not before. With no captured traffic (a run-based pipeline), promote a real /runs output to a golden (the console's make golden, or `promoteToEval`) and use `--from-eval-cases <task>`; its variants come from the route bundle named after the task. A bake-off measures and never switches anything.
+
+```bash
+# 1. in modelrig/routes/example.support_summarize.yaml: capture traffic, and declare
+#    a cheaper variant (narrowing only: its candidates must be in the route's list)
+capture: true
+variants:
+  - name: cheap
+    candidates:
+      - provider: gemini
+        model: gemini-3.1-flash-lite
+
+# 2. after traffic accumulates, compare the route as declared (default) with cheap
+npx modelrig bakeoff --route example.support_summarize --variants default,cheap --replay-last 50
+
+# no captured route traffic? promote a real /runs output to a golden, then
+npx modelrig bakeoff --from-eval-cases example.support_summarize --variants default,cheap
+```
+<!-- /BLOCK:BAKEOFF -->
+
+On a hosted worker, pin the org a deployment must export to:
+
+<!-- BLOCK:EXPECT_ORG -->
+**Pin the org a deployment must export to.** `--expect-org` and `expectOrg` take the org's slug, not its display name. `modelrig doctor` prints both, as `→ org «Your Org» (your-org) ✓`: the slug is the part in parentheses. In the console, hover the org badge in the header to see it. With `--expect-org <slug>`, doctor exits non-zero when the key belongs to another org, so a deploy check fails loudly instead of exporting somewhere else.
+
+```ts
+// The same check in code: the exporter asks whoami on its first flush and logs
+// ORG MISMATCH on every flush while the key belongs to another org.
+const rig = createRig({ ...loadConfigFromEnv(), expectOrg: "your-org" });
+```
+<!-- /BLOCK:EXPECT_ORG -->
+
 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>.
@@ -120,11 +218,12 @@ Which lane fits a codebase (observe, the `runRaw` seam, or named routes):
 
 Before migrating anything, you can just **watch** an existing pipeline. ModelRig
 records each run as a run → step → artifact chain you click through in the
-console — no routes moved, no model calls rerouted, and with the flag off the
+console — no routes moved, no model calls rerouted, and with no key set the
 pipeline behaves byte-for-byte as before. Scaffold it:
 `npx modelrig observe [path] --scope <one pipeline>` writes a self-contained
-`record-step` seam and an `OBSERVE.md` whose wiring is emitted as diffs you
-apply. The instrumentation is a code-level SDK seam (no zero-code observe), but
+`record-step` seam (a raw-only rig, `routesDir: null`, that reports each call
+with `rig.recordCall` so steps carry a cost) and an `OBSERVE.md` whose wiring,
+including `environment` on the run, is emitted as diffs you apply. The instrumentation is a code-level SDK seam (no zero-code observe), but
 you no longer hand-write it — see <https://modelrig.dev/instrumentation.html>.
 The namespace is **on by default once a control plane is configured** (a
 `rig_sk_` API key, or the self-host Supabase pair); a pure local-only rig stays
@@ -148,8 +247,8 @@ behaviour-affecting, so the agent *proposes* it, proves it with
 never the skill's job.
 
 **Runs are the standard path, not an appendix.** Every pipeline execution should
-be a **run**: wrap it in `rig.artifacts.run.start` / `run.scope`, name one step
-per model-call family (pass `stepKey`), `artifact.save` the work products, and tag
+be a **run**: wrap it in `rig.artifacts.run.start` / `run.scope`, name each
+model call's step with `stepKey`, `artifact.save` the work products, and tag
 `subject` / `feature`. Inside a run context the SDK auto-stamps `tags.run_id` and
 `tags.step` for you, so the run fills `/runs` **and** `/projects`; acceptance is
 the run appearing on `/runs` with its steps. `run_id` is reserved: never set it