modelrig 0.0.1 → 0.1.0

package/dist/tenancy/api-key-format.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * The `rig_sk_` key FORMAT — Phase 6 WS2.
+ *
+ * Shared knowledge, deliberately: the SDK builds the header that presents a
+ * key, modelrig-server resolves one, and the oracle decides whether the value
+ * it was handed is a key at all. Three packages agreeing on a prefix by
+ * copying a string literal is how N1's "one name per concept" fails in
+ * practice, so the string lives here and they all import it.
+ *
+ * What is NOT here is MINTING. Generating a secret and writing its hash is the
+ * control plane's job; an SDK that could do it would imply a client could
+ * issue itself a credential, which is the shape of the thing this scheme
+ * exists to prevent. `mintApiKey` lives in modelrig-server.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API_KEY_SCOPES = exports.API_KEY_BODY_MIN_LENGTH = exports.API_KEY_SECRET_BYTES = exports.API_KEY_PREFIX = void 0;
+exports.hashApiKeySecret = hashApiKeySecret;
+exports.looksLikeApiKey = looksLikeApiKey;
+exports.redactApiKey = redactApiKey;
+exports.parseScopes = parseScopes;
+exports.hasScope = hasScope;
+const node_crypto_1 = require("node:crypto");
+/**
+ * The one place this prefix is spelled. Grep-visible on purpose: the
+ * guardrails C2 rule keys off it, and so does the exporter's sink selection.
+ */
+exports.API_KEY_PREFIX = "rig_sk_";
+/** 32 bytes = 256 bits, as base64url. The minting side uses this to generate;
+ * this side uses its ENCODED length to recognise. See 00020's header for why
+ * that number carries the argument that a plain sha-256 at rest is sound. */
+exports.API_KEY_SECRET_BYTES = 32;
+/** base64url length of API_KEY_SECRET_BYTES — the minimum a real key's body has. */
+exports.API_KEY_BODY_MIN_LENGTH = 43;
+/**
+ * The granted authorities. Mirrors migration 00020's CHECK constraint — a
+ * test pins that the two agree, because a scope that exists here and not
+ * there is a key that cannot be written, and one that exists there and not
+ * here is an authority nothing enforces.
+ */
+exports.API_KEY_SCOPES = ["ingest", "query", "feedback", "decision", "oracle-act"];
+/** sha256 of the WHOLE presented string, prefix included — so a caller cannot
+ * strip the prefix and land on a different row. */
+function hashApiKeySecret(secret) {
+    return (0, node_crypto_1.createHash)("sha256").update(secret, "utf8").digest("hex");
+}
+/**
+ * Cheap shape check, used to decide which credential branch a bearer token
+ * takes before any I/O happens.
+ *
+ * The minimum body length matters: without it the bare string `rig_sk_` would
+ * take the api-key branch and cost a database round trip per garbage request,
+ * which is a free amplification primitive on an unauthenticated surface.
+ */
+function looksLikeApiKey(presented) {
+    if (!presented.startsWith(exports.API_KEY_PREFIX))
+        return false;
+    const body = presented.slice(exports.API_KEY_PREFIX.length);
+    return body.length >= exports.API_KEY_BODY_MIN_LENGTH && /^[A-Za-z0-9_-]+$/.test(body);
+}
+/**
+ * What a key may be called in a log line, an error, or a boot banner.
+ *
+ * Returns the placeholder form for a non-key so that a caller who reaches for
+ * this with the wrong variable prints nothing useful rather than printing the
+ * whole thing. C2's leak-gate is the belt; this is the braces.
+ */
+function redactApiKey(presented) {
+    const suffix = looksLikeApiKey(presented) ? presented.slice(-4) : "????";
+    return `${exports.API_KEY_PREFIX}…${suffix}`;
+}
+/**
+ * Narrow an untrusted scope list to the known set (T7: a jsonb/array column
+ * is not proof of shape — narrow at the boundary).
+ *
+ * Unknown entries are DROPPED, not rejected: a row written by a future
+ * migration with a scope this build predates should still authorize the
+ * scopes this build understands, rather than failing closed on everything.
+ * Returns declaration order so two equal grant sets compare equal.
+ */
+function parseScopes(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const present = new Set(raw.filter((s) => typeof s === "string"));
+    return exports.API_KEY_SCOPES.filter((scope) => present.has(scope));
+}
+/** An empty grant set authorizes nothing — stated as code so it cannot be
+ * accidentally re-derived as "no scopes means unrestricted". */
+function hasScope(granted, required) {
+    return granted.includes(required);
+}

