modelrig 0.8.1 → 0.10.0

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

@@ -1 +1 @@
-{"version":3,"file":"objective-loader.d.ts","sourceRoot":"","sources":["../../src/routes/objective-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EAGb,cAAc,EACd,UAAU,EACX,MAAM,gBAAgB,CAAC;AAExB;;2EAE2E;AAC3E,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,QAAQ,EAAE,MAAM,EAAE,GACjB;IAAE,SAAS,CAAC,EAAE,cAAc,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IAAC,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAe9F;AAoCD;mEACmE;AACnE,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,cAAc,GAAG,SAAS,CAqD3F;AAqCD;;2EAE2E;AAC3E,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,QAAQ,EAAE,MAAM,EAAE,GACjB,aAAa,GAAG,SAAS,CAwE3B;AAiCD;uCACuC;AACvC,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,UAAU,EAAE,GAAG,SAAS,CAqCpG;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAUvG"}
+{"version":3,"file":"objective-loader.d.ts","sourceRoot":"","sources":["../../src/routes/objective-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EAGb,cAAc,EACd,UAAU,EACX,MAAM,gBAAgB,CAAC;AAExB;;2EAE2E;AAC3E,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,QAAQ,EAAE,MAAM,EAAE,GACjB;IACD,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACpC,KAAK,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACnC,CAmBA;AAYD,iFAAiF;AACjF,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;kFAGkF;AAClF,wBAAgB,eAAe,CAC7B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAAE,GACjB;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAavC;AA0BD;mEACmE;AACnE,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,cAAc,GAAG,SAAS,CAqD3F;AAqCD;;2EAE2E;AAC3E,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,QAAQ,EAAE,MAAM,EAAE,GACjB,aAAa,GAAG,SAAS,CA+F3B;AAoED;uCACuC;AACvC,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,UAAU,EAAE,GAAG,SAAS,CAqCpG;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAUvG"}

package/dist/routes/objective-loader.js

@@ -7,7 +7,9 @@
  * unit-tested directly.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GRADE_PASS_THRESHOLD = void 0;
 exports.parseRb1Fields = parseRb1Fields;
+exports.parseGradeBlock = parseGradeBlock;
 exports.parseObjective = parseObjective;
 exports.parseBakeoffConfig = parseBakeoffConfig;
 exports.parseValueChecks = parseValueChecks;
@@ -19,6 +21,9 @@ function parseRb1Fields(doc, route, candidates, problems) {
     const objective = parseObjective(doc.objective, problems);
     const bakeoff = parseBakeoffConfig(doc.bakeoff, candidates, problems);
     const valueChecks = parseValueChecks(doc.value_checks, problems);
+    // Grade primitive (R2): the optional per-route pass threshold rides the same
+    // additive-route-knobs parse, keeping loader.ts under the LOC cap.
+    const grade = parseGradeBlock(doc.grade, problems);
     // Only nag routes that OPT INTO RB-1 (declare objective/bakeoff) but omit a
     // bound — a legacy route with neither block is not using regret bake-offs.
     if (objective !== undefined || bakeoff !== undefined) {
@@ -30,6 +35,7 @@ function parseRb1Fields(doc, route, candidates, problems) {
         ...(objective !== undefined ? { objective } : {}),
         ...(bakeoff !== undefined ? { bakeoff } : {}),
         ...(valueChecks !== undefined ? { valueChecks } : {}),
+        ...(grade !== undefined ? { grade } : {}),
     };
 }
 const OBJECTIVE_MODES = new Set([
@@ -40,6 +46,28 @@ const OBJECTIVE_MODES = new Set([
 function isRecord(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
+/** Default grade pass threshold when a route declares no `grade:` block (R2). */
+exports.DEFAULT_GRADE_PASS_THRESHOLD = 0.5;
+/** Parse the optional `grade:` block (grade primitive, R2). Currently one knob,
+ * `pass_threshold` (0–1). Declared + validated here but UNREAD until GP-2 wires
+ * verdict derivation. Absent ⇒ undefined (⇒ the default 0.5 is applied downstream).
+ * A malformed value pushes a teaching problem, exactly like every other field. */
+function parseGradeBlock(raw, problems) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        problems.push("grade must be an object { pass_threshold: <0..1> }");
+        return undefined;
+    }
+    const t = raw.pass_threshold;
+    if (t === undefined)
+        return undefined;
+    if (typeof t !== "number" || !Number.isFinite(t) || t < 0 || t > 1) {
+        problems.push(`grade.pass_threshold must be a number in [0, 1], got ${String(t)}`);
+        return undefined;
+    }
+    return { passThreshold: t };
+}
 function parsePriceCeiling(raw, field, problems) {
     if (raw === undefined || raw === null)
         return undefined;
@@ -222,15 +250,69 @@ function parseBakeoffConfig(raw, candidates, problems) {
                 pairwise = { judge: pwJudge };
         }
     }
+    // Q1 regret monitor (spec §5) + N4 upgrade watch (spec §4) — additive, optional.
+    const regretMonitor = parseRegretMonitor(raw.regret_monitor, problems);
+    let upgradeWatch;
+    if (raw.upgrade_watch !== undefined) {
+        if (typeof raw.upgrade_watch !== "boolean") {
+            problems.push("bakeoff.upgrade_watch must be a boolean");
+        }
+        else {
+            upgradeWatch = raw.upgrade_watch;
+        }
+    }
+    // Teaching (spec §3 opt-in rule): a monitor/upgrade-watch with NO reference has
+    // nothing to measure against — warn (non-fatal), mirroring missingBoundWarning.
+    const noReference = reference === undefined;
+    if (noReference && (regretMonitor?.enabled === true || upgradeWatch === true)) {
+        console.warn(`modelrig: route bakeoff sets ${regretMonitor?.enabled === true ? "regret_monitor.enabled" : "upgrade_watch"}` +
+            " but declares no bakeoff.reference — there is no ceiling to measure regret against, so neither the" +
+            " regret monitor nor the up-swap watch can fire. Declare bakeoff.reference (auto or provider/model).");
+    }
     const out = {
         ...(reference !== undefined ? { reference } : {}),
         ...(referenceAllowExternal ? { referenceAllowExternal: true } : {}),
         ...(referenceEnvelopeUsd !== undefined ? { referenceEnvelopeUsd } : {}),
         ...(judge !== undefined ? { judge } : {}),
         ...(pairwise !== undefined ? { pairwise } : {}),
+        ...(regretMonitor !== undefined ? { regretMonitor } : {}),
+        ...(upgradeWatch !== undefined ? { upgradeWatch } : {}),
     };
     return Object.freeze(out);
 }
+/** Parse `bakeoff.regret_monitor: { enabled, sample_n?, window_days?,
+ * baseline_days? }` (spec §5). Absent ⇒ undefined. Each numeric bound must be a
+ * positive integer when present. */
+function parseRegretMonitor(raw, problems) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        problems.push("bakeoff.regret_monitor must be an object { enabled, sample_n?, window_days?, baseline_days? }");
+        return undefined;
+    }
+    if (typeof raw.enabled !== "boolean") {
+        problems.push("bakeoff.regret_monitor.enabled must be a boolean");
+        return undefined;
+    }
+    const posInt = (v, field) => {
+        if (v === undefined)
+            return undefined;
+        if (typeof v !== "number" || !Number.isInteger(v) || v < 1) {
+            problems.push(`bakeoff.regret_monitor.${field} must be a positive integer`);
+            return undefined;
+        }
+        return v;
+    };
+    const sampleN = posInt(raw.sample_n, "sample_n");
+    const windowDays = posInt(raw.window_days, "window_days");
+    const baselineDays = posInt(raw.baseline_days, "baseline_days");
+    return Object.freeze({
+        enabled: raw.enabled,
+        ...(sampleN !== undefined ? { sampleN } : {}),
+        ...(windowDays !== undefined ? { windowDays } : {}),
+        ...(baselineDays !== undefined ? { baselineDays } : {}),
+    });
+}
 /** Parse a `{ model, max_samples }` judge spec (shared by `bakeoff.judge` and
  * `bakeoff.pairwise.judge`). Enforces #223 F3: the judge model must be a declared
  * candidate. Returns the parsed spec, or undefined when absent/invalid (problems

package/dist/routes/output-loader.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Route OUTPUT contract at load — the `schema:` file reader and the `output:`
+ * block (GitLab issue #1, incident 2026-10-11: a prose route had no way to say
+ * "my output is not JSON" and was rejected `content_invalid` on every call).
+ *
+ * Carved out of routes/loader.ts (which sits at the 700-LOC cap, dev-rule P1):
+ * `readSchema` is a PURE MOVE; `parseOutputBlock` is new.
+ *
+ * YAML forms accepted for `output:`:
+ *   (absent)                          → json  (the default; byte-identical)
+ *   output: json                      → json  (explicit; identical to absent)
+ *   output: text                      → text  (prose/markdown, returned verbatim)
+ *   output: { kind: text, min_chars: N } → text with a declared length floor
+ *   output: { kind: json }            → json
+ *
+ * The parsed result OMITS `outputKind` for json so a JSON route's bundle (and
+ * its `bundle_sha`) is unchanged; only `text` is ever carried.
+ */
+import type { RepairPolicy, Requirement, RouteVariant } from "../types/route";
+export declare const OUTPUT_KINDS: ReadonlySet<string>;
+export declare const PROSE_DOCS_ANCHOR = "route-bundles.md#prose-and-markdown-output-output-text";
+/** Resolve + parse the bundle's `schema:` file (null / absent ⇒ schema-less). */
+export declare function readSchema(schemaRaw: unknown, bundleDir: string, problems: string[]): object | null;
+export interface ParsedOutputBlock {
+    /** Present ONLY for `text` (json ⇒ omitted ⇒ byte-identical bundle). */
+    readonly outputKind?: "text";
+    readonly outputMinChars?: number;
+}
+/** What the loader already parsed that an `output: text` declaration must be
+ * consistent with — each conflict is a LOAD error that teaches, never a run-time
+ * surprise. */
+export interface OutputBlockContext {
+    readonly outputSchema: object | null;
+    readonly schemaDeclared: boolean;
+    readonly require: readonly Requirement[];
+    readonly repair: RepairPolicy | undefined;
+    readonly variants: readonly RouteVariant[];
+}
+/** Parse the bundle's `output:` key. Pushes teaching problems; returns `{}` for
+ * json (absent / explicit) so the bundle spread adds nothing. */
+export declare function parseOutputBlock(raw: unknown, ctx: OutputBlockContext, problems: string[]): ParsedOutputBlock;
+//# sourceMappingURL=output-loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"output-loader.d.ts","sourceRoot":"","sources":["../../src/routes/output-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAc,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE1F,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAAyC,CAAC;AAGvF,eAAO,MAAM,iBAAiB,2DAA2D,CAAC;AAM1F,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAsBnG;AAED,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;eAEe;AACf,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAED;iEACiE;AACjE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAqD7G"}

package/dist/routes/output-loader.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Route OUTPUT contract at load — the `schema:` file reader and the `output:`
+ * block (GitLab issue #1, incident 2026-10-11: a prose route had no way to say
+ * "my output is not JSON" and was rejected `content_invalid` on every call).
+ *
+ * Carved out of routes/loader.ts (which sits at the 700-LOC cap, dev-rule P1):
+ * `readSchema` is a PURE MOVE; `parseOutputBlock` is new.
+ *
+ * YAML forms accepted for `output:`:
+ *   (absent)                          → json  (the default; byte-identical)
+ *   output: json                      → json  (explicit; identical to absent)
+ *   output: text                      → text  (prose/markdown, returned verbatim)
+ *   output: { kind: text, min_chars: N } → text with a declared length floor
+ *   output: { kind: json }            → json
+ *
+ * The parsed result OMITS `outputKind` for json so a JSON route's bundle (and
+ * its `bundle_sha`) is unchanged; only `text` is ever carried.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROSE_DOCS_ANCHOR = exports.OUTPUT_KINDS = void 0;
+exports.readSchema = readSchema;
+exports.parseOutputBlock = parseOutputBlock;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.OUTPUT_KINDS = new Set(["json", "text"]);
+const OUTPUT_BLOCK_KEYS = new Set(["kind", "min_chars"]);
+exports.PROSE_DOCS_ANCHOR = "route-bundles.md#prose-and-markdown-output-output-text";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Resolve + parse the bundle's `schema:` file (null / absent ⇒ schema-less). */
+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;
+    }
+}
+/** Parse the bundle's `output:` key. Pushes teaching problems; returns `{}` for
+ * json (absent / explicit) so the bundle spread adds nothing. */
+function parseOutputBlock(raw, ctx, problems) {
+    if (raw === undefined || raw === null)
+        return {};
+    let kind;
+    let minChars;
+    if (typeof raw === "string") {
+        kind = raw;
+    }
+    else if (isRecord(raw)) {
+        for (const key of Object.keys(raw)) {
+            if (!OUTPUT_BLOCK_KEYS.has(key)) {
+                problems.push(`output.${key} is not a known key — the block is {kind: json|text, min_chars?: integer >= 1}`);
+            }
+        }
+        kind = raw.kind;
+        if (raw.min_chars !== undefined) {
+            if (typeof raw.min_chars !== "number" || !Number.isInteger(raw.min_chars) || raw.min_chars < 1) {
+                problems.push("output.min_chars must be an integer >= 1");
+            }
+            else {
+                minChars = raw.min_chars;
+            }
+        }
+    }
+    else {
+        problems.push(`output must be "json", "text", or {kind, min_chars?} — got ${JSON.stringify(raw)}`);
+        return {};
+    }
+    if (typeof kind !== "string" || !exports.OUTPUT_KINDS.has(kind)) {
+        problems.push(`output "${String(kind)}" is not one of [json, text] — write \`output: text\` for a prose/markdown route, ` +
+            `or omit it for JSON (the default)`);
+        return {};
+    }
+    if (kind === "json") {
+        if (minChars !== undefined)
+            problems.push("output.min_chars applies to output: text only — a JSON route conforms to its schema instead");
+        return {};
+    }
+    // kind === "text": the prose contract must not contradict the JSON machinery.
+    if (ctx.schemaDeclared || ctx.outputSchema !== null) {
+        problems.push("output: text cannot be combined with schema: — a prose route has no JSON Schema to conform to. " +
+            "Remove `schema:` (or set it to null), or drop `output: text` to serve JSON");
+    }
+    if (ctx.require.includes("schema_conformant")) {
+        problems.push("output: text cannot require schema_conformant — there is no schema; remove it from `require`");
+    }
+    const repairDeclared = ctx.repair !== undefined || ctx.variants.some((v) => v.repair !== undefined);
+    if (repairDeclared) {
+        problems.push("repair: is the JSON repair rung and never runs on an output: text route — remove it (a prose " +
+            "response that fails min_chars is retried from the content_invalid budget instead)");
+    }
+    return { outputKind: "text", ...(minChars !== undefined ? { outputMinChars: minChars } : {}) };
+}

