modelrig 0.0.1 → 0.2.0

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/resolved-bundle.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The RESOLVED route bundle — http-gateway spec §13 (Phase D).
+ *
+ * A `RouteBundle` in memory already has its file references FOLLOWED and
+ * INLINED: `loader.ts` reads the schema file into `outputSchema` (a parsed JSON
+ * object) and the prompt file into `systemTemplate` (a string), and a MISSING
+ * file fails there with a teaching `RouteConfigError` — at deploy, where the
+ * developer is, never at request where the customer is (§13.1 rule 6). So the
+ * "resolved bundle" the exporter mirrors is a pure, serialisable PROJECTION of
+ * an already-loaded bundle; this module is the ONE definition of that shape and
+ * of the round-trip both sides use.
+ *
+ *   exporter (SDK)   resolveRouteBundle(bundle) → ResolvedRouteBundle + sha
+ *                    → mirrored onto public.routes.bundle / bundle_sha
+ *   gateway (server) bundleFromResolved(mirrored) → RouteBundle
+ *                    → rig.runBundle(bundle, opts) → the SAME verified pipeline
+ *
+ * `bundle_sha` is the content hash of the CANONICAL serialisation (keys sorted
+ * recursively, array order preserved), so the same bundle always hashes the
+ * same and the console can flag a mirror that no longer matches git (§13.1
+ * rule 5). The hash is computed once, at sync time, from the resolved bundle.
+ *
+ * `fingerprintCell` is NOT carried on the wire: it is derived from
+ * `outputSchema` and recomputed on rebuild, so it can never drift from the
+ * schema it fingerprints.
+ */
+import type { LoadedRoutes } from "./loader";
+import type { CandidateSpec, Preference, RepairPolicy, Requirement, RouteBundle, RoutePolicy, RouteVariant } from "../types/route";
+/**
+ * The canonical, JSON-serialisable form of a resolved route bundle. Every field
+ * here defines how the route BEHAVES — the gateway needs all of them to drive
+ * the verified pipeline without the customer's filesystem. `fingerprintCell` is
+ * deliberately absent (derived from `outputSchema`, recomputed on rebuild).
+ */
+export interface ResolvedRouteBundle {
+    readonly route: string;
+    readonly version: number;
+    /** Resolved, parsed JSON Schema (null = unstructured route). Inlined at sync. */
+    readonly outputSchema: object | null;
+    readonly candidates: readonly CandidateSpec[];
+    readonly require: readonly Requirement[];
+    readonly prefer: readonly Preference[];
+    /** Raw template text — the prompt FILE, inlined at sync. */
+    readonly systemTemplate: string;
+    readonly variables: readonly string[];
+    readonly policy: RoutePolicy;
+    readonly repair?: RepairPolicy;
+    readonly variants: readonly RouteVariant[];
+    readonly capture: boolean;
+    readonly groundingQuery?: string;
+}
+/** Project an already-loaded (resolved) bundle to its serialisable form. Pure —
+ * no filesystem; the loader already followed every file reference. */
+export declare function resolveRouteBundle(bundle: RouteBundle): ResolvedRouteBundle;
+/** The canonical serialisation whose hash becomes `bundle_sha`. */
+export declare function canonicalBundleJson(bundle: ResolvedRouteBundle): string;
+/** Content hash of the canonical bundle — `sha256:<hex>`. Self-describing so a
+ * future algorithm change is visible in the stored value rather than silent. */
+export declare function hashResolvedBundle(bundle: ResolvedRouteBundle): string;
+/**
+ * Rebuild a runnable `RouteBundle` from a mirrored resolved bundle. Recomputes
+ * `fingerprintCell` from `outputSchema` (never trusted from the wire) and
+ * freezes to match loader output. Throws `RouteConfigError` — the loader's own
+ * teaching class — if the mirrored payload is structurally unusable, so a
+ * corrupt mirror row surfaces as a teaching error, not a downstream crash.
+ */
+export declare function bundleFromResolved(raw: unknown): RouteBundle;
+/**
+ * A `LoadedRoutes` holding exactly ONE bundle — the seam that lets the verified
+ * pipeline run over a mirrored bundle without a local routes directory.
+ *
+ * `run()`/`runStream()` resolve a route only through `deps.routes.get(name)`, so
+ * swapping in this store (and nothing else) runs the WHOLE existing pipeline —
+ * validate, repair, envelope, telemetry, ZDR (G-3), routing controls (G-2) —
+ * over the provided bundle. Asking for any other name is a teaching error, so a
+ * mismatched slug can never silently resolve to the wrong route.
+ */
+export declare function singleRouteStore(bundle: RouteBundle): LoadedRoutes;
+//# sourceMappingURL=resolved-bundle.d.ts.map

