modelrig 0.0.1 → 0.1.0

package/dist/routes/loader.js

@@ -0,0 +1,436 @@
+"use strict";
+/**
+ * Routes-as-code loader — spec §3, plan step 3.
+ * Scans a routes directory for *.yaml bundles, validates structurally,
+ * resolves schema/prompt paths relative to the bundle file, freezes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouteConfigError = void 0;
+exports.loadRoutes = loadRoutes;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const yaml_1 = require("yaml");
+const failures_1 = require("../types/failures");
+const fingerprint_1 = require("../registry/fingerprint");
+const template_1 = require("./template");
+/**
+ * Structured config error thrown for any invalid bundle (never a raw Error).
+ * Load-time problems are deliberately NOT RigFailures — the failure taxonomy
+ * classifies inference attempts; a malformed bundle means the rig was never
+ * runnable for that route.
+ */
+class RouteConfigError extends Error {
+    constructor(message, opts = {}) {
+        const problems = opts.problems ?? [];
+        super(problems.length > 0 ? `${message}: ${problems.join("; ")}` : message);
+        this.name = "RouteConfigError";
+        this.file = opts.file ?? null;
+        this.problems = problems;
+    }
+}
+exports.RouteConfigError = RouteConfigError;
+const PROVIDERS = new Set([
+    "gemini",
+    "openai",
+    "deepseek",
+    "anthropic",
+    "grok",
+]);
+const REQUIREMENTS = new Set([
+    "schema_conformant",
+    "grounded",
+    "zero_retention",
+    "trace_visible",
+]);
+const PREFERENCES = new Set(["cost", "latency"]);
+const TIERS = new Set(["standard", "flex", "priority"]);
+const JSON_MODES = new Set(["native", "json_mode"]);
+// config_auth is deliberately absent (F2): non-retryable by contract — a
+// bundle configuring retries for it is a config error, same as terminals.
+const RETRYABLE_CLASSES = new Set([
+    "content_invalid",
+    "capacity_shed",
+    "network",
+    "refusal",
+    "cache_invalid",
+    "timeout",
+].filter((c) => !failures_1.TERMINAL_CLASSES.has(c)));
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function parseCandidates(raw, problems) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        problems.push("candidates must be a non-empty list");
+        return [];
+    }
+    const out = [];
+    for (const [i, c] of raw.entries()) {
+        if (!isRecord(c) || typeof c.provider !== "string" || typeof c.model !== "string" || c.model === "") {
+            problems.push(`candidates[${i}] must be {provider, model}`);
+            continue;
+        }
+        if (!PROVIDERS.has(c.provider)) {
+            problems.push(`candidates[${i}].provider "${c.provider}" is not a known provider`);
+            continue;
+        }
+        out.push(Object.freeze({ provider: c.provider, model: c.model }));
+    }
+    return out;
+}
+function parseStringList(raw, field, allowed, problems) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw)) {
+        problems.push(`${field} must be a list`);
+        return [];
+    }
+    const out = [];
+    for (const v of raw) {
+        if (typeof v !== "string" || !allowed.has(v)) {
+            problems.push(`${field} entry "${String(v)}" is not one of [${[...allowed].join(", ")}]`);
+            continue;
+        }
+        out.push(v);
+    }
+    return out;
+}
+function parsePolicy(raw, problems) {
+    const fallback = Object.freeze({
+        retries: Object.freeze({}),
+        timeoutMs: 300000,
+        tier: "standard",
+        json: "native",
+    });
+    if (!isRecord(raw)) {
+        problems.push("policy must be an object");
+        return fallback;
+    }
+    const retries = {};
+    if (raw.retries !== undefined) {
+        if (!isRecord(raw.retries)) {
+            problems.push("policy.retries must be an object");
+        }
+        else {
+            for (const [cls, n] of Object.entries(raw.retries)) {
+                if (!RETRYABLE_CLASSES.has(cls)) {
+                    problems.push(`policy.retries key "${cls}" is not a retryable failure class`);
+                    continue;
+                }
+                if (typeof n !== "number" || !Number.isInteger(n) || n < 0) {
+                    problems.push(`policy.retries.${cls} must be a non-negative integer`);
+                    continue;
+                }
+                retries[cls] = n;
+            }
+        }
+    }
+    const timeoutMs = raw.timeout_ms;
+    if (typeof timeoutMs !== "number" || !Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+        problems.push("policy.timeout_ms must be a positive integer");
+    }
+    const tier = raw.tier ?? "standard";
+    if (typeof tier !== "string" || !TIERS.has(tier)) {
+        problems.push(`policy.tier "${String(tier)}" is not one of [${[...TIERS].join(", ")}]`);
+    }
+    const json = raw.json ?? "native";
+    if (typeof json !== "string" || !JSON_MODES.has(json)) {
+        problems.push(`policy.json "${String(json)}" is not one of [native, json_mode]`);
+    }
+    if (problems.length > 0)
+        return fallback;
+    return Object.freeze({
+        retries: Object.freeze(retries),
+        timeoutMs: timeoutMs,
+        tier: tier,
+        json: json,
+    });
+}
+/** "provider/model" string or {provider, model} mapping → CandidateSpec. */
+function parseRepairModel(raw, field, problems) {
+    let provider;
+    let model;
+    if (typeof raw === "string") {
+        const slash = raw.indexOf("/");
+        if (slash <= 0 || slash === raw.length - 1) {
+            problems.push(`${field} must be "provider/model" or {provider, model}`);
+            return null;
+        }
+        provider = raw.slice(0, slash);
+        model = raw.slice(slash + 1);
+    }
+    else if (isRecord(raw)) {
+        provider = raw.provider;
+        model = raw.model;
+    }
+    else {
+        problems.push(`${field} must be "provider/model" or {provider, model}`);
+        return null;
+    }
+    if (typeof provider !== "string" || !PROVIDERS.has(provider) || typeof model !== "string" || model === "") {
+        problems.push(`${field} has an unknown provider or empty model`);
+        return null;
+    }
+    return Object.freeze({ provider: provider, model });
+}
+function parseRepair(raw, field, candidates, problems) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        problems.push(`${field} must be an object {max_repairs, repair_model?}`);
+        return undefined;
+    }
+    const maxRepairs = raw.max_repairs;
+    if (typeof maxRepairs !== "number" || !Number.isInteger(maxRepairs) || maxRepairs < 1 || maxRepairs > 2) {
+        problems.push(`${field}.max_repairs must be 1 or 2 (retry-with-errors, then optional repair model)`);
+        return undefined;
+    }
+    let repairModel = null;
+    if (raw.repair_model !== undefined) {
+        repairModel = parseRepairModel(raw.repair_model, `${field}.repair_model`, problems);
+        if (repairModel !== null &&
+            !candidates.some((c) => c.provider === repairModel?.provider && c.model === repairModel?.model)) {
+            // Candidate-set invariant: the repair model must be a declared candidate.
+            problems.push(`${field}.repair_model (${repairModel.provider}/${repairModel.model}) is not in the route's declared candidates`);
+            repairModel = null;
+        }
+    }
+    if (maxRepairs === 2 && repairModel === null) {
+        problems.push(`${field}.max_repairs=2 requires repair_model (attempt 2 is the designated repair model)`);
+    }
+    return Object.freeze({
+        maxRepairs,
+        ...(repairModel !== null ? { repairModel } : {}),
+    });
+}
+function parseVariants(raw, routeCandidates, problems) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw)) {
+        problems.push("variants must be a list");
+        return [];
+    }
+    const seen = new Set();
+    const out = [];
+    const inDeclared = (c) => routeCandidates.some((rc) => rc.provider === c.provider && rc.model === c.model);
+    for (const [i, v] of raw.entries()) {
+        const field = `variants[${i}]`;
+        if (!isRecord(v)) {
+            problems.push(`${field} must be a mapping`);
+            continue;
+        }
+        if (typeof v.name !== "string" || v.name === "") {
+            problems.push(`${field}.name must be a non-empty string`);
+            continue;
+        }
+        if (v.name === "default") {
+            problems.push(`${field}.name "default" is reserved (the route's base config)`);
+            continue;
+        }
+        if (seen.has(v.name)) {
+            problems.push(`duplicate variant name "${v.name}"`);
+            continue;
+        }
+        seen.add(v.name);
+        let candidates;
+        if (v.candidates !== undefined) {
+            candidates = parseCandidates(v.candidates, problems);
+            for (const c of candidates) {
+                if (!inDeclared(c)) {
+                    // Candidate-set invariant: variants narrow, never widen.
+                    problems.push(`${field} candidate (${c.provider}, ${c.model}) is not in the route's declared candidates`);
+                }
+            }
+        }
+        if (v.prompt_override !== undefined && v.prompt_append !== undefined) {
+            problems.push(`${field} sets both prompt_override and prompt_append — they are mutually exclusive`);
+        }
+        for (const key of ["prompt_override", "prompt_append", "scaffold"]) {
+            if (v[key] !== undefined && typeof v[key] !== "string") {
+                problems.push(`${field}.${key} must be a string`);
+            }
+        }
+        if (v.json !== undefined && (typeof v.json !== "string" || !JSON_MODES.has(v.json))) {
+            problems.push(`${field}.json must be one of [native, json_mode]`);
+        }
+        const repair = parseRepair(v.repair, `${field}.repair`, routeCandidates, problems);
+        out.push(Object.freeze({
+            name: v.name,
+            ...(candidates !== undefined ? { candidates: Object.freeze(candidates) } : {}),
+            ...(typeof v.prompt_override === "string" ? { promptOverride: v.prompt_override } : {}),
+            ...(typeof v.prompt_append === "string" ? { promptAppend: v.prompt_append } : {}),
+            ...(typeof v.scaffold === "string" ? { scaffold: v.scaffold } : {}),
+            ...(typeof v.json === "string" && JSON_MODES.has(v.json)
+                ? { json: v.json }
+                : {}),
+            ...(repair !== undefined ? { repair } : {}),
+        }));
+    }
+    return out;
+}
+function readSchema(schemaRaw, bundleDir, problems) {
+    if (schemaRaw === null || schemaRaw === undefined)
+        return null;
+    if (typeof schemaRaw !== "string" || schemaRaw === "") {
+        problems.push("schema must be a relative path or null");
+        return null;
+    }
+    const schemaPath = (0, node_path_1.resolve)(bundleDir, schemaRaw);
+    if (!(0, node_fs_1.existsSync)(schemaPath)) {
+        problems.push(`schema file not found: ${schemaRaw}`);
+        return null;
+    }
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(schemaPath, "utf8"));
+        if (!isRecord(parsed)) {
+            problems.push(`schema file ${schemaRaw} must contain a JSON object`);
+            return null;
+        }
+        return parsed;
+    }
+    catch (err) {
+        problems.push(`schema file ${schemaRaw} is not valid JSON: ${err.message}`);
+        return null;
+    }
+}
+function loadBundleFile(filePath) {
+    const problems = [];
+    let doc;
+    try {
+        doc = (0, yaml_1.parse)((0, node_fs_1.readFileSync)(filePath, "utf8"));
+    }
+    catch (err) {
+        throw new RouteConfigError(`invalid YAML in route bundle`, {
+            file: filePath,
+            problems: [err.message],
+        });
+    }
+    if (!isRecord(doc)) {
+        throw new RouteConfigError("route bundle must be a YAML mapping", { file: filePath });
+    }
+    const route = doc.route;
+    if (typeof route !== "string" || route === "")
+        problems.push("route must be a non-empty string");
+    const version = doc.version;
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+        problems.push("version must be an integer >= 1");
+    }
+    const bundleDir = (0, node_path_1.dirname)(filePath);
+    const candidates = parseCandidates(doc.candidates, problems);
+    const require = parseStringList(doc.require, "require", REQUIREMENTS, problems);
+    const prefer = parseStringList(doc.prefer, "prefer", PREFERENCES, problems);
+    const outputSchema = readSchema(doc.schema, bundleDir, problems);
+    const policy = parsePolicy(doc.policy, problems);
+    // Phase 3 (bundle v2, all additive): variants, repair, capture opt-in,
+    // grounding-inject query template.
+    const variants = parseVariants(doc.variants, candidates, problems);
+    const repair = parseRepair(doc.repair, "repair", candidates, problems);
+    const capture = doc.capture ?? false;
+    if (typeof capture !== "boolean") {
+        problems.push("capture must be a boolean");
+    }
+    let groundingQuery;
+    if (doc.grounding !== undefined) {
+        if (!isRecord(doc.grounding) || typeof doc.grounding.query !== "string" || doc.grounding.query === "") {
+            problems.push("grounding must be an object {query: <template string>}");
+        }
+        else {
+            groundingQuery = doc.grounding.query;
+        }
+    }
+    let systemTemplate = "";
+    let variables = [];
+    if (!isRecord(doc.prompt) || typeof doc.prompt.system !== "string") {
+        problems.push("prompt.system must be a relative path");
+    }
+    else {
+        const promptPath = (0, node_path_1.resolve)(bundleDir, doc.prompt.system);
+        if (!(0, node_fs_1.existsSync)(promptPath)) {
+            problems.push(`prompt.system file not found: ${doc.prompt.system}`);
+        }
+        else {
+            systemTemplate = (0, node_fs_1.readFileSync)(promptPath, "utf8");
+        }
+        const rawVars = doc.prompt.variables ?? [];
+        if (!Array.isArray(rawVars) || rawVars.some((v) => typeof v !== "string")) {
+            problems.push("prompt.variables must be a list of strings");
+        }
+        else {
+            variables = rawVars;
+        }
+    }
+    if (systemTemplate !== "") {
+        const declared = new Set(variables);
+        for (const ref of (0, template_1.scanTemplateVariables)(systemTemplate)) {
+            if (!declared.has(ref)) {
+                problems.push(`template references undeclared variable "${ref}" (declare it in prompt.variables)`);
+            }
+        }
+    }
+    if (groundingQuery !== undefined) {
+        const declared = new Set(variables);
+        for (const ref of (0, template_1.scanTemplateVariables)(groundingQuery)) {
+            if (!declared.has(ref)) {
+                problems.push(`grounding.query references undeclared variable "${ref}"`);
+            }
+        }
+    }
+    if (problems.length > 0) {
+        throw new RouteConfigError("invalid route bundle", { file: filePath, problems });
+    }
+    return Object.freeze({
+        route: route,
+        version: version,
+        outputSchema: outputSchema === null ? null : Object.freeze(outputSchema),
+        candidates: Object.freeze(candidates),
+        require: Object.freeze(require),
+        prefer: Object.freeze(prefer),
+        systemTemplate,
+        variables: Object.freeze(variables),
+        policy,
+        ...(repair !== undefined ? { repair } : {}),
+        variants: Object.freeze(variants),
+        capture: capture === true,
+        ...(groundingQuery !== undefined ? { groundingQuery } : {}),
+        // Network-effect instrumentation (spec WS6): computed once at load,
+        // stamped on every telemetry row for this route.
+        fingerprintCell: (0, fingerprint_1.fingerprintSchema)(outputSchema)?.cellKey ?? null,
+    });
+}
+function loadRoutes(routesDir) {
+    if (!(0, node_fs_1.existsSync)(routesDir)) {
+        // First-run moment (Phase 5 WS4): this is the most likely error a new
+        // user ever sees, so it teaches instead of just reporting.
+        throw new RouteConfigError(`routes directory not found: ${routesDir}\n\n` +
+            "A route is a task your code calls by name — one small YAML file each, in that\n" +
+            "directory. There isn't one here yet. Two ways to get your first:\n\n" +
+            "  modelrig init .          draft routes from the provider calls already in this repo\n" +
+            "  mkdir -p " +
+            routesDir +
+            "   start empty and write one by hand\n\n" +
+            "Point somewhere else with MODELRIG_ROUTES_DIR. Docs: https://modelrig.dev/quickstart.html");
+    }
+    const files = (0, node_fs_1.readdirSync)(routesDir)
+        .filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"))
+        .sort()
+        .map((f) => (0, node_path_1.join)(routesDir, f));
+    const byName = new Map();
+    for (const file of files) {
+        const bundle = loadBundleFile(file);
+        if (byName.has(bundle.route)) {
+            throw new RouteConfigError(`duplicate route "${bundle.route}"`, { file });
+        }
+        byName.set(bundle.route, bundle);
+    }
+    return {
+        get(route) {
+            const bundle = byName.get(route);
+            if (!bundle) {
+                throw new RouteConfigError(`unknown route "${route}" — known routes: [${[...byName.keys()].join(", ")}]`);
+            }
+            return bundle;
+        },
+        list() {
+            return Object.freeze([...byName.values()]);
+        },
+    };
+}