package/dist/routes/prompt-loader.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The bundle's `prompt:` block at load — `prompt.system`, the per-call
+ * `prompt.user` (GitLab issue #5, R1), and `prompt.variables`.
+ *
+ * Carved out of routes/loader.ts (which sits at the 700-LOC cap, dev-rule P1):
+ * the `prompt.system` + `variables` handling is a PURE MOVE; `prompt.user` and
+ * the cache/system-only advisory are new.
+ *
+ * YAML forms accepted for `prompt:`:
+ *   prompt: { system: <path>, variables: [...] }                 → today (byte-identical)
+ *   prompt: { system: <path>, user: <path>, variables: [...] }   → system + per-call user turn
+ *   prompt: { user: <path>, variables: [...] }                   → user turn only (empty system)
+ *
+ * Both templates are files relative to the bundle (same rule as `schema:`);
+ * both render with the same variables, capability conditionals and `x-trust`
+ * removal. `prompt.user` must be a non-empty file — an empty user turn next to
+ * a cache handle would send the handle and nothing else, the exact trap R1
+ * closes.
+ */
+import type { CandidateSpec } from "../types/route";
+export declare const CACHE_PROMPT_DOCS_ANCHOR = "caching-lifecycle.md#a-cache-handle-changes-where-the-template-is-delivered";
+export interface ParsedPromptBlock {
+    readonly systemTemplate: string;
+    /** Present ONLY when `prompt.user` was declared (absent ⇒ byte-identical bundle). */
+    readonly userTemplate?: string;
+    readonly variables: readonly string[];
+    readonly variableTrust?: Record<string, "untrusted">;
+}
+/**
+ * Parse the bundle's `prompt:` block. `prompt.system` stays REQUIRED unless
+ * `prompt.user` is declared (a user-turn-only route has an empty system
+ * template — the shape a Gemini cache handle wants, since the cache already
+ * holds the system content). Returns `systemTemplate: ""` on any problem so the
+ * caller's later checks stay total; the collected problems fail the load.
+ */
+export declare function parsePromptBlock(raw: unknown, bundleDir: string, problems: string[]): ParsedPromptBlock;
+/**
+ * Issue #5 (R1) advisory, P4 "errors teach": a route that opts into caching
+ * (`cache: auto`) AND has a Gemini candidate AND renders a non-empty system
+ * template with NO `prompt.user` is the shape that loses content the moment a
+ * customer passes a Gemini cache handle on `rig.run` — the handle forbids
+ * `systemInstruction`, so the rendered template is delivered as the user turn
+ * (never dropped), but the author almost certainly meant the cache to hold the
+ * prefix and `prompt.user` to hold the delta. Warn once at load naming the
+ * rule. Non-fatal: the route loads and serves as declared. Pure — unit-tested
+ * directly. Returns the warning line, or null.
+ */
+export declare function cachedRouteSystemOnlyWarning(route: string, cache: boolean, candidates: readonly CandidateSpec[], systemTemplate: string, userTemplate: string | undefined): string | null;
+//# sourceMappingURL=prompt-loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-loader.d.ts","sourceRoot":"","sources":["../../src/routes/prompt-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,eAAO,MAAM,wBAAwB,gFAAgF,CAAC;AAMtH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,qFAAqF;IACrF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACtD;AAkBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAiCvG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAYf"}

package/dist/routes/prompt-loader.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * The bundle's `prompt:` block at load — `prompt.system`, the per-call
+ * `prompt.user` (GitLab issue #5, R1), and `prompt.variables`.
+ *
+ * Carved out of routes/loader.ts (which sits at the 700-LOC cap, dev-rule P1):
+ * the `prompt.system` + `variables` handling is a PURE MOVE; `prompt.user` and
+ * the cache/system-only advisory are new.
+ *
+ * YAML forms accepted for `prompt:`:
+ *   prompt: { system: <path>, variables: [...] }                 → today (byte-identical)
+ *   prompt: { system: <path>, user: <path>, variables: [...] }   → system + per-call user turn
+ *   prompt: { user: <path>, variables: [...] }                   → user turn only (empty system)
+ *
+ * Both templates are files relative to the bundle (same rule as `schema:`);
+ * both render with the same variables, capability conditionals and `x-trust`
+ * removal. `prompt.user` must be a non-empty file — an empty user turn next to
+ * a cache handle would send the handle and nothing else, the exact trap R1
+ * closes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CACHE_PROMPT_DOCS_ANCHOR = void 0;
+exports.parsePromptBlock = parsePromptBlock;
+exports.cachedRouteSystemOnlyWarning = cachedRouteSystemOnlyWarning;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const screen_loader_1 = require("./screen-loader");
+exports.CACHE_PROMPT_DOCS_ANCHOR = "caching-lifecycle.md#a-cache-handle-changes-where-the-template-is-delivered";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Read a template file named by `prompt.<key>` relative to the bundle. Pushes
+ * a teaching problem and returns null when the key is not a path or the file is
+ * missing. */
+function readTemplateFile(raw, key, bundleDir, problems) {
+    if (typeof raw !== "string" || raw === "") {
+        problems.push(`prompt.${key} must be a relative path`);
+        return null;
+    }
+    const path = (0, node_path_1.resolve)(bundleDir, raw);
+    if (!(0, node_fs_1.existsSync)(path)) {
+        problems.push(`prompt.${key} file not found: ${raw}`);
+        return null;
+    }
+    return (0, node_fs_1.readFileSync)(path, "utf8");
+}
+/**
+ * Parse the bundle's `prompt:` block. `prompt.system` stays REQUIRED unless
+ * `prompt.user` is declared (a user-turn-only route has an empty system
+ * template — the shape a Gemini cache handle wants, since the cache already
+ * holds the system content). Returns `systemTemplate: ""` on any problem so the
+ * caller's later checks stay total; the collected problems fail the load.
+ */
+function parsePromptBlock(raw, bundleDir, problems) {
+    if (!isRecord(raw)) {
+        problems.push("prompt.system must be a relative path");
+        return { systemTemplate: "", variables: [] };
+    }
+    const userDeclared = raw.user !== undefined && raw.user !== null;
+    let systemTemplate = "";
+    if (raw.system !== undefined && raw.system !== null) {
+        systemTemplate = readTemplateFile(raw.system, "system", bundleDir, problems) ?? "";
+    }
+    else if (!userDeclared) {
+        problems.push("prompt.system must be a relative path");
+    }
+    let userTemplate;
+    if (userDeclared) {
+        const text = readTemplateFile(raw.user, "user", bundleDir, problems);
+        if (text !== null) {
+            if (text.trim() === "") {
+                problems.push(`prompt.user file is empty: ${String(raw.user)} — the user turn must carry content (with a cache handle ` +
+                    `it is the ONLY per-call content the model sees; omit prompt.user to keep the fixed trigger)`);
+            }
+            else {
+                userTemplate = text;
+            }
+        }
+    }
+    const parsed = (0, screen_loader_1.parseVariables)(raw.variables ?? [], problems);
+    return {
+        systemTemplate,
+        ...(userTemplate !== undefined ? { userTemplate } : {}),
+        variables: parsed.names,
+        ...(parsed.trust !== undefined ? { variableTrust: parsed.trust } : {}),
+    };
+}
+/**
+ * Issue #5 (R1) advisory, P4 "errors teach": a route that opts into caching
+ * (`cache: auto`) AND has a Gemini candidate AND renders a non-empty system
+ * template with NO `prompt.user` is the shape that loses content the moment a
+ * customer passes a Gemini cache handle on `rig.run` — the handle forbids
+ * `systemInstruction`, so the rendered template is delivered as the user turn
+ * (never dropped), but the author almost certainly meant the cache to hold the
+ * prefix and `prompt.user` to hold the delta. Warn once at load naming the
+ * rule. Non-fatal: the route loads and serves as declared. Pure — unit-tested
+ * directly. Returns the warning line, or null.
+ */
+function cachedRouteSystemOnlyWarning(route, cache, candidates, systemTemplate, userTemplate) {
+    if (!cache)
+        return null;
+    if (userTemplate !== undefined)
+        return null;
+    if (systemTemplate.trim() === "")
+        return null;
+    if (!candidates.some((c) => c.provider === "gemini"))
+        return null;
+    return (`route "${route}" declares cache: with a Gemini candidate, a non-empty prompt.system and no prompt.user. ` +
+        `A Gemini cache handle (rig.run(..., { cache: { key, provider: "gemini" } })) forbids systemInstruction, so ` +
+        `on a cached dispatch the rendered system template is delivered AS THE USER TURN (prompt_delivery: ` +
+        `"user+cache") — never dropped, but probably not what you meant. Put the shared prefix in the cache ` +
+        `resource and the per-call delta in a \`prompt.user\` template (see ${exports.CACHE_PROMPT_DOCS_ANCHOR}).`);
+}

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

@@ -25,6 +25,9 @@
  * schema it fingerprints.
  */
 import type { LoadedRoutes } from "./loader";
+import type { ScreenPolicy } from "../screen/types";
+import type { ResolvedMaskPolicy } from "../mask/types";
+import type { Manifest } from "../prompts/manifest";
 import type { CandidateSpec, Preference, RepairPolicy, Requirement, RouteBundle, RoutePolicy, RouteVariant } from "../types/route";
 /**
  * The canonical, JSON-serialisable form of a resolved route bundle. Every field
@@ -37,21 +40,87 @@ export interface ResolvedRouteBundle {
     readonly version: number;
     /** Resolved, parsed JSON Schema (null = unstructured route). Inlined at sync. */
     readonly outputSchema: object | null;
+    /** Issue #1 — `output: text`. Carried ONLY as `"text"` (a json route omits the
+     * key, so its `bundle_sha` is unchanged); the hosted/mirror lane rebuilds the
+     * same prose contract and never JSON-parses the response. `outputMinChars` is
+     * the declared floor, text routes only. Absent ⇒ json ⇒ byte-identical. */
+    readonly outputKind?: "text";
+    readonly outputMinChars?: number;
     readonly candidates: readonly CandidateSpec[];
     readonly require: readonly Requirement[];
     readonly prefer: readonly Preference[];
     /** Raw template text — the prompt FILE, inlined at sync. */
     readonly systemTemplate: string;
+    /** Issue #5 (R1) — the per-call `prompt.user` template, inlined at sync and
+     * carried ONLY when declared (absent ⇒ the fixed trigger ⇒ unchanged
+     * `bundle_sha`), so the hosted/mirror lane renders the same user turn and a
+     * cache handle composes there too. */
+    readonly userTemplate?: string;
     readonly variables: readonly string[];
     readonly policy: RoutePolicy;
     readonly repair?: RepairPolicy;
     readonly variants: readonly RouteVariant[];
     readonly capture: boolean;
     readonly groundingQuery?: string;
+    /** S1 grounding assembly mode (`legacy` | `spotlight`). Carried so a route's
+     * spotlight opt-in survives to the hosted (mirror) lane. Absent ⇒ legacy. */
+    readonly groundingAssembly?: "legacy" | "spotlight";
+    /** S2 per-variable `x-trust` annotation. S3 mirror plumbing (spec §11.3, gap
+     * #3): previously DROPPED on the round-trip, so any bundle-borne trust signal
+     * was `undefined` on every mirror-lane run. Carried now so route `x-trust`
+     * annotations survive to the hosted lane. Absent ⇒ every variable stays `semi`
+     * (byte-identical). */
+    readonly variableTrust?: Readonly<Record<string, "untrusted">>;
+    /** SC-1b mirror fix (spec §4, SC-1b req 1 — the #322 QA finding). Previously
+     * DROPPED on the round-trip: `route.screen` was `undefined` on every
+     * mirror-lane run, so screening was silently INERT (a fail-open) — an
+     * `enforce` route did not screen at all on the hosted lane. Carried now as the
+     * RAW `ScreenPolicy` (the serialisable `.policy` — the built detector closures
+     * on `ResolvedScreenPolicy` cannot cross the wire); `bundleFromResolved`
+     * RE-RESOLVES it with `resolveScreenPolicy`, which always rebuilds the T0
+     * pattern detector deterministically. Absent ⇒ no screening (byte-identical).
+     * A `screen: enforce` route that relies on a T1 `classifier:` detector is
+     * REFUSED at export by {@link assertMirrorSafe} (weights can't be guaranteed on
+     * the gateway ⇒ it would silently degrade to T0 — never a silent inert
+     * enforce). */
+    readonly screenPolicy?: ScreenPolicy;
+    /** SC-1b mirror fix (spec §3, SC-1b req 1). The `mask:` block had the IDENTICAL
+     * drop gap — `route.mask` was `undefined` on the mirror lane, so masking was
+     * silently INERT. Carried now as the FULLY-RESOLVED policy: unlike screen, a
+     * `ResolvedMaskPolicy` has its dictionary `entries` INLINED and is fully
+     * serialisable, so it is passed straight through (no re-resolve, no filesystem
+     * on the gateway) and re-materialises byte-identically — so `mask: block`
+     * always re-resolves on the mirror and needs no export refusal. Absent ⇒ no
+     * masking (byte-identical). */
+    readonly mask?: ResolvedMaskPolicy;
+    /** PSR-2 (spec §2.1/§3) — the served prompt's assembly manifest (structure-only).
+     * A promote writes the promoted `prompt_versions` row's `manifest` through into
+     * `routes.bundle` alongside the `systemTemplate`, and recomputes `bundle_sha`
+     * over this whole object — so the served projection carries the manifest the
+     * client-fill engine (PSR-2b) resolves against. Absent ⇒ no PSR manifest
+     * (byte-identical to a pre-PSR mirror). Additive & optional. */
+    readonly manifest?: Manifest;
 }
 /** 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;
+/**
+ * Refuse-on-export guard (SC-1b req 1 — the #322 QA finding). A route that
+ * declares `screen: enforce` MUST be guaranteed to re-resolve its enforcement on
+ * the hosted (mirror) lane, or the hosted lane silently fails open. The mirror
+ * rebuilds the screen policy with `resolveScreenPolicy`, which ALWAYS builds the
+ * T0 pattern detector deterministically (no filesystem) — so a pure-T0 enforce
+ * policy re-resolves identically and mirrors safely. A T1 `classifier:` detector,
+ * though, depends on gateway-local weights the mirror cannot guarantee: there it
+ * would DEGRADE to T0 SILENTLY, weaker than what was authored and proven. Rather
+ * than ship a silently-degraded enforce we REFUSE at export with a teaching
+ * error. `mask` needs no guard: its resolved policy (dictionary entries inlined)
+ * crosses the wire whole and re-materialises identically.
+ *
+ * Called from the exporter (`buildExportedRouteMirrors`) — a hard failure at
+ * SYNC, on the developer's machine, never a silent inert enforce at request.
+ */
+export declare function assertMirrorSafe(bundle: RouteBundle): void;
 /** 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

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

@@ -1 +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"}
+{"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;AAG7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,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;;;+EAG2E;IAC3E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,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;;;0CAGsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,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;IACjC;iFAC6E;IAC7E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;IACpD;;;;2BAIuB;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAC/D;;;;;;;;;;;mBAWe;IACf,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;;;;mCAO+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC;IACnC;;;;;oEAKgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC9B;AAED;sEACsE;AACtE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,mBAAmB,CA8B3E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAe1D;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,CAoE5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAclE"}