package/dist/tenancy/constants.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tenancy constants — Phase 6 WS1.
+ *
+ * Last Verified: 2026-08-04 against migration
+ * `supabase/migrations/00012_orgs_projects_memberships.sql` (S4: schema truth
+ * is the migration file; never assume an id, read the seed).
+ */
+/**
+ * The org that owns everything predating accounts, and the org a
+ * single-tenant deployment writes into.
+ *
+ * A fixed sentinel rather than a random uuid so that policies, migrations and
+ * code can all name it without a lookup. Seeded by 00012; a partial unique
+ * index on `orgs (is_house) where is_house` makes a second one impossible.
+ *
+ * On a SELF-HOSTED control plane this is simply "the customer's org" — their
+ * database has exactly one, and everything belongs to it. On the hosted plane
+ * it is ours, and WS2's `/v1/ingest` never uses it: there, org and project are
+ * resolved from the api key and stamped explicitly (T3 — tenancy is derived
+ * from the principal, never defaulted).
+ */
+export declare const HOUSE_ORG_ID = "00000000-0000-4000-8000-000000000001";
+//# sourceMappingURL=constants.d.ts.map

package/dist/tenancy/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/tenancy/constants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,yCAAyC,CAAC"}

package/dist/tenancy/constants.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Tenancy constants — Phase 6 WS1.
+ *
+ * Last Verified: 2026-08-04 against migration
+ * `supabase/migrations/00012_orgs_projects_memberships.sql` (S4: schema truth
+ * is the migration file; never assume an id, read the seed).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOUSE_ORG_ID = void 0;
+/**
+ * The org that owns everything predating accounts, and the org a
+ * single-tenant deployment writes into.
+ *
+ * A fixed sentinel rather than a random uuid so that policies, migrations and
+ * code can all name it without a lookup. Seeded by 00012; a partial unique
+ * index on `orgs (is_house) where is_house` makes a second one impossible.
+ *
+ * On a SELF-HOSTED control plane this is simply "the customer's org" — their
+ * database has exactly one, and everything belongs to it. On the hosted plane
+ * it is ours, and WS2's `/v1/ingest` never uses it: there, org and project are
+ * resolved from the api key and stamped explicitly (T3 — tenancy is derived
+ * from the principal, never defaulted).
+ */
+exports.HOUSE_ORG_ID = "00000000-0000-4000-8000-000000000001";

package/dist/tenancy/scrub.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The one secret-scrubber every emission boundary shares — C2's leak gate.
+ *
+ * ── WHY THIS MOVED HERE (WS3) ────────────────────────────────────────────
+ * `scrubSecrets` was born in `watch/run-record.ts`, scoped to the six
+ * INFRASTRUCTURE prefixes a failing cron might spill (`sk_live_`, `whsec_`,
+ * `rnd_`, a Supabase JWT). WS3 changed the threat model: the BYOK vault now
+ * decrypts CUSTOMER PROVIDER keys into data-plane memory at call time, and a
+ * decrypted key that reaches an error message, a telemetry row, an export, or
+ * a log line is precisely the leak the vault exists to prevent. So the scrubber
+ * is promoted to shared, its prefix set widened to every provider family we
+ * might hold, and it is exported from the package so the server and the SDK run
+ * the SAME gate rather than two that drift.
+ *
+ * ── PREFIX-BASED, NOT ENTROPY-BASED, ON PURPOSE ──────────────────────────
+ * A high-entropy heuristic ("looks random enough") redacts request ids, git
+ * shas, and base64 payloads — and a scrubber that eats legitimate text gets
+ * muted within a week, which is worse than none. Anchoring on known credential
+ * prefixes matches a real key and almost nothing else. The cost is that a
+ * provider inventing a brand-new prefix is invisible until added here; that is
+ * a one-line change and the correct trade.
+ *
+ * ── A NAME IS NOT A LEAK ─────────────────────────────────────────────────
+ * These patterns match secret VALUES, never their variable names. The string
+ * `MODELRIG_SUPABASE_SERVICE_ROLE_KEY` in an error is a name and stays; only a
+ * value carrying a live prefix is redacted. `publish-safety.test.ts` relies on
+ * the same distinction.
+ */
+/**
+ * Credential prefixes that mark a key-shaped VALUE. Grep-visible on purpose —
+ * `scripts/guardrails.ts` (C2) and this module are the two places the set is
+ * spelled, and a test pins that the vault's provider families all appear here.
+ *
+ * Order does not matter; each is tried independently.
+ */
+export declare const KEY_SHAPED_PREFIXES: readonly string[];
+/**
+ * Replace every key-shaped substring with `[redacted]`, leaving all other text
+ * intact. Safe to run on any string headed out of the process — failure
+ * messages, telemetry notes, export rows, log lines.
+ */
+export declare function scrubSecrets(text: string): string;
+/** True if the text contains anything key-shaped. The predicate behind the
+ * build-failing leak-gate test — cheaper to read than a diff of scrubbed vs
+ * original, and it says what it means. */
+export declare function containsKeyShapedString(text: string): boolean;
+//# sourceMappingURL=scrub.d.ts.map

