modelrig 0.0.1 → 0.2.0

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

@@ -0,0 +1,110 @@
+"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 (widened
+ * by 00033 for content custody) — 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.
+ *
+ * `artifact-write`/`artifact-read` (E2-C, 00033): request a content upload grant
+ * / mint a content download URL. Both are ordinary (non-elevated) machine
+ * grants — they move an org's own artifact bytes, they do not spend money or
+ * approve swaps (contrast decision/oracle-act, gated to admin/owner minters).
+ *
+ * `task-settings` (settings-plane, 00043): PATCH a task's governance settings
+ * (capture / artifacts / content / scrub). Held by a coding agent flipping
+ * settings for the user. READING settings needs no scope — any org-scoped key
+ * may read, since settings ride the already-readable task row.
+ */
+exports.API_KEY_SCOPES = [
+    "ingest",
+    "query",
+    "feedback",
+    "decision",
+    "oracle-act",
+    "artifact-write",
+    "artifact-read",
+    "task-settings",
+];
+/** 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/config-teaching.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Errors that teach, for LOAD-TIME config problems — onboarding-redesign §7 G2.
+ *
+ * The failure taxonomy in failures-teaching.ts classifies inference ATTEMPTS: a
+ * request that ran and went wrong. A malformed route bundle never ran — it is a
+ * `RouteConfigError`, deliberately outside that taxonomy (loader.ts §26). So
+ * the teaching table covered every way a call can fail and NOT the two things a
+ * first-time user actually hits first: a schema path that doesn't resolve, and
+ * a `{{variable}}` nobody declared. The setup flow's `failed` state and the
+ * docs' "when it doesn't work" sections both draw their copy from here, so
+ * `failed` has something precise to say exactly when it matters most.
+ *
+ * A `RouteConfigError` carries `.problems: string[]` — each a message the
+ * loader produced. This module classifies each into a SHAPE and attaches the
+ * three things a stuck author needs, in order: what it means, what to do, where
+ * to read. The completeness test makes every shape carry all three.
+ *
+ * NOTE what is deliberately NOT here: a `json: native` claim on a model that
+ * cannot hold it. The loader ACCEPTS that syntactically — it is a claim about
+ * the model, checked against the probed registry, not a config error. It loads
+ * and then behaves unlike the code it replaced, which is why the agent prompt
+ * (§3.5) states it as a constraint instead.
+ */
+import type { RouteConfigError } from "../routes/loader";
+export type ConfigProblemShape = "missing_schema" | "missing_prompt" | "undeclared_variable" | "unknown_provider" | "no_candidates" | "invalid_policy" | "invalid_cache" | "invalid_structure" | "duplicate_route" | "unknown_route" | "other";
+export interface ConfigTeaching {
+    readonly shape: ConfigProblemShape;
+    /** One sentence: what this problem MEANS, in the author's terms. */
+    readonly what: string;
+    /** The action to take — an instruction, not a diagnosis. */
+    readonly fixHint: string;
+    /** A deep link with a per-shape anchor, never a homepage. */
+    readonly docsUrl: string;
+}
+export declare const CONFIG_TEACHING: Readonly<Record<ConfigProblemShape, ConfigTeaching>>;
+/** Map one loader problem string to its shape. Ordered most-specific first. */
+export declare function classifyConfigProblem(problem: string): ConfigProblemShape;
+export interface TeachableConfigProblem extends ConfigTeaching {
+    /** The raw loader message — this is literally "what we found". */
+    readonly problem: string;
+}
+/** Teach every problem a RouteConfigError carries. */
+export declare function teachConfigError(error: RouteConfigError): {
+    readonly file: string | null;
+    readonly problems: readonly TeachableConfigProblem[];
+};
+/**
+ * The `failed`-state triple §3.1 asks for — what we looked for, what we found
+ * instead, and the most likely causes — for a route bundle that would not load.
+ * This is what the setup flow's `failed` state renders, and it is why that
+ * state can now describe its own absence instead of presenting as silence.
+ */
+export interface ConfigFailedState {
+    readonly lookedFor: string;
+    readonly found: readonly string[];
+    readonly causes: readonly string[];
+    readonly docsUrls: readonly string[];
+}
+export declare function describeConfigFailure(error: RouteConfigError): ConfigFailedState;
+/** Terminal-friendly rendering — parity with renderFailureForTerminal. */
+export declare function renderConfigErrorForTerminal(error: RouteConfigError): string;
+//# sourceMappingURL=config-teaching.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config-teaching.d.ts","sourceRoot":"","sources":["../../src/types/config-teaching.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,MAAM,MAAM,kBAAkB,GAC1B,gBAAgB,GAChB,gBAAgB,GAChB,qBAAqB,GACrB,kBAAkB,GAClB,eAAe,GACf,gBAAgB,GAChB,eAAe,GACf,mBAAmB,GACnB,iBAAiB,GACjB,eAAe,GACf,OAAO,CAAC;AAEZ,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAID,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,cAAc,CAAC,CAgHhF,CAAC;AAEF,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAezE;AAED,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACtD,CAWA;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CAUhF;AAED,0EAA0E;AAC1E,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAQ5E"}