package/dist/routes/manifest.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The rig manifest (modelrig/rig.yaml) — cost-dimensions-design.md §2a.
+ * Project-level, optional; absence means "no declared dimensions" and
+ * everything continues to work (declaration upgrades, never gates).
+ */
+import type { RunTags } from "../types/route";
+export interface DimensionSpec {
+    readonly key: string;
+    readonly label: string;
+    readonly required: boolean;
+}
+export interface RigManifest {
+    readonly name: string;
+    readonly dimensions: readonly DimensionSpec[];
+    /** Conformance Matrix contribution consent — default false (Phase 2: flag
+     * + mirror only; no pipeline consumes it yet). */
+    readonly contribution: boolean;
+}
+export declare function loadManifest(rigDir: string): RigManifest | null;
+/** Required dimensions with no (non-empty) value in the run's tags — pure. */
+export declare function missingRequiredDimensions(manifest: RigManifest | null, tags: RunTags): readonly string[];
+export declare function warnMissingRequiredDimensions(manifest: RigManifest | null, tags: RunTags, log?: (message: string) => void): void;
+export declare function resetDimensionWarningsForTest(): void;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/routes/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/routes/manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C;sDACkD;IAClD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AA+CD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAoC/D;AAED,8EAA8E;AAC9E,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,WAAW,GAAG,IAAI,EAC5B,IAAI,EAAE,OAAO,GACZ,SAAS,MAAM,EAAE,CASnB;AAMD,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,WAAW,GAAG,IAAI,EAC5B,IAAI,EAAE,OAAO,EACb,GAAG,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAmB,GAC5C,IAAI,CASN;AAED,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD"}