package/dist/tenancy/scrub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrub.d.ts","sourceRoot":"","sources":["../../src/tenancy/scrub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAiBhD,CAAC;AAkBF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;0CAE0C;AAC1C,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D"}

package/dist/tenancy/scrub.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * The one secret-scrubber every emission boundary shares — C2's leak gate.
+ *
+ * ── WHY THIS MOVED HERE (WS3) ────────────────────────────────────────────
+ * `scrubSecrets` was born in `watch/run-record.ts`, scoped to the six
+ * INFRASTRUCTURE prefixes a failing cron might spill (`sk_live_`, `whsec_`,
+ * `rnd_`, a Supabase JWT). WS3 changed the threat model: the BYOK vault now
+ * decrypts CUSTOMER PROVIDER keys into data-plane memory at call time, and a
+ * decrypted key that reaches an error message, a telemetry row, an export, or
+ * a log line is precisely the leak the vault exists to prevent. So the scrubber
+ * is promoted to shared, its prefix set widened to every provider family we
+ * might hold, and it is exported from the package so the server and the SDK run
+ * the SAME gate rather than two that drift.
+ *
+ * ── PREFIX-BASED, NOT ENTROPY-BASED, ON PURPOSE ──────────────────────────
+ * A high-entropy heuristic ("looks random enough") redacts request ids, git
+ * shas, and base64 payloads — and a scrubber that eats legitimate text gets
+ * muted within a week, which is worse than none. Anchoring on known credential
+ * prefixes matches a real key and almost nothing else. The cost is that a
+ * provider inventing a brand-new prefix is invisible until added here; that is
+ * a one-line change and the correct trade.
+ *
+ * ── A NAME IS NOT A LEAK ─────────────────────────────────────────────────
+ * These patterns match secret VALUES, never their variable names. The string
+ * `MODELRIG_SUPABASE_SERVICE_ROLE_KEY` in an error is a name and stays; only a
+ * value carrying a live prefix is redacted. `publish-safety.test.ts` relies on
+ * the same distinction.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEY_SHAPED_PREFIXES = void 0;
+exports.scrubSecrets = scrubSecrets;
+exports.containsKeyShapedString = containsKeyShapedString;
+/**
+ * Credential prefixes that mark a key-shaped VALUE. Grep-visible on purpose —
+ * `scripts/guardrails.ts` (C2) and this module are the two places the set is
+ * spelled, and a test pins that the vault's provider families all appear here.
+ *
+ * Order does not matter; each is tried independently.
+ */
+exports.KEY_SHAPED_PREFIXES = [
+    // Provider keys the BYOK vault can hold (signup-auth-boundary §BYOK).
+    "sk-", // OpenAI, Anthropic (sk-ant-), DeepSeek, most openai-compat
+    "AIza", // Google / Gemini
+    "xai-", // xAI / Grok
+    "fw_", // Fireworks
+    "tvly-", // Tavily
+    // ModelRig's own machine credential.
+    "rig_sk_",
+    // Platform / infrastructure secrets (the original run-record set).
+    "sk_live_",
+    "sk_test_",
+    "rk_live_", // Stripe restricted keys
+    "rk_test_",
+    "whsec_", // Stripe webhook signing
+    "rnd_", // Render API
+    "eyJ", // JWT (Supabase publishable / service-role) — base64url header
+];
+/** The body that must follow a prefix for it to count as a key: at least eight
+ * of the characters a base64url/hex secret is made of. Keeps `sk-` from eating
+ * the word "sk-" in prose while catching every real key, which is long. */
+const KEY_BODY = "[A-Za-z0-9_\\-.]{8,}";
+function escape(prefix) {
+    return prefix.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&");
+}
+/** One combined pattern, rebuilt per call (regex objects carry `lastIndex`
+ * state with the `g` flag, so a shared instance is a footgun across callers). */
+function keyPattern() {
+    const alt = exports.KEY_SHAPED_PREFIXES.map((p) => escape(p) + KEY_BODY).join("|");
+    return new RegExp(alt, "g");
+}
+/**
+ * Replace every key-shaped substring with `[redacted]`, leaving all other text
+ * intact. Safe to run on any string headed out of the process — failure
+ * messages, telemetry notes, export rows, log lines.
+ */
+function scrubSecrets(text) {
+    return text.replace(keyPattern(), "[redacted]");
+}
+/** True if the text contains anything key-shaped. The predicate behind the
+ * build-failing leak-gate test — cheaper to read than a diff of scrubbed vs
+ * original, and it says what it means. */
+function containsKeyShapedString(text) {
+    return keyPattern().test(text);
+}