package/dist/routes/resolved-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolved-bundle.d.ts","sourceRoot":"","sources":["../../src/routes/resolved-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACb,MAAM,gBAAgB,CAAC;AAExB;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;sEACsE;AACtE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,mBAAmB,CAgB3E;AAiBD,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAEvE;AAED;gFACgF;AAChF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAsC5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAclE"}

package/dist/routes/resolved-bundle.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * The RESOLVED route bundle — http-gateway spec §13 (Phase D).
+ *
+ * A `RouteBundle` in memory already has its file references FOLLOWED and
+ * INLINED: `loader.ts` reads the schema file into `outputSchema` (a parsed JSON
+ * object) and the prompt file into `systemTemplate` (a string), and a MISSING
+ * file fails there with a teaching `RouteConfigError` — at deploy, where the
+ * developer is, never at request where the customer is (§13.1 rule 6). So the
+ * "resolved bundle" the exporter mirrors is a pure, serialisable PROJECTION of
+ * an already-loaded bundle; this module is the ONE definition of that shape and
+ * of the round-trip both sides use.
+ *
+ *   exporter (SDK)   resolveRouteBundle(bundle) → ResolvedRouteBundle + sha
+ *                    → mirrored onto public.routes.bundle / bundle_sha
+ *   gateway (server) bundleFromResolved(mirrored) → RouteBundle
+ *                    → rig.runBundle(bundle, opts) → the SAME verified pipeline
+ *
+ * `bundle_sha` is the content hash of the CANONICAL serialisation (keys sorted
+ * recursively, array order preserved), so the same bundle always hashes the
+ * same and the console can flag a mirror that no longer matches git (§13.1
+ * rule 5). The hash is computed once, at sync time, from the resolved bundle.
+ *
+ * `fingerprintCell` is NOT carried on the wire: it is derived from
+ * `outputSchema` and recomputed on rebuild, so it can never drift from the
+ * schema it fingerprints.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRouteBundle = resolveRouteBundle;
+exports.canonicalBundleJson = canonicalBundleJson;
+exports.hashResolvedBundle = hashResolvedBundle;
+exports.bundleFromResolved = bundleFromResolved;
+exports.singleRouteStore = singleRouteStore;
+const node_crypto_1 = require("node:crypto");
+const fingerprint_1 = require("../registry/fingerprint");
+const loader_1 = require("./loader");
+/** Project an already-loaded (resolved) bundle to its serialisable form. Pure —
+ * no filesystem; the loader already followed every file reference. */
+function resolveRouteBundle(bundle) {
+    return {
+        route: bundle.route,
+        version: bundle.version,
+        outputSchema: bundle.outputSchema,
+        candidates: bundle.candidates,
+        require: bundle.require,
+        prefer: bundle.prefer,
+        systemTemplate: bundle.systemTemplate,
+        variables: bundle.variables,
+        policy: bundle.policy,
+        ...(bundle.repair !== undefined ? { repair: bundle.repair } : {}),
+        variants: bundle.variants,
+        capture: bundle.capture,
+        ...(bundle.groundingQuery !== undefined ? { groundingQuery: bundle.groundingQuery } : {}),
+    };
+}
+/** Deterministic JSON: object keys sorted recursively, array order preserved.
+ * The whole point is that the SAME bundle always produces the SAME bytes, so
+ * the content hash is stable across processes and machines. */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = canonicalize(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/** The canonical serialisation whose hash becomes `bundle_sha`. */
+function canonicalBundleJson(bundle) {
+    return JSON.stringify(canonicalize(bundle));
+}
+/** Content hash of the canonical bundle — `sha256:<hex>`. Self-describing so a
+ * future algorithm change is visible in the stored value rather than silent. */
+function hashResolvedBundle(bundle) {
+    return `sha256:${(0, node_crypto_1.createHash)("sha256").update(canonicalBundleJson(bundle)).digest("hex")}`;
+}
+/**
+ * Rebuild a runnable `RouteBundle` from a mirrored resolved bundle. Recomputes
+ * `fingerprintCell` from `outputSchema` (never trusted from the wire) and
+ * freezes to match loader output. Throws `RouteConfigError` — the loader's own
+ * teaching class — if the mirrored payload is structurally unusable, so a
+ * corrupt mirror row surfaces as a teaching error, not a downstream crash.
+ */
+function bundleFromResolved(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new loader_1.RouteConfigError("mirrored route bundle is not an object");
+    }
+    const b = raw;
+    if (typeof b.route !== "string" || b.route === "") {
+        throw new loader_1.RouteConfigError("mirrored route bundle is missing `route`");
+    }
+    if (typeof b.version !== "number" || !Number.isInteger(b.version)) {
+        throw new loader_1.RouteConfigError(`mirrored route bundle "${b.route}" is missing a valid \`version\``);
+    }
+    if (!Array.isArray(b.candidates) || b.candidates.length === 0) {
+        throw new loader_1.RouteConfigError(`mirrored route bundle "${b.route}" has no candidates`);
+    }
+    if (typeof b.systemTemplate !== "string") {
+        throw new loader_1.RouteConfigError(`mirrored route bundle "${b.route}" is missing \`systemTemplate\``);
+    }
+    if (b.policy === undefined || b.policy === null) {
+        throw new loader_1.RouteConfigError(`mirrored route bundle "${b.route}" is missing \`policy\``);
+    }
+    const outputSchema = b.outputSchema ?? null;
+    return Object.freeze({
+        route: b.route,
+        version: b.version,
+        outputSchema: outputSchema === null ? null : Object.freeze(outputSchema),
+        candidates: Object.freeze([...b.candidates]),
+        require: Object.freeze([...(b.require ?? [])]),
+        prefer: Object.freeze([...(b.prefer ?? [])]),
+        systemTemplate: b.systemTemplate,
+        variables: Object.freeze([...(b.variables ?? [])]),
+        policy: b.policy,
+        ...(b.repair !== undefined ? { repair: b.repair } : {}),
+        variants: Object.freeze([...(b.variants ?? [])]),
+        capture: b.capture === true,
+        ...(b.groundingQuery !== undefined ? { groundingQuery: b.groundingQuery } : {}),
+        // Recomputed, never trusted from the wire — cannot drift from the schema.
+        fingerprintCell: (0, fingerprint_1.fingerprintSchema)(outputSchema)?.cellKey ?? null,
+    });
+}
+/**
+ * A `LoadedRoutes` holding exactly ONE bundle — the seam that lets the verified
+ * pipeline run over a mirrored bundle without a local routes directory.
+ *
+ * `run()`/`runStream()` resolve a route only through `deps.routes.get(name)`, so
+ * swapping in this store (and nothing else) runs the WHOLE existing pipeline —
+ * validate, repair, envelope, telemetry, ZDR (G-3), routing controls (G-2) —
+ * over the provided bundle. Asking for any other name is a teaching error, so a
+ * mismatched slug can never silently resolve to the wrong route.
+ */
+function singleRouteStore(bundle) {
+    return {
+        get(route) {
+            if (route !== bundle.route) {
+                throw new loader_1.RouteConfigError(`route "${route}" is not the mirrored bundle "${bundle.route}"`);
+            }
+            return bundle;
+        },
+        list() {
+            return Object.freeze([bundle]);
+        },
+    };
+}