package/dist/types/config-teaching.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * Errors that teach, for LOAD-TIME config problems — onboarding-redesign §7 G2.
+ *
+ * The failure taxonomy in failures-teaching.ts classifies inference ATTEMPTS: a
+ * request that ran and went wrong. A malformed route bundle never ran — it is a
+ * `RouteConfigError`, deliberately outside that taxonomy (loader.ts §26). So
+ * the teaching table covered every way a call can fail and NOT the two things a
+ * first-time user actually hits first: a schema path that doesn't resolve, and
+ * a `{{variable}}` nobody declared. The setup flow's `failed` state and the
+ * docs' "when it doesn't work" sections both draw their copy from here, so
+ * `failed` has something precise to say exactly when it matters most.
+ *
+ * A `RouteConfigError` carries `.problems: string[]` — each a message the
+ * loader produced. This module classifies each into a SHAPE and attaches the
+ * three things a stuck author needs, in order: what it means, what to do, where
+ * to read. The completeness test makes every shape carry all three.
+ *
+ * NOTE what is deliberately NOT here: a `json: native` claim on a model that
+ * cannot hold it. The loader ACCEPTS that syntactically — it is a claim about
+ * the model, checked against the probed registry, not a config error. It loads
+ * and then behaves unlike the code it replaced, which is why the agent prompt
+ * (§3.5) states it as a constraint instead.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_TEACHING = void 0;
+exports.classifyConfigProblem = classifyConfigProblem;
+exports.teachConfigError = teachConfigError;
+exports.describeConfigFailure = describeConfigFailure;
+exports.renderConfigErrorForTerminal = renderConfigErrorForTerminal;
+const DOCS_BASE = "https://modelrig.dev/route-bundles.html";
+exports.CONFIG_TEACHING = {
+    missing_schema: {
+        shape: "missing_schema",
+        what: "The bundle's `schema:` names a JSON Schema file, and there is no file at that path relative " +
+            "to the bundle. The route can't validate output it can't find the shape for, so it never loads.",
+        fixHint: "Create the schema file at the exact path the bundle names (paths resolve relative to the " +
+            "bundle's own directory), or set `schema: null` if this task is genuinely free-form.",
+        docsUrl: `${DOCS_BASE}#missing_schema`,
+    },
+    missing_prompt: {
+        shape: "missing_prompt",
+        what: "The bundle's `prompt.system:` names a template file that isn't at that path. A route with no " +
+            "prompt has nothing to send, so it fails at load rather than at the first call.",
+        fixHint: "Create the prompt file at the path the bundle names (relative to the bundle), or point " +
+            "`prompt.system` at where the file actually is.",
+        docsUrl: `${DOCS_BASE}#missing_prompt`,
+    },
+    undeclared_variable: {
+        shape: "undeclared_variable",
+        what: "The prompt template references a `{{variable}}` that `prompt.variables` doesn't declare. " +
+            "Undeclared references are rejected at load so a typo can't silently ship an empty slot.",
+        fixHint: "Add the variable to `prompt.variables`, or fix the reference in the template if it's a typo. " +
+            "Every `{{name}}` in the template (and in `grounding.query`) must appear in the declared list.",
+        docsUrl: `${DOCS_BASE}#undeclared_variable`,
+    },
+    unknown_provider: {
+        shape: "unknown_provider",
+        what: "A candidate names a provider the SDK has no adapter for, so nothing could ever serve that " +
+            "candidate.",
+        fixHint: "Use a provider the SDK ships an adapter for (gemini, openai, deepseek, anthropic, grok), and " +
+            "pick the model from the probed registry rather than from memory.",
+        docsUrl: `${DOCS_BASE}#unknown_provider`,
+    },
+    no_candidates: {
+        shape: "no_candidates",
+        what: "The route declares no candidates, so it has nothing it is allowed to serve — the candidate " +
+            "set is the upper bound, and an empty one bounds it to nothing.",
+        fixHint: "List at least one `{provider, model}` under `candidates:`. Every model the route may ever " +
+            "use has to be named here; nothing outside this list can serve it.",
+        docsUrl: `${DOCS_BASE}#no_candidates`,
+    },
+    invalid_policy: {
+        shape: "invalid_policy",
+        what: "A value under `policy` is out of range — a retry count, a timeout, the tier, or the json " +
+            "mode — so the route's behaviour would be undefined.",
+        fixHint: "Check the policy block against the reference: retries are non-negative integers keyed by a " +
+            "retryable failure class, `timeout_ms` is a positive integer, `tier` is standard|flex|priority, " +
+            "`json` is native|json_mode.",
+        docsUrl: `${DOCS_BASE}#invalid_policy`,
+    },
+    invalid_cache: {
+        shape: "invalid_cache",
+        what: "The bundle's `cache:` is set to a value the loader doesn't accept. Request-path caching has " +
+            'exactly one setting in v1 — `cache: auto` — which lets the SDK opt each provider into its ' +
+            "native prompt cache (and stamp a stable-prefix fingerprint for savings tracking).",
+        fixHint: 'Set `cache: auto` to turn on request-path caching for this route, or remove the `cache:` line ' +
+            "to leave it off. Gemini candidates need no opt-in — they cache implicitly and are skipped " +
+            "automatically even on an `auto` route.",
+        docsUrl: `${DOCS_BASE}#invalid_cache`,
+    },
+    invalid_structure: {
+        shape: "invalid_structure",
+        what: "The bundle isn't a well-formed route: it's not valid YAML, not a mapping, or missing the " +
+            "`route`/`version` a bundle must carry.",
+        fixHint: "Open the file and check it parses as YAML and has a non-empty `route:` and an integer " +
+            "`version:` at the top level. Copy the starter bundle if in doubt.",
+        docsUrl: `${DOCS_BASE}#invalid_structure`,
+    },
+    duplicate_route: {
+        shape: "duplicate_route",
+        what: "Two bundles in the routes directory declare the same `route:` name, so which one wins would " +
+            "be ambiguous.",
+        fixHint: "Give each route a unique name, or delete the duplicate bundle. Route names are the keys your " +
+            "code calls by, so they must be one-to-one with files.",
+        docsUrl: `${DOCS_BASE}#duplicate_route`,
+    },
+    unknown_route: {
+        shape: "unknown_route",
+        what: "Something asked to run a route no bundle defines — usually a name typo, or a bundle that " +
+            "isn't in the routes directory the SDK is reading.",
+        fixHint: "Check the route name against the bundles present, and confirm MODELRIG_ROUTES_DIR points at " +
+            "the directory that holds them.",
+        docsUrl: `${DOCS_BASE}#unknown_route`,
+    },
+    other: {
+        shape: "other",
+        what: "The route bundle is invalid in a way the loader reported but this table hasn't shaped yet.",
+        fixHint: "Read the exact problem the loader printed — it names the field — and check that field against " +
+            "the route-bundle reference.",
+        docsUrl: `${DOCS_BASE}#route-bundles`,
+    },
+};
+/** Map one loader problem string to its shape. Ordered most-specific first. */
+function classifyConfigProblem(problem) {
+    const p = problem.toLowerCase();
+    if (/schema file not found/.test(p))
+        return "missing_schema";
+    if (/prompt\.system file not found/.test(p))
+        return "missing_prompt";
+    if (/references undeclared variable/.test(p))
+        return "undeclared_variable";
+    if (/is not a known provider/.test(p))
+        return "unknown_provider";
+    if (/candidates must be a non-empty list|candidates\[.*\] must be/.test(p))
+        return "no_candidates";
+    if (/^policy|policy\.|policy /.test(p))
+        return "invalid_policy";
+    if (/^cache .*is not supported/.test(p))
+        return "invalid_cache";
+    if (/invalid yaml|must be a yaml mapping|^route must be|^version must be/.test(p)) {
+        return "invalid_structure";
+    }
+    if (/duplicate route/.test(p))
+        return "duplicate_route";
+    if (/unknown route|routes directory not found/.test(p))
+        return "unknown_route";
+    return "other";
+}
+/** Teach every problem a RouteConfigError carries. */
+function teachConfigError(error) {
+    // A bundle-level error (bad YAML, not a mapping) has no `.problems` entries;
+    // its own message is the problem.
+    const raw = error.problems.length > 0 ? error.problems : [error.message];
+    return {
+        file: error.file,
+        problems: raw.map((problem) => {
+            const teaching = exports.CONFIG_TEACHING[classifyConfigProblem(problem)];
+            return { ...teaching, problem };
+        }),
+    };
+}
+function describeConfigFailure(error) {
+    const taught = teachConfigError(error);
+    return {
+        lookedFor: error.file
+            ? `a route bundle that loads at ${error.file}`
+            : "a route bundle that loads",
+        found: taught.problems.map((p) => p.problem),
+        causes: taught.problems.map((p) => p.fixHint),
+        docsUrls: [...new Set(taught.problems.map((p) => p.docsUrl))],
+    };
+}
+/** Terminal-friendly rendering — parity with renderFailureForTerminal. */
+function renderConfigErrorForTerminal(error) {
+    const taught = teachConfigError(error);
+    const header = error.file ? `Route bundle did not load: ${error.file}` : "Route bundle did not load";
+    const lines = [header, ""];
+    for (const p of taught.problems) {
+        lines.push(`• ${p.problem}`, `  ${p.what}`, `  Fix: ${p.fixHint}`, `  Docs: ${p.docsUrl}`, "");
+    }
+    return lines.join("\n").trimEnd();
+}

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"}