package/dist/types/failures-teaching.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Errors that teach — Phase 5 WS3.
+ *
+ * ONE table, not prose scattered across call sites. Every failure class here
+ * answers three questions in the order a stuck engineer asks them:
+ *
+ *   1. what happened?          → `what` (plain language, no jargon-first)
+ *   2. what do I do about it?  → `fixHint` (an action, not a diagnosis)
+ *   3. where do I read more?   → `docsUrl` (a deep link, not a homepage)
+ *
+ * And where the fix is MECHANICAL, a fourth: `suggestedChange` — a
+ * JSON-patch-shaped hint a coding agent can apply without inventing
+ * anything. Only classes whose remedy is genuinely a config edit carry one;
+ * inventing a patch for "the model refused" would be worse than silence.
+ *
+ * The completeness test in failures-teaching.test.ts fails the build if a
+ * new FailureClass is added without an entry here, so this table cannot
+ * silently fall behind the taxonomy.
+ */
+import type { FailureClass, RigFailure } from "./failures";
+/** A JSON-Patch-shaped edit (RFC 6902 subset) against the route bundle. */
+export interface SuggestedChange {
+    readonly op: "add" | "replace" | "remove";
+    /** JSON Pointer into the route bundle YAML, e.g. "/policy/retries/network". */
+    readonly path: string;
+    readonly value?: unknown;
+    /** Why this edit is the right one — shown beside the diff. */
+    readonly because: string;
+}
+export interface FailureTeaching {
+    readonly class: FailureClass;
+    /** One sentence: what this class MEANS, in the reader's terms. */
+    readonly what: string;
+    /** The default action to take. Overridden by a failure's own fixHint when
+     * the site knows something more specific (a provider name, a model). */
+    readonly fixHint: string;
+    readonly docsUrl: string;
+    /** Build a mechanical edit for this failure, when one exists. */
+    readonly suggestedChange?: (failure: RigFailure) => SuggestedChange | null;
+}
+export declare const FAILURE_TEACHING: Readonly<Record<FailureClass, FailureTeaching>>;
+/** The rendered teaching for one failure: the site's own fixHint wins when
+ * it has one (it knows the provider and model), the table fills the rest. */
+export interface TeachableFailure {
+    readonly class: FailureClass;
+    readonly message: string;
+    readonly what: string;
+    readonly fixHint: string;
+    readonly docsUrl: string;
+    readonly suggestedChange: SuggestedChange | null;
+}
+export declare function teach(failure: RigFailure): TeachableFailure;
+/** Terminal-friendly rendering — used by the CLI. Kept here so the CLI and
+ * the server cannot drift into two different-looking errors. */
+export declare function renderFailureForTerminal(failure: RigFailure): string;
+//# sourceMappingURL=failures-teaching.d.ts.map