package/dist/routes/sampling-config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Route-bundle sampling config (CE-6, spec §2/§3) — extracted from loader.ts to
+ * keep it under the 700-LOC cap. Pure parsing + the Gemini-3 advisory; the
+ * loader calls both and owns the fail-loud aggregation.
+ */
+import type { SamplingParams } from "../types/provider";
+import type { CandidateSpec, RoutePolicy } from "../types/route";
+/**
+ * Parse + validate `policy.sampling`. YAML is snake_case (`temperature` /
+ * `top_p` / `max_output_tokens`); the parsed block is camelCase
+ * (`SamplingParams`). Ranges are the permissive provider envelope — a value the
+ * provider then rejects surfaces through the run loop's failure ladder, never a
+ * silent clamp here (spec §3/§6). Every violation is a config error at load
+ * (fail-loud). Returns undefined when the block is absent OR empty ⇒ every
+ * adapter behaves exactly as pre-CE-6.
+ */
+export declare function parseSampling(raw: unknown, field: string, problems: string[]): SamplingParams | undefined;
+/** A Gemini-3.x model id (gemini-3.0-*, gemini-3.1-*, gemini-3-*). Google
+ * recommends temperature=1.0 for the whole Gemini-3 family (CE-6 §3). */
+export declare function isGemini3Model(model: string): boolean;
+/**
+ * CE-6 §3/§6: warn (non-fatal) when a route declares a sub-1.0 temperature on a
+ * Gemini-3 candidate. Google STRONGLY recommends temperature=1.0 for Gemini 3
+ * and warns sub-1.0 values can loop / degrade on complex reasoning tasks
+ * (classification/extraction are typically fine — which is why the source
+ * pipeline ran gemini-3.1-pro at 0.1 for classification without looping). The
+ * route still LOADS and the request is still sent AS DECLARED — the honest
+ * middle: the customer asked, we told them, the request goes as asked. Returns
+ * the warning line, or null when no advisory applies.
+ */
+export declare function gemini3LowTemperatureWarning(route: string, policy: RoutePolicy, candidates: readonly CandidateSpec[]): string | null;
+//# sourceMappingURL=sampling-config.d.ts.map

