modelrig 0.1.0 → 0.3.0

package/dist/routes/cache-lint.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Prompt-stability lint — cache-aware-routing WS-C step 4 (spec §5.3,
+ * [Briefing §10]). A prefix cache only pays off when the CACHED PREFIX is
+ * stable across calls. A route template that interpolates a volatile value
+ * (a timestamp, a run id, a random nonce) high in the prompt shifts the prefix
+ * on every call, so the provider caches something that never recurs — the route
+ * pays the write premium forever and never reads a hit ("paying full price and
+ * don't know it", the §5.6 smell, caught statically here instead of after the money).
+ *
+ * v1 is a pure, conservative NAME heuristic over the declared `{{variable}}`
+ * references (the run-loop's stable prefix IS the route template — spec §5.3).
+ * It flags variables whose NAME reads volatile AND that appear before the
+ * template's stable tail. It does NOT inspect rendered values (it can't — the
+ * lint runs at load, before any input) and it never fails the load: a false
+ * positive must not block a legitimate route, so this warns. The prompt compiler
+ * + Prefix Stability Score (real per-token volatility telemetry) is the deferred
+ * successor ([Briefing Phase 5]); this is the cheap static precursor.
+ */
+export interface CacheLintWarning {
+    /** The offending variable name. */
+    readonly variable: string;
+    /** Character offset of the reference in the raw template. */
+    readonly index: number;
+    /** Human-readable, teach-not-scold message. */
+    readonly message: string;
+}
+/**
+ * Lint a route's raw system template for cache-hostile volatile interpolations.
+ * Pure and total. Returns one warning per volatile-named reference that sits
+ * before the stable tail; `[]` for a clean template.
+ *
+ * "Before the stable tail" (v1 approximation): a volatile reference in the first
+ * `headFraction` of the template shifts the cacheable prefix; one at the very
+ * end (after the bulk of the stable instructions) shifts only the tail and is
+ * harmless for prefix caching. We warn only on head references to keep the
+ * signal high — a `{{now}}` in a trailing "as of {{now}}" line is fine.
+ */
+export declare function lintCacheTemplate(template: string, opts?: {
+    readonly headFraction?: number;
+}): CacheLintWarning[];
+//# sourceMappingURL=cache-lint.d.ts.map

package/dist/routes/cache-lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-lint.d.ts","sourceRoot":"","sources":["../../src/routes/cache-lint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAmCH,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,gBAAgB,EAAE,CAmBpB"}

package/dist/routes/cache-lint.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Prompt-stability lint — cache-aware-routing WS-C step 4 (spec §5.3,
+ * [Briefing §10]). A prefix cache only pays off when the CACHED PREFIX is
+ * stable across calls. A route template that interpolates a volatile value
+ * (a timestamp, a run id, a random nonce) high in the prompt shifts the prefix
+ * on every call, so the provider caches something that never recurs — the route
+ * pays the write premium forever and never reads a hit ("paying full price and
+ * don't know it", the §5.6 smell, caught statically here instead of after the money).
+ *
+ * v1 is a pure, conservative NAME heuristic over the declared `{{variable}}`
+ * references (the run-loop's stable prefix IS the route template — spec §5.3).
+ * It flags variables whose NAME reads volatile AND that appear before the
+ * template's stable tail. It does NOT inspect rendered values (it can't — the
+ * lint runs at load, before any input) and it never fails the load: a false
+ * positive must not block a legitimate route, so this warns. The prompt compiler
+ * + Prefix Stability Score (real per-token volatility telemetry) is the deferred
+ * successor ([Briefing Phase 5]); this is the cheap static precursor.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lintCacheTemplate = lintCacheTemplate;
+/** Variable names that read as per-call-volatile. Deliberately broad on the
+ * volatile side (a warning is cheap; a silently un-cached route is not) but
+ * anchored to whole \b tokens so `updated_at_note` matches yet `runtime` does
+ * not falsely trip on "run". */
+const VOLATILE_NAME = new RegExp([
+    "\\btime(stamp)?\\b",
+    "\\bnow\\b",
+    "\\bdate(time)?\\b",
+    "run[_-]?id",
+    "request[_-]?id",
+    "trace[_-]?id",
+    "session[_-]?id",
+    "correlation[_-]?id",
+    "\\buuid\\b",
+    "\\bguid\\b",
+    "\\bnonce\\b",
+    "\\brandom\\b",
+    "\\brand\\b",
+    "\\bepoch\\b",
+    "\\bcurrent[_-]",
+    "generated[_-]?at",
+    "created[_-]?at",
+    "updated[_-]?at",
+].join("|"), "i");
+/** The `{{var}}` scanner from template.ts, duplicated as a global-match here so
+ * the lint can read each reference's POSITION (scanTemplateVariables dedupes to
+ * names only). Kept in sync with template.ts's VAR_TAG. */
+const VAR_TAG = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+/**
+ * Lint a route's raw system template for cache-hostile volatile interpolations.
+ * Pure and total. Returns one warning per volatile-named reference that sits
+ * before the stable tail; `[]` for a clean template.
+ *
+ * "Before the stable tail" (v1 approximation): a volatile reference in the first
+ * `headFraction` of the template shifts the cacheable prefix; one at the very
+ * end (after the bulk of the stable instructions) shifts only the tail and is
+ * harmless for prefix caching. We warn only on head references to keep the
+ * signal high — a `{{now}}` in a trailing "as of {{now}}" line is fine.
+ */
+function lintCacheTemplate(template, opts = {}) {
+    const headFraction = opts.headFraction ?? 0.75;
+    const headCutoff = Math.floor(template.length * headFraction);
+    const warnings = [];
+    for (const m of template.matchAll(VAR_TAG)) {
+        const name = m[1];
+        const index = m.index;
+        if (index >= headCutoff)
+            continue; // in the stable tail — harmless
+        if (!VOLATILE_NAME.test(name))
+            continue;
+        warnings.push({
+            variable: name,
+            index,
+            message: `route template interpolates \`{{${name}}}\` before the stable prompt tail — a per-call ` +
+                `value here shifts the cacheable prefix and defeats prompt caching (the route would pay ` +
+                `full price every call). Move volatile values to the end of the prompt, or drop them.`,
+        });
+    }
+    return warnings;
+}

package/dist/routes/loader.d.ts

@@ -4,6 +4,17 @@
  * resolves schema/prompt paths relative to the bundle file, freezes.
  */
 import type { RouteBundle } from "../types/route";
+/**
+ * CE-2 A5 co-item: warn (non-fatal) when a route's output schema has an ARRAY
+ * root. OpenAI strict structured output (`response_format: json_schema`, strict)
+ * requires a top-level OBJECT — an array-root schema cannot use strict
+ * enforcement on OpenAI candidates and silently falls back to non-strict there
+ * (the walkthrough §10 provider-matrix gap). The route still LOADS and serves as
+ * declared; the fix is to wrap the array in an object property so strict
+ * enforcement holds across every provider. Returns the warning line, or null.
+ * Pure — unit-tested directly.
+ */
+export declare function arrayRootSchemaWarning(route: string, outputSchema: object | null): string | null;
 /**
  * Structured config error thrown for any invalid bundle (never a raw Error).
  * Load-time problems are deliberately NOT RigFailures — the failure taxonomy
@@ -22,5 +33,42 @@ export interface LoadedRoutes {
     get(route: string): RouteBundle;
     list(): readonly RouteBundle[];
 }
+/**
+ * Merge two loaded route sets into one store — a UNION, collision is a loud
+ * error. Used to fold a deployment's bundled INTERNAL infra routes (e.g. the
+ * server's run-judge@v1 / analyst-summarize@v1) into the operator's configured
+ * routes without replacing them (index.ts createRig, extraRoutesDir). The
+ * reserved `@v<n>` infra namespace never collides with customer/demo routes;
+ * if it ever did, failing at boot is correct.
+ */
+/**
+ * Load a routes directory and OPTIONALLY union a second (deployment-bundled
+ * infra) directory into it — the one call createRig makes so the extra-routes
+ * merge does not grow index.ts. `extraDir` absent/empty ⇒ exactly loadRoutes.
+ */
+export declare function loadRoutesWithExtra(routesDir: string, extraDir?: string): LoadedRoutes;
+export declare function mergeLoadedRoutes(primary: LoadedRoutes, extra: LoadedRoutes): LoadedRoutes;
+/** One route file's structural-validation outcome (CE-6, spec §1 / walkthrough
+ * §8.7a). `route` is the parsed handle, or null when the bundle failed before a
+ * name could be read. */
+export interface RouteValidation {
+    readonly file: string;
+    readonly route: string | null;
+    readonly ok: boolean;
+    readonly problems: readonly string[];
+}
+/**
+ * Structurally validate every route bundle in a directory WITHOUT requiring any
+ * provider key (CE-6 `modelrig validate`). Unlike {@link loadRoutes}, one bad
+ * bundle does NOT abort the rest — each file is loaded independently and its
+ * outcome collected, so a newbie sees every problem in one pass. Duplicate route
+ * handles across files are reported per the later file. This deliberately does
+ * NOT run the serveable-candidate gate (serveability.ts) — that needs keys and
+ * stays fail-closed for SERVING; validation only checks authoring.
+ *
+ * A missing directory is still a hard error (nothing to validate) — it throws
+ * the same teaching RouteConfigError as loadRoutes.
+ */
+export declare function validateRoutesDir(routesDir: string): RouteValidation[];
 export declare function loadRoutes(routesDir: string): LoadedRoutes;
 //# sourceMappingURL=loader.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/routes/loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAKV,WAAW,EAGZ,MAAM,gBAAgB,CAAC;AAIxB;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAO;CAOxF;AAiCD,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC,IAAI,IAAI,SAAS,WAAW,EAAE,CAAC;CAChC;AAkXD,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CA2C1D"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/routes/loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAKV,WAAW,EAGZ,MAAM,gBAAgB,CAAC;AAMxB;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAWhG;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAO;CAOxF;AAiCD,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC,IAAI,IAAI,SAAS,WAAW,EAAE,CAAC;CAChC;AA4ZD;;;;;;;GAOG;AACH;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CAItF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,YAAY,CAyB1F;AAED;;yBAEyB;AACzB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CA6CtE;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CA2C1D"}

package/dist/routes/loader.js

@@ -6,6 +6,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RouteConfigError = void 0;
+exports.arrayRootSchemaWarning = arrayRootSchemaWarning;
+exports.loadRoutesWithExtra = loadRoutesWithExtra;
+exports.mergeLoadedRoutes = mergeLoadedRoutes;
+exports.validateRoutesDir = validateRoutesDir;
 exports.loadRoutes = loadRoutes;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -13,6 +17,30 @@ const yaml_1 = require("yaml");
 const failures_1 = require("../types/failures");
 const fingerprint_1 = require("../registry/fingerprint");
 const template_1 = require("./template");
+const cache_lint_1 = require("./cache-lint");
+const sampling_config_1 = require("./sampling-config");
+/**
+ * CE-2 A5 co-item: warn (non-fatal) when a route's output schema has an ARRAY
+ * root. OpenAI strict structured output (`response_format: json_schema`, strict)
+ * requires a top-level OBJECT — an array-root schema cannot use strict
+ * enforcement on OpenAI candidates and silently falls back to non-strict there
+ * (the walkthrough §10 provider-matrix gap). The route still LOADS and serves as
+ * declared; the fix is to wrap the array in an object property so strict
+ * enforcement holds across every provider. Returns the warning line, or null.
+ * Pure — unit-tested directly.
+ */
+function arrayRootSchemaWarning(route, outputSchema) {
+    if (outputSchema === null)
+        return null;
+    const rootType = outputSchema.type;
+    if (rootType !== "array")
+        return null;
+    return (`route "${route}" declares an output schema whose ROOT is type: "array". OpenAI strict ` +
+        `structured output requires a top-level object, so strict enforcement cannot apply on OpenAI ` +
+        `candidates (they fall back to non-strict there). Wrap the array in an object property ` +
+        `(e.g. { "type": "object", "properties": { "items": <your array> } }) to keep strict ` +
+        `enforcement across providers. The route loads and serves as declared.`);
+}
 /**
  * Structured config error thrown for any invalid bundle (never a raw Error).
  * Load-time problems are deliberately NOT RigFailures — the failure taxonomy
@@ -136,6 +164,7 @@ function parsePolicy(raw, problems) {
     if (typeof json !== "string" || !JSON_MODES.has(json)) {
         problems.push(`policy.json "${String(json)}" is not one of [native, json_mode]`);
     }
+    const sampling = (0, sampling_config_1.parseSampling)(raw.sampling, "policy.sampling", problems);
     if (problems.length > 0)
         return fallback;
     return Object.freeze({
@@ -143,6 +172,7 @@ function parsePolicy(raw, problems) {
         timeoutMs: timeoutMs,
         tier: tier,
         json: json,
+        ...(sampling !== undefined ? { sampling } : {}),
     });
 }
 /** "provider/model" string or {provider, model} mapping → CandidateSpec. */
@@ -328,6 +358,21 @@ function loadBundleFile(filePath) {
     if (typeof capture !== "boolean") {
         problems.push("capture must be a boolean");
     }
+    // Request-path caching opt-in (cache-aware-routing WS-C). Exactly one value
+    // is supported in v1 — `cache: auto`. Anything else is a config error (a typo
+    // must not silently ship an un-cached route). Gemini is NOT excluded here: a
+    // mixed-provider route may opt in, and the run-loop's policy gate skips
+    // gemini's request path (cache-stamp.ts) while its implicit hit rate still
+    // arrives passively — the exclusion is code-enforced, not author-policed.
+    let cache = false;
+    if (doc.cache !== undefined && doc.cache !== null) {
+        if (doc.cache === "auto") {
+            cache = true;
+        }
+        else {
+            problems.push(`cache "${String(doc.cache)}" is not supported — use "cache: auto" or omit it`);
+        }
+    }
     let groundingQuery;
     if (doc.grounding !== undefined) {
         if (!isRecord(doc.grounding) || typeof doc.grounding.query !== "string" || doc.grounding.query === "") {
@@ -377,6 +422,28 @@ function loadBundleFile(filePath) {
     if (problems.length > 0) {
         throw new RouteConfigError("invalid route bundle", { file: filePath, problems });
     }
+    // Prompt-stability lint (WS-C step 4, spec §5.3): a non-fatal warning — a
+    // volatile interpolation before the stable tail defeats prompt caching. Only
+    // meaningful once the route opted into `cache: auto`, so scoped to it to keep
+    // the signal high (same console-warn posture as manifest dimension warnings).
+    if (cache) {
+        for (const w of (0, cache_lint_1.lintCacheTemplate)(systemTemplate)) {
+            console.warn(`modelrig: route "${String(route)}" (${filePath}): ${w.message}`);
+        }
+    }
+    // CE-6 sampling advisory: a sub-1.0 temperature on a Gemini-3 candidate loads
+    // and is sent as declared, but Google recommends 1.0 for the family — warn so
+    // the choice is deliberate, never silent (spec §3/§6).
+    const geminiTempWarning = (0, sampling_config_1.gemini3LowTemperatureWarning)(route, policy, candidates);
+    if (geminiTempWarning !== null) {
+        console.warn(`modelrig: ${geminiTempWarning}`);
+    }
+    // CE-2 A5 co-item: an array-root schema cannot use OpenAI strict enforcement —
+    // warn once at load so the incompatibility is deliberate, never silent.
+    const arrayRootWarning = arrayRootSchemaWarning(route, outputSchema);
+    if (arrayRootWarning !== null) {
+        console.warn(`modelrig: ${arrayRootWarning}`);
+    }
     return Object.freeze({
         route: route,
         version: version,
@@ -390,12 +457,112 @@ function loadBundleFile(filePath) {
         ...(repair !== undefined ? { repair } : {}),
         variants: Object.freeze(variants),
         capture: capture === true,
+        cache,
         ...(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,
     });
 }
+/**
+ * Merge two loaded route sets into one store — a UNION, collision is a loud
+ * error. Used to fold a deployment's bundled INTERNAL infra routes (e.g. the
+ * server's run-judge@v1 / analyst-summarize@v1) into the operator's configured
+ * routes without replacing them (index.ts createRig, extraRoutesDir). The
+ * reserved `@v<n>` infra namespace never collides with customer/demo routes;
+ * if it ever did, failing at boot is correct.
+ */
+/**
+ * Load a routes directory and OPTIONALLY union a second (deployment-bundled
+ * infra) directory into it — the one call createRig makes so the extra-routes
+ * merge does not grow index.ts. `extraDir` absent/empty ⇒ exactly loadRoutes.
+ */
+function loadRoutesWithExtra(routesDir, extraDir) {
+    const base = loadRoutes(routesDir);
+    if (extraDir === undefined || extraDir === "")
+        return base;
+    return mergeLoadedRoutes(base, loadRoutes(extraDir));
+}
+function mergeLoadedRoutes(primary, extra) {
+    const byName = new Map();
+    for (const b of primary.list())
+        byName.set(b.route, b);
+    for (const b of extra.list()) {
+        if (byName.has(b.route)) {
+            throw new RouteConfigError(`duplicate route "${b.route}" — an internal infra route collides with a configured route`);
+        }
+        byName.set(b.route, b);
+    }
+    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()]);
+        },
+    };
+}
+/**
+ * Structurally validate every route bundle in a directory WITHOUT requiring any
+ * provider key (CE-6 `modelrig validate`). Unlike {@link loadRoutes}, one bad
+ * bundle does NOT abort the rest — each file is loaded independently and its
+ * outcome collected, so a newbie sees every problem in one pass. Duplicate route
+ * handles across files are reported per the later file. This deliberately does
+ * NOT run the serveable-candidate gate (serveability.ts) — that needs keys and
+ * stays fail-closed for SERVING; validation only checks authoring.
+ *
+ * A missing directory is still a hard error (nothing to validate) — it throws
+ * the same teaching RouteConfigError as loadRoutes.
+ */
+function validateRoutesDir(routesDir) {
+    if (!(0, node_fs_1.existsSync)(routesDir)) {
+        throw new RouteConfigError(`routes directory not found: ${routesDir}\n\n` +
+            "There are no route bundles to validate here. Create your first with\n" +
+            "  modelrig init .          draft routes from the provider calls in this repo\n" +
+            "or point elsewhere 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 results = [];
+    const seen = new Map();
+    for (const file of files) {
+        try {
+            const bundle = loadBundleFile(file);
+            const prior = seen.get(bundle.route);
+            if (prior !== undefined) {
+                results.push({
+                    file,
+                    route: bundle.route,
+                    ok: false,
+                    problems: [`duplicate route "${bundle.route}" — already declared in ${prior}`],
+                });
+                continue;
+            }
+            seen.set(bundle.route, file);
+            results.push({ file, route: bundle.route, ok: true, problems: [] });
+        }
+        catch (err) {
+            if (err instanceof RouteConfigError) {
+                results.push({
+                    file,
+                    route: null,
+                    ok: false,
+                    problems: err.problems.length > 0 ? err.problems : [err.message],
+                });
+            }
+            else {
+                results.push({ file, route: null, ok: false, problems: [err.message] });
+            }
+        }
+    }
+    return results;
+}
 function loadRoutes(routesDir) {
     if (!(0, node_fs_1.existsSync)(routesDir)) {
         // First-run moment (Phase 5 WS4): this is the most likely error a new

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]);
+        },
+    };
+}