package/dist/types/failures-teaching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failures-teaching.d.ts","sourceRoot":"","sources":["../../src/types/failures-teaching.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3D,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;4EACwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,eAAe,GAAG,IAAI,CAAC;CAC5E;AAID,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,CA+I5E,CAAC;AAiBF;6EAC6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,eAAe,GAAG,IAAI,CAAC;CAClD;AAED,wBAAgB,KAAK,CAAC,OAAO,EAAE,UAAU,GAAG,gBAAgB,CAU3D;AAED;gEACgE;AAChE,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAapE"}

package/dist/types/failures-teaching.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * Errors that teach — Phase 5 WS3.
+ *
+ * ONE table, not prose scattered across call sites. Every failure class here
+ * answers three questions in the order a stuck engineer asks them:
+ *
+ *   1. what happened?          → `what` (plain language, no jargon-first)
+ *   2. what do I do about it?  → `fixHint` (an action, not a diagnosis)
+ *   3. where do I read more?   → `docsUrl` (a deep link, not a homepage)
+ *
+ * And where the fix is MECHANICAL, a fourth: `suggestedChange` — a
+ * JSON-patch-shaped hint a coding agent can apply without inventing
+ * anything. Only classes whose remedy is genuinely a config edit carry one;
+ * inventing a patch for "the model refused" would be worse than silence.
+ *
+ * The completeness test in failures-teaching.test.ts fails the build if a
+ * new FailureClass is added without an entry here, so this table cannot
+ * silently fall behind the taxonomy.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAILURE_TEACHING = void 0;
+exports.teach = teach;
+exports.renderFailureForTerminal = renderFailureForTerminal;
+const DOCS_BASE = "https://modelrig.dev/docs/failures";
+exports.FAILURE_TEACHING = {
+    content_invalid: {
+        class: "content_invalid",
+        what: "The model answered, but the answer did not match the schema your route requires — so it " +
+            "was rejected rather than passed downstream.",
+        fixHint: "Retry on this class is budgeted separately, so a flaky schema cannot eat your network " +
+            "retries. If it persists, the model likely cannot hold this shape: check the registry for " +
+            "a candidate with probed native structured output.",
+        docsUrl: `${DOCS_BASE}#content_invalid`,
+        // Mechanical: raise the content-retry budget. A repair rung is a bigger
+        // decision, so we suggest the small edit and name the bigger one in prose.
+        suggestedChange: () => ({
+            op: "replace",
+            path: "/policy/retries/content_invalid",
+            value: 3,
+            because: "A schema miss is usually transient at low retry counts; three attempts is the point " +
+                "past which the model is telling you it cannot hold this shape.",
+        }),
+    },
+    capacity_shed: {
+        class: "capacity_shed",
+        what: "The provider shed your request rather than serving it — a 429, a 503, or a flex-tier " +
+            "rejection. Nothing was wrong with the request.",
+        fixHint: "Capacity retries back off automatically. If it happens constantly, you are asking for " +
+            "discounted sheddable capacity during peak: move the route off the flex tier, or add a " +
+            "candidate on another provider so a shed on one does not stall the route.",
+        docsUrl: `${DOCS_BASE}#capacity_shed`,
+        suggestedChange: () => ({
+            op: "replace",
+            path: "/policy/tier",
+            value: "standard",
+            because: "Flex capacity is discounted because it is sheddable. If sheds are routine on this " +
+                "route, standard tier is the cheaper choice once retries are counted.",
+        }),
+    },
+    network: {
+        class: "network",
+        what: "The request never completed at the transport level — DNS, TLS, a dropped connection, or " +
+            "an error we could not classify any more precisely.",
+        fixHint: "These retry on their own budget. A persistent one is usually local: check egress, proxy " +
+            "settings, and whether the provider is up before changing anything in the route.",
+        docsUrl: `${DOCS_BASE}#network`,
+    },
+    refusal: {
+        class: "refusal",
+        what: "The model declined the task itself — this is an answer, not a fault.",
+        fixHint: "Retrying a refusal usually earns another refusal. Read the prompt as the model saw it: " +
+            "the input often contains something the model's policy will not touch. A different " +
+            "candidate may answer, but check the prompt first.",
+        docsUrl: `${DOCS_BASE}#refusal`,
+        // Deliberately no suggestedChange: no config edit fixes a refusal, and a
+        // patch that pretends otherwise would send someone down the wrong path.
+    },
+    cache_invalid: {
+        class: "cache_invalid",
+        what: "The provider-side cache or cached context this call relied on expired or was rejected, " +
+            "so the discount it was counting on is gone.",
+        fixHint: "Re-running usually repopulates the cache. If it recurs, your cached prefix is probably " +
+            "changing between calls — anything varying near the START of the prompt defeats prefix " +
+            "caching, so move volatile values to the end.",
+        docsUrl: `${DOCS_BASE}#cache_invalid`,
+    },
+    timeout: {
+        class: "timeout",
+        what: "The call passed the route's wall-clock deadline before the model finished.",
+        fixHint: "Either the deadline is too tight for this task or the model is slower than assumed. " +
+            "Check the latency column for this model before raising the timeout — a timeout raised to " +
+            "cover a slow model just makes a slow route.",
+        docsUrl: `${DOCS_BASE}#timeout`,
+        suggestedChange: () => ({
+            op: "replace",
+            path: "/policy/timeout_ms",
+            value: 300000,
+            because: "Long structured generations routinely exceed a 2-minute default. Five minutes is the " +
+                "ceiling used by the pipeline routes that produce full reports.",
+        }),
+    },
+    config_auth: {
+        class: "config_auth",
+        what: "The provider rejected the credentials, or there were none to send. This is never " +
+            "retried — retrying a dead key just spends time.",
+        fixHint: "Set the provider's API key in this environment. Until then the candidate is inert: the " +
+            "route still serves on its keyed candidates, and this one is skipped at dispatch.",
+        docsUrl: `${DOCS_BASE}#config_auth`,
+        // Mechanical only in the sense of naming the variable — the value is a
+        // secret and never appears in a suggested patch.
+        suggestedChange: (failure) => failure.provider === undefined
+            ? null
+            : {
+                op: "add",
+                path: `/env/${envVarNameFor(failure.provider)}`,
+                value: "<your API key>",
+                because: `Provider "${failure.provider}" has no usable credentials here. Set ` +
+                    `${envVarNameFor(failure.provider)} in the environment — never in the route file.`,
+            },
+    },
+    budget_exhausted: {
+        class: "budget_exhausted",
+        what: "The envelope this work was running under hit its cap, so spending stopped mid-run. " +
+            "This is the budget machinery working, not a bug.",
+        fixHint: "Decide whether the cap was wrong or the run was. Check the envelope's spend against what " +
+            "you expected before raising it — a runaway loop and an under-sized cap look identical " +
+            "from here, and only one of them is fixed by more money.",
+        docsUrl: `${DOCS_BASE}#budget_exhausted`,
+    },
+    invariant_violation: {
+        class: "invariant_violation",
+        what: "Something tried to serve a model your route never declared. The run was stopped rather " +
+            "than allowed to bill you for a model you did not choose.",
+        fixHint: "This is a bug in ModelRig, not in your configuration — the candidate set is meant to be " +
+            "an upper bound that nothing can escape. Please report it with the route name and the " +
+            "model that appeared.",
+        docsUrl: `${DOCS_BASE}#invariant_violation`,
+    },
+};
+/** Provider → the env var that keys it. Mirrors config.ts's PROVIDER_KEY_ENV;
+ * kept as a local lookup so this table has no import cycle with config. */
+function envVarNameFor(provider) {
+    const known = {
+        gemini: "GEMINI_API_KEY",
+        openai: "OPENAI_API_KEY",
+        deepseek: "DEEPSEEK_API_KEY",
+        anthropic: "ANTHROPIC_API_KEY",
+        grok: "XAI_API_KEY",
+        deepinfra: "MODELRIG_DEEPINFRA_API_KEY",
+        fireworks: "MODELRIG_FIREWORKS_API_KEY",
+    };
+    return known[provider] ?? `${provider.toUpperCase()}_API_KEY`;
+}
+function teach(failure) {
+    const entry = exports.FAILURE_TEACHING[failure.class];
+    return {
+        class: failure.class,
+        message: failure.message,
+        what: entry.what,
+        fixHint: failure.fixHint ?? entry.fixHint,
+        docsUrl: entry.docsUrl,
+        suggestedChange: entry.suggestedChange?.(failure) ?? null,
+    };
+}
+/** Terminal-friendly rendering — used by the CLI. Kept here so the CLI and
+ * the server cannot drift into two different-looking errors. */
+function renderFailureForTerminal(failure) {
+    const t = teach(failure);
+    const lines = [`[${t.class}] ${t.message}`, "", t.what, "", `Fix: ${t.fixHint}`, `Docs: ${t.docsUrl}`];
+    if (t.suggestedChange !== null) {
+        const change = t.suggestedChange;
+        lines.push("", `Suggested change: ${change.op} ${change.path}` +
+            (change.value === undefined ? "" : ` = ${JSON.stringify(change.value)}`), `  ${change.because}`);
+    }
+    return lines.join("\n");
+}