package/dist/routes/manifest.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * The rig manifest (modelrig/rig.yaml) — cost-dimensions-design.md §2a.
+ * Project-level, optional; absence means "no declared dimensions" and
+ * everything continues to work (declaration upgrades, never gates).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadManifest = loadManifest;
+exports.missingRequiredDimensions = missingRequiredDimensions;
+exports.warnMissingRequiredDimensions = warnMissingRequiredDimensions;
+exports.resetDimensionWarningsForTest = resetDimensionWarningsForTest;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const yaml_1 = require("yaml");
+const loader_1 = require("./loader");
+const TAG_SAFE_KEY = /^[A-Za-z0-9_]{1,64}$/;
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function parseDimensions(raw, problems) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw)) {
+        problems.push("dimensions must be a list");
+        return [];
+    }
+    const out = [];
+    const seen = new Set();
+    for (const [i, d] of raw.entries()) {
+        if (!isRecord(d) || typeof d.key !== "string") {
+            problems.push(`dimensions[${i}] must be an object with a string key`);
+            continue;
+        }
+        if (!TAG_SAFE_KEY.test(d.key)) {
+            problems.push(`dimensions[${i}].key "${d.key}" is not tag-safe (must match [A-Za-z0-9_]{1,64})`);
+            continue;
+        }
+        if (seen.has(d.key)) {
+            problems.push(`duplicate dimension key "${d.key}"`);
+            continue;
+        }
+        seen.add(d.key);
+        const label = d.label ?? d.key;
+        if (typeof label !== "string" || label === "") {
+            problems.push(`dimensions[${i}].label must be a non-empty string`);
+            continue;
+        }
+        const required = d.required ?? false;
+        if (typeof required !== "boolean") {
+            problems.push(`dimensions[${i}].required must be a boolean`);
+            continue;
+        }
+        out.push(Object.freeze({ key: d.key, label, required }));
+    }
+    return out;
+}
+function loadManifest(rigDir) {
+    const manifestPath = (0, node_path_1.join)(rigDir, "rig.yaml");
+    if (!(0, node_fs_1.existsSync)(manifestPath))
+        return null; // absence never gates
+    let doc;
+    try {
+        doc = (0, yaml_1.parse)((0, node_fs_1.readFileSync)(manifestPath, "utf8"));
+    }
+    catch (err) {
+        throw new loader_1.RouteConfigError("invalid YAML in rig manifest", {
+            file: manifestPath,
+            problems: [err.message],
+        });
+    }
+    if (!isRecord(doc)) {
+        throw new loader_1.RouteConfigError("rig manifest must be a YAML mapping", { file: manifestPath });
+    }
+    const problems = [];
+    if (typeof doc.name !== "string" || doc.name === "") {
+        problems.push("name must be a non-empty string");
+    }
+    const dimensions = parseDimensions(doc.dimensions, problems);
+    const contribution = doc.contribution ?? false;
+    if (typeof contribution !== "boolean") {
+        problems.push("contribution must be a boolean");
+    }
+    if (problems.length > 0) {
+        throw new loader_1.RouteConfigError("invalid rig manifest", { file: manifestPath, problems });
+    }
+    return Object.freeze({
+        name: doc.name,
+        dimensions: Object.freeze(dimensions),
+        contribution: contribution,
+    });
+}
+/** Required dimensions with no (non-empty) value in the run's tags — pure. */
+function missingRequiredDimensions(manifest, tags) {
+    if (manifest === null)
+        return [];
+    return manifest.dimensions
+        .filter((d) => d.required)
+        .filter((d) => {
+        const value = tags[d.key];
+        return value === undefined || value === "";
+    })
+        .map((d) => d.key);
+}
+/** Once per process per dimension (spec WS5) — repeated untagged runs stay
+ * quiet after the first warning so pipelines aren't spammed. */
+const warnedDimensions = new Set();
+function warnMissingRequiredDimensions(manifest, tags, log = console.warn) {
+    for (const key of missingRequiredDimensions(manifest, tags)) {
+        if (warnedDimensions.has(key))
+            continue;
+        warnedDimensions.add(key);
+        log(`[modelrig] required dimension "${key}" missing from run tags — costs for these runs ` +
+            `will be under-attributed on /costs (declared in rig.yaml)`);
+    }
+}
+function resetDimensionWarningsForTest() {
+    warnedDimensions.clear();
+}