package/dist/routes/sampling-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling-config.d.ts","sourceRoot":"","sources":["../../src/routes/sampling-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAMjE;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,GACjB,cAAc,GAAG,SAAS,CAmC5B;AAED;yEACyE;AACzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,SAAS,aAAa,EAAE,GACnC,MAAM,GAAG,IAAI,CAaf"}

package/dist/routes/sampling-config.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Route-bundle sampling config (CE-6, spec §2/§3) — extracted from loader.ts to
+ * keep it under the 700-LOC cap. Pure parsing + the Gemini-3 advisory; the
+ * loader calls both and owns the fail-loud aggregation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSampling = parseSampling;
+exports.isGemini3Model = isGemini3Model;
+exports.gemini3LowTemperatureWarning = gemini3LowTemperatureWarning;
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Parse + validate `policy.sampling`. YAML is snake_case (`temperature` /
+ * `top_p` / `max_output_tokens`); the parsed block is camelCase
+ * (`SamplingParams`). Ranges are the permissive provider envelope — a value the
+ * provider then rejects surfaces through the run loop's failure ladder, never a
+ * silent clamp here (spec §3/§6). Every violation is a config error at load
+ * (fail-loud). Returns undefined when the block is absent OR empty ⇒ every
+ * adapter behaves exactly as pre-CE-6.
+ */
+function parseSampling(raw, field, problems) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        problems.push(`${field} must be an object {temperature?, top_p?, max_output_tokens?}`);
+        return undefined;
+    }
+    const out = {};
+    const t = raw.temperature;
+    if (t !== undefined) {
+        if (typeof t !== "number" || !Number.isFinite(t) || t < 0 || t > 2) {
+            problems.push(`${field}.temperature must be a number in [0, 2]`);
+        }
+        else {
+            out.temperature = t;
+        }
+    }
+    const p = raw.top_p;
+    if (p !== undefined) {
+        if (typeof p !== "number" || !Number.isFinite(p) || p <= 0 || p > 1) {
+            problems.push(`${field}.top_p must be a number in (0, 1]`);
+        }
+        else {
+            out.topP = p;
+        }
+    }
+    const m = raw.max_output_tokens;
+    if (m !== undefined) {
+        if (typeof m !== "number" || !Number.isInteger(m) || m < 1) {
+            problems.push(`${field}.max_output_tokens must be an integer >= 1`);
+        }
+        else {
+            out.maxOutputTokens = m;
+        }
+    }
+    if (out.temperature === undefined && out.topP === undefined && out.maxOutputTokens === undefined) {
+        return undefined;
+    }
+    return Object.freeze(out);
+}
+/** A Gemini-3.x model id (gemini-3.0-*, gemini-3.1-*, gemini-3-*). Google
+ * recommends temperature=1.0 for the whole Gemini-3 family (CE-6 §3). */
+function isGemini3Model(model) {
+    return /^gemini-3(\.\d+)?[-.]/.test(model) || model === "gemini-3";
+}
+/**
+ * CE-6 §3/§6: warn (non-fatal) when a route declares a sub-1.0 temperature on a
+ * Gemini-3 candidate. Google STRONGLY recommends temperature=1.0 for Gemini 3
+ * and warns sub-1.0 values can loop / degrade on complex reasoning tasks
+ * (classification/extraction are typically fine — which is why the source
+ * pipeline ran gemini-3.1-pro at 0.1 for classification without looping). The
+ * route still LOADS and the request is still sent AS DECLARED — the honest
+ * middle: the customer asked, we told them, the request goes as asked. Returns
+ * the warning line, or null when no advisory applies.
+ */
+function gemini3LowTemperatureWarning(route, policy, candidates) {
+    const temp = policy.sampling?.temperature;
+    if (temp === undefined || temp >= 1.0)
+        return null;
+    const affected = candidates.filter((c) => c.provider === "gemini" && isGemini3Model(c.model));
+    if (affected.length === 0)
+        return null;
+    const models = affected.map((c) => c.model).join(", ");
+    return (`route "${route}" declares policy.sampling.temperature=${temp} for Gemini-3 candidate(s) ` +
+        `[${models}]. Google recommends temperature=1.0 for Gemini 3; values <1.0 can cause looping / ` +
+        `degraded output on complex reasoning tasks (classification/extraction are typically fine). ` +
+        `The route loads and the request is sent as declared. ` +
+        `Docs: https://ai.google.dev/gemini-api/docs/gemini-3`);
+}

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