package/dist/types/failures.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Typed failure taxonomy — spec §2, §4.
+ * Adapters MUST map every provider error into a RigFailure; raw provider
+ * errors never cross the adapter boundary. Retry budgets are per-class and
+ * non-fungible (see run/retry.ts).
+ */
+export type FailureClass = "content_invalid" | "capacity_shed" | "network" | "refusal" | "cache_invalid" | "timeout" | "config_auth" | "budget_exhausted" | "invariant_violation";
+export interface RigFailure {
+    readonly class: FailureClass;
+    readonly message: string;
+    /** Provider/model that produced the failure, when applicable. */
+    readonly provider?: string;
+    readonly model?: string;
+    /** Raw underlying error for diagnostics; never used for control flow. */
+    readonly cause?: unknown;
+    /** Machine-readable remediation (errors-that-teach lands fully in Phase 5). */
+    readonly fixHint?: string;
+}
+export declare const TERMINAL_CLASSES: ReadonlySet<FailureClass>;
+/** Error subclass for the rare paths that must throw (config errors, terminal
+ * failures surfacing to the caller). The failure travels intact on `.failure`. */
+export declare class RigFailureError extends Error {
+    readonly failure: RigFailure;
+    constructor(failure: RigFailure);
+}
+export declare function isRigFailure(value: unknown): value is RigFailure;
+//# sourceMappingURL=failures.d.ts.map