package/dist/routes/serveability.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Load-time route serveability — Phase 4 resilience (architect-flagged
+ * change to the Phase-1 fail-fast guard).
+ *
+ * A declared candidate whose provider has no registered adapter (no API key
+ * in THIS environment) is INERT, not fatal: the gateway must not crash at
+ * boot because a bake-off challenger arm lacks a key here. This is the
+ * "safe but inert" behaviour the route-v3 commit assumed — true on the
+ * InferWealth cutover wrapper (it catches + falls back to legacy), but the
+ * standalone modelrig-server builds the rig eagerly at boot with no catch,
+ * so a keyless arm downed staging.
+ *
+ * Rule: warn per inert candidate and keep serving on the keyed ones; a route
+ * with ZERO serveable candidates is still a hard error (genuinely dead). The
+ * candidate-set UPPER bound is untouched — resolveCandidates still only
+ * yields declared candidates, and the run loop skips inert ones at dispatch.
+ */
+import type { RigFailure } from "../types/failures";
+import type { CandidateRef } from "../types/provider";
+import type { CandidateSpec } from "../types/route";
+/** One route's inert candidates, structured so surfaces beyond the log —
+ * the server boot banner and console /setup (F1) — can name them and say
+ * exactly which env var fixes each. */
+export interface ServeabilityWarning {
+    readonly route: string;
+    /** Declared candidates with no adapter in this environment. */
+    readonly inert: readonly CandidateSpec[];
+    /** Distinct providers behind `inert`, in declaration order. */
+    readonly missingProviders: readonly string[];
+    /** How many candidates CAN serve — the route is alive on these. */
+    readonly serveableCount: number;
+    /** The log/banner line (what `checkServeability` returns). */
+    readonly message: string;
+    /** The teaching half: the env vars to set, named. */
+    readonly fixHint: string;
+}
+/** Typed failure for an inert (keyless) candidate the run loop skips at
+ * dispatch — non-terminal config_auth so the loop advances to the next
+ * declared candidate; surfaced as the run's error only if EVERY candidate
+ * is inert. */
+export declare function inertCandidateFailure(candidate: CandidateRef, route: string): RigFailure;
+export declare function serveabilityWarnings(bundles: ReadonlyArray<{
+    readonly route: string;
+    readonly candidates: readonly CandidateSpec[];
+}>, hasAdapter: (provider: string) => boolean): ServeabilityWarning[];
+/** String façade over {@link serveabilityWarnings} — one traversal, one
+ * source of wording. Throws identically on a zero-serveable route. */
+export declare function checkServeability(bundles: ReadonlyArray<{
+    readonly route: string;
+    readonly candidates: readonly CandidateSpec[];
+}>, hasAdapter: (provider: string) => boolean): string[];
+//# sourceMappingURL=serveability.d.ts.map

package/dist/routes/serveability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serveability.d.ts","sourceRoot":"","sources":["../../src/routes/serveability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;uCAEuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,+DAA+D;IAC/D,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAMD;;;eAGe;AACf,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAUxF;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,CAAC,EACjG,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,GACxC,mBAAmB,EAAE,CA4BvB;AAED;sEACsE;AACtE,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,CAAC,EACjG,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,GACxC,MAAM,EAAE,CAEV"}