package/dist/routes/serveability.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inertCandidateFailure = inertCandidateFailure;
+exports.serveabilityWarnings = serveabilityWarnings;
+exports.checkServeability = checkServeability;
+const config_1 = require("../config");
+const loader_1 = require("./loader");
+function envVarFor(provider) {
+    return config_1.PROVIDER_KEY_ENV[provider] ?? `${provider.toUpperCase()}_API_KEY`;
+}
+/** 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. */
+function inertCandidateFailure(candidate, route) {
+    return {
+        class: "config_auth",
+        message: `provider "${candidate.provider}" has no adapter (declared by route "${route}") — ` +
+            `its API key is not configured; skipping this candidate`,
+        provider: candidate.provider,
+        model: candidate.model,
+        fixHint: `configure the ${candidate.provider} API key to enable this candidate`,
+    };
+}
+function serveabilityWarnings(bundles, hasAdapter) {
+    const warnings = [];
+    for (const bundle of bundles) {
+        const serveable = bundle.candidates.filter((c) => hasAdapter(c.provider));
+        if (serveable.length === 0) {
+            const providers = [...new Set(bundle.candidates.map((c) => c.provider))];
+            throw new loader_1.RouteConfigError(`route "${bundle.route}" has no serveable candidate — none of its declared providers ` +
+                `[${providers.join(", ")}] has an API key configured ` +
+                `(set ${providers.map(envVarFor).join(" or ")})`);
+        }
+        const inert = bundle.candidates.filter((c) => !hasAdapter(c.provider));
+        if (inert.length === 0)
+            continue;
+        const missingProviders = [...new Set(inert.map((c) => c.provider))];
+        warnings.push({
+            route: bundle.route,
+            inert,
+            missingProviders,
+            serveableCount: serveable.length,
+            message: `route "${bundle.route}": ${inert.length} candidate(s) inert (no API key) — ` +
+                `${inert.map((c) => `${c.provider}/${c.model}`).join(", ")}; serving on ` +
+                `${serveable.length} keyed candidate(s) until their keys are configured.`,
+            fixHint: `set ${missingProviders.map(envVarFor).join(", ")} to enable these candidates`,
+        });
+    }
+    return warnings;
+}
+/** String façade over {@link serveabilityWarnings} — one traversal, one
+ * source of wording. Throws identically on a zero-serveable route. */
+function checkServeability(bundles, hasAdapter) {
+    return serveabilityWarnings(bundles, hasAdapter).map((w) => w.message);
+}

package/dist/routes/template.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Template renderer — spec §3, plan §4.
+ * Supports {{var}} substitution and capability-conditional blocks:
+ *   {{#if capability.grounded_native}}...{{/if}}
+ *   {{#unless capability.structured_native}}...{{/unless}}
+ * Deliberately hand-rolled and tiny — NO external template engine (jinja-class
+ * engines are a documented CVE surface; see litellm-vendoring-strategy.md §3).
+ */
+import type { CapabilityFlag } from "../types/provider";
+export interface RenderContext {
+    readonly variables: Record<string, unknown>;
+    readonly capabilities: ReadonlySet<CapabilityFlag>;
+}
+export declare function renderTemplate(template: string, ctx: RenderContext): string;
+/** Distinct {{var}} names referenced anywhere in the template (loader
+ * validation: every reference must be a declared variable). */
+export declare function scanTemplateVariables(template: string): readonly string[];
+//# sourceMappingURL=template.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/routes/template.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;CACpD;AAuFD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,MAAM,CAE3E;AAED;+DAC+D;AAC/D,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAIzE"}