package/dist/types/failures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failures.d.ts","sourceRoot":"","sources":["../../src/types/failures.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,eAAe,GACf,SAAS,GACT,SAAS,GACT,eAAe,GACf,SAAS,GACT,aAAa,GACb,kBAAkB,GAClB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,YAAY,CAGrD,CAAC;AAcH;kFACkF;AAClF,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;gBAEjB,OAAO,EAAE,UAAU;CAKhC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAIhE"}

package/dist/types/failures.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Typed failure taxonomy — spec §2, §4.
+ * Adapters MUST map every provider error into a RigFailure; raw provider
+ * errors never cross the adapter boundary. Retry budgets are per-class and
+ * non-fungible (see run/retry.ts).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RigFailureError = exports.TERMINAL_CLASSES = void 0;
+exports.isRigFailure = isRigFailure;
+exports.TERMINAL_CLASSES = new Set([
+    "budget_exhausted",
+    "invariant_violation",
+]);
+const FAILURE_CLASSES = new Set([
+    "content_invalid",
+    "capacity_shed",
+    "network",
+    "refusal",
+    "cache_invalid",
+    "timeout",
+    "config_auth",
+    "budget_exhausted",
+    "invariant_violation",
+]);
+/** Error subclass for the rare paths that must throw (config errors, terminal
+ * failures surfacing to the caller). The failure travels intact on `.failure`. */
+class RigFailureError extends Error {
+    constructor(failure) {
+        super(`[${failure.class}] ${failure.message}`);
+        this.name = "RigFailureError";
+        this.failure = failure;
+    }
+}
+exports.RigFailureError = RigFailureError;
+function isRigFailure(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return typeof v.class === "string" && FAILURE_CLASSES.has(v.class) && typeof v.message === "string";
+}