modelrig 0.4.0 → 0.6.0

package/dist/routes/loader-warnings.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Non-fatal loader advisories — extracted from loader.ts (kept it under the
+ * 700-LOC cap). Each is a pure function returning a warning line or null; the
+ * loader console.warns them after a bundle loads. Unit-tested directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.arrayRootSchemaWarning = arrayRootSchemaWarning;
+exports.unreferencedTrialCandidatesWarning = unreferencedTrialCandidatesWarning;
+/**
+ * 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.
+ */
+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.`);
+}
+/**
+ * Declare-first dead-declaration warning (routing-console spec §4.4): a `trial`
+ * candidate that no variant references can never be reached — not live (trial
+ * candidates are dropped on every live path) and not in a bake-off (a bake-off
+ * replays a NAMED variant, and no variant narrows to it). Warn so the author
+ * either adds the `trial-<provider>-<model>` variant the declare flow emits or
+ * removes the dangling candidate. Non-fatal (the route still loads and serves
+ * its live candidates as declared). Pure — unit-tested directly. Returns the
+ * warning line, or null when every trial candidate is referenced.
+ */
+function unreferencedTrialCandidatesWarning(route, candidates, variants) {
+    const referenced = new Set();
+    for (const v of variants) {
+        for (const c of v.candidates ?? [])
+            referenced.add(`${c.provider}/${c.model}`);
+    }
+    const dangling = candidates
+        .filter((c) => c.trial === true && !referenced.has(`${c.provider}/${c.model}`))
+        .map((c) => `${c.provider}/${c.model}`);
+    if (dangling.length === 0)
+        return null;
+    return (`route "${route}" declares trial candidate(s) [${dangling.join(", ")}] that no variant references. ` +
+        `A trial candidate is declared but never served live; it is only reachable through a bake-off of a ` +
+        `variant that narrows to it. Add a variant (e.g. { name: "trial-${dangling[0].replace("/", "-")}", ` +
+        `candidates: [<that candidate>] }) to bake it off, or remove the dangling declaration.`);
+}

package/dist/routes/loader.d.ts

@@ -4,17 +4,7 @@
  * 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;
+export { arrayRootSchemaWarning, unreferencedTrialCandidatesWarning } from "./loader-warnings";
 /**
  * Structured config error thrown for any invalid bundle (never a raw Error).
  * Load-time problems are deliberately NOT RigFailures — the failure taxonomy

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;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"}
+{"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;AAUxB,OAAO,EAAE,sBAAsB,EAAE,kCAAkC,EAAE,MAAM,mBAAmB,CAAC;AAE/F;;;;;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;AAucD;;;;;;;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

@@ -5,8 +5,7 @@
  * resolves schema/prompt paths relative to the bundle file, freezes.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RouteConfigError = void 0;
-exports.arrayRootSchemaWarning = arrayRootSchemaWarning;
+exports.RouteConfigError = exports.unreferencedTrialCandidatesWarning = exports.arrayRootSchemaWarning = void 0;
 exports.loadRoutesWithExtra = loadRoutesWithExtra;
 exports.mergeLoadedRoutes = mergeLoadedRoutes;
 exports.validateRoutesDir = validateRoutesDir;
@@ -19,28 +18,13 @@ 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.`);
-}
+const loader_warnings_1 = require("./loader-warnings");
+const objective_loader_1 = require("./objective-loader");
+// Re-exported so existing importers of "./loader" keep resolving these advisories
+// (they live in ./loader-warnings to hold loader.ts under the 700-LOC cap).
+var loader_warnings_2 = require("./loader-warnings");
+Object.defineProperty(exports, "arrayRootSchemaWarning", { enumerable: true, get: function () { return loader_warnings_2.arrayRootSchemaWarning; } });
+Object.defineProperty(exports, "unreferencedTrialCandidatesWarning", { enumerable: true, get: function () { return loader_warnings_2.unreferencedTrialCandidatesWarning; } });
 /**
  * Structured config error thrown for any invalid bundle (never a raw Error).
  * Load-time problems are deliberately NOT RigFailures — the failure taxonomy
@@ -81,7 +65,7 @@ const RETRYABLE_CLASSES = new Set([
     "network",
     "refusal",
     "cache_invalid",
-    "timeout",
+    "timeout", "quality_rejected",
 ].filter((c) => !failures_1.TERMINAL_CLASSES.has(c)));
 function isRecord(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -101,7 +85,18 @@ function parseCandidates(raw, problems) {
             problems.push(`candidates[${i}].provider "${c.provider}" is not a known provider`);
             continue;
         }
-        out.push(Object.freeze({ provider: c.provider, model: c.model }));
+        // Declare-first `trial` flag (routing-console spec §4.4): declared, never
+        // live-served. Optional; only `true` is carried so an absent/false flag
+        // leaves the candidate byte-identical to a pre-R3 candidate.
+        if (c.trial !== undefined && typeof c.trial !== "boolean") {
+            problems.push(`candidates[${i}].trial must be a boolean`);
+            continue;
+        }
+        out.push(Object.freeze({
+            provider: c.provider,
+            model: c.model,
+            ...(c.trial === true ? { trial: true } : {}),
+        }));
     }
     return out;
 }
@@ -223,6 +218,13 @@ function parseRepair(raw, field, candidates, problems) {
             problems.push(`${field}.repair_model (${repairModel.provider}/${repairModel.model}) is not in the route's declared candidates`);
             repairModel = null;
         }
+        // Declare-first (spec §4.4): the repair model dispatches LIVE, so a `trial`
+        // candidate (declared, never live-served) must not be one — reject at load.
+        const rm = repairModel;
+        if (rm !== null && candidates.some((c) => c.provider === rm.provider && c.model === rm.model && c.trial === true)) {
+            problems.push(`${field}.repair_model (${rm.provider}/${rm.model}) is a trial candidate and cannot be a live repair model`);
+            repairModel = null;
+        }
     }
     if (maxRepairs === 2 && repairModel === null) {
         problems.push(`${field}.max_repairs=2 requires repair_model (attempt 2 is the designated repair model)`);
@@ -256,6 +258,10 @@ function parseVariants(raw, routeCandidates, problems) {
             problems.push(`${field}.name "default" is reserved (the route's base config)`);
             continue;
         }
+        if (v.name.startsWith("__")) {
+            problems.push(`${field}.name "${v.name}" is reserved ("__" names are synthetic bake-off arms, e.g. "__reference__")`);
+            continue;
+        }
         if (seen.has(v.name)) {
             problems.push(`duplicate variant name "${v.name}"`);
             continue;
@@ -271,6 +277,14 @@ function parseVariants(raw, routeCandidates, problems) {
                 }
             }
         }
+        // trialOnly (routing-console spec §4.4): a variant whose candidates ALL map
+        // to declared `trial` candidates is a trial variant — valid for a bake-off,
+        // a live config error. Computed from the route-level trial flags (a variant
+        // narrows a subset; the flag lives on the declared candidate), so an empty
+        // or inherited candidate list is never trial-only.
+        const trialOnly = candidates !== undefined &&
+            candidates.length > 0 &&
+            candidates.every((vc) => routeCandidates.some((rc) => rc.provider === vc.provider && rc.model === vc.model && rc.trial === true));
         if (v.prompt_override !== undefined && v.prompt_append !== undefined) {
             problems.push(`${field} sets both prompt_override and prompt_append — they are mutually exclusive`);
         }
@@ -293,6 +307,7 @@ function parseVariants(raw, routeCandidates, problems) {
                 ? { json: v.json }
                 : {}),
             ...(repair !== undefined ? { repair } : {}),
+            ...(trialOnly ? { trialOnly: true } : {}),
         }));
     }
     return out;
@@ -382,6 +397,9 @@ function loadBundleFile(filePath) {
             groundingQuery = doc.grounding.query;
         }
     }
+    // RB-1 (near-optimal spec §3): objective knob, reference arm + judge, value
+    // checks — all additive; candidate-set invariant enforced in parseRb1Fields.
+    const rb1 = (0, objective_loader_1.parseRb1Fields)(doc, route, candidates, problems);
     let systemTemplate = "";
     let variables = [];
     if (!isRecord(doc.prompt) || typeof doc.prompt.system !== "string") {
@@ -435,15 +453,19 @@ function loadBundleFile(filePath) {
     // 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) {
+    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) {
+    const arrayRootWarning = (0, loader_warnings_1.arrayRootSchemaWarning)(route, outputSchema);
+    if (arrayRootWarning !== null)
         console.warn(`modelrig: ${arrayRootWarning}`);
-    }
+    // Declare-first dead-declaration warning (spec §4.4): a trial candidate no
+    // variant references is unreachable — warn so the dangling declaration is
+    // deliberate, never silent.
+    const trialWarning = (0, loader_warnings_1.unreferencedTrialCandidatesWarning)(route, candidates, variants);
+    if (trialWarning !== null)
+        console.warn(`modelrig: ${trialWarning}`);
     return Object.freeze({
         route: route,
         version: version,
@@ -462,6 +484,7 @@ function loadBundleFile(filePath) {
         // 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,
+        ...rb1, // RB-1 regret-bounded objective (objective/bakeoff/valueChecks, additive)
     });
 }
 /**

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

@@ -0,0 +1,35 @@
+/**
+ * Route-bundle parsing for the RB-1 regret-bounded objective (near-optimal spec
+ * §3). Extracted from loader.ts (kept it under the 700-LOC cap). Each parser
+ * pushes teaching problems into the shared `problems` array — a non-empty array
+ * fails the bundle load, exactly like every other loader field. Pure functions,
+ * unit-tested directly.
+ */
+import type { BakeoffConfig, CandidateSpec, RouteObjective, ValueCheck } from "../types/route";
+/** All three RB-1 route fields parsed in one call (keeps loader.ts under the
+ * 700-LOC cap): objective, bakeoff (reference arm + judge), value_checks. Pushes
+ * any problems into the shared array; emits the missing-bound advisory. */
+export declare function parseRb1Fields(doc: Record<string, unknown>, route: string, candidates: readonly CandidateSpec[], problems: string[]): {
+    objective?: RouteObjective;
+    bakeoff?: BakeoffConfig;
+    valueChecks?: readonly ValueCheck[];
+};
+/** Parse the `objective:` block. Absent ⇒ undefined (the engine defaults to
+ * quality-first with no bound: regret shown, nothing proposed). */
+export declare function parseObjective(raw: unknown, problems: string[]): RouteObjective | undefined;
+/** Parse the `bakeoff:` block (reference arm + judge). `candidates` is the
+ * route's declared set — the candidate-set invariant is enforced here (#223 F3
+ * for the judge; the reference must be declared unless allow-external). */
+export declare function parseBakeoffConfig(raw: unknown, candidates: readonly CandidateSpec[], problems: string[]): BakeoffConfig | undefined;
+/** Parse `value_checks:` — a list of {path, expect}. `path` is a JSON pointer;
+ * `expect` is a literal or {regex}. */
+export declare function parseValueChecks(raw: unknown, problems: string[]): readonly ValueCheck[] | undefined;
+/**
+ * Non-fatal advisory (CE-2 teaching-hint style): a route declares an objective
+ * with NEITHER a regret bound NOR a price ceiling, so a bake-off will REPORT
+ * regret but never propose anything. Warn so the missing bound is deliberate.
+ * Returns the warning line, or null. Only meaningful for quality-first/balanced
+ * (cost-first has its own gate and needs no bound).
+ */
+export declare function missingBoundWarning(route: string, objective: RouteObjective | undefined): string | null;
+//# sourceMappingURL=objective-loader.d.ts.map

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

@@ -0,0 +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,CAwC3F;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+E3B;AAED;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

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * Route-bundle parsing for the RB-1 regret-bounded objective (near-optimal spec
+ * §3). Extracted from loader.ts (kept it under the 700-LOC cap). Each parser
+ * pushes teaching problems into the shared `problems` array — a non-empty array
+ * fails the bundle load, exactly like every other loader field. Pure functions,
+ * unit-tested directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRb1Fields = parseRb1Fields;
+exports.parseObjective = parseObjective;
+exports.parseBakeoffConfig = parseBakeoffConfig;
+exports.parseValueChecks = parseValueChecks;
+exports.missingBoundWarning = missingBoundWarning;
+/** All three RB-1 route fields parsed in one call (keeps loader.ts under the
+ * 700-LOC cap): objective, bakeoff (reference arm + judge), value_checks. Pushes
+ * any problems into the shared array; emits the missing-bound advisory. */
+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);
+    // 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) {
+        const warning = missingBoundWarning(route, objective);
+        if (warning !== null)
+            console.warn(`modelrig: ${warning}`);
+    }
+    return {
+        ...(objective !== undefined ? { objective } : {}),
+        ...(bakeoff !== undefined ? { bakeoff } : {}),
+        ...(valueChecks !== undefined ? { valueChecks } : {}),
+    };
+}
+const OBJECTIVE_MODES = new Set([
+    "quality-first",
+    "balanced",
+    "cost-first",
+]);
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function parsePriceCeiling(raw, field, problems) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        problems.push(`${field} must be an object { usd_per_1k } or { usd_per_run }`);
+        return undefined;
+    }
+    const per1k = raw.usd_per_1k;
+    const perRun = raw.usd_per_run;
+    if (per1k !== undefined && perRun !== undefined) {
+        problems.push(`${field} sets both usd_per_1k and usd_per_run — pick one unit`);
+        return undefined;
+    }
+    if (per1k === undefined && perRun === undefined) {
+        problems.push(`${field} must set usd_per_1k or usd_per_run`);
+        return undefined;
+    }
+    const value = per1k ?? perRun;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        problems.push(`${field} value must be a positive number`);
+        return undefined;
+    }
+    return Object.freeze(per1k !== undefined ? { usdPer1k: value } : { usdPerRun: value });
+}
+/** Parse the `objective:` block. Absent ⇒ undefined (the engine defaults to
+ * quality-first with no bound: regret shown, nothing proposed). */
+function parseObjective(raw, problems) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        problems.push("objective must be an object");
+        return undefined;
+    }
+    const mode = raw.mode ?? "quality-first";
+    if (typeof mode !== "string" || !OBJECTIVE_MODES.has(mode)) {
+        problems.push(`objective.mode "${String(mode)}" is not one of [${[...OBJECTIVE_MODES].join(", ")}]`);
+        return undefined;
+    }
+    let maxRegret;
+    if (raw.max_regret !== undefined) {
+        if (typeof raw.max_regret !== "number" || !(raw.max_regret >= 0 && raw.max_regret <= 1)) {
+            problems.push("objective.max_regret must be a number in [0, 1] (quality points)");
+        }
+        else {
+            maxRegret = raw.max_regret;
+        }
+    }
+    const priceCeiling = parsePriceCeiling(raw.price_ceiling, "objective.price_ceiling", problems);
+    let lambda;
+    if (raw.lambda !== undefined) {
+        if (typeof raw.lambda !== "number" || !Number.isFinite(raw.lambda) || raw.lambda < 0) {
+            problems.push("objective.lambda must be a non-negative number");
+        }
+        else {
+            lambda = raw.lambda;
+        }
+    }
+    if (mode !== "balanced" && lambda !== undefined) {
+        problems.push("objective.lambda only applies to mode: balanced");
+    }
+    if (mode === "balanced" && lambda === undefined) {
+        problems.push("objective.mode: balanced requires objective.lambda");
+    }
+    return Object.freeze({
+        mode: mode,
+        ...(maxRegret !== undefined ? { maxRegret } : {}),
+        ...(priceCeiling !== undefined ? { priceCeiling } : {}),
+        ...(lambda !== undefined ? { lambda } : {}),
+    });
+}
+const PROVIDERS = new Set([
+    "gemini",
+    "openai",
+    "deepseek",
+    "anthropic",
+    "grok",
+]);
+/** "provider/model" or {provider, model} → CandidateSpec (no trial flag —
+ * a reference/judge is a concrete model, never a declare-first placeholder). */
+function parseModelRef(raw, field, problems) {
+    let provider;
+    let model;
+    if (typeof raw === "string") {
+        const slash = raw.indexOf("/");
+        if (slash <= 0 || slash === raw.length - 1) {
+            problems.push(`${field} must be "provider/model" or {provider, model}`);
+            return null;
+        }
+        provider = raw.slice(0, slash);
+        model = raw.slice(slash + 1);
+    }
+    else if (isRecord(raw)) {
+        provider = raw.provider;
+        model = raw.model;
+    }
+    else {
+        problems.push(`${field} must be "provider/model" or {provider, model}`);
+        return null;
+    }
+    if (typeof provider !== "string" || !PROVIDERS.has(provider) || typeof model !== "string" || model === "") {
+        problems.push(`${field} has an unknown provider or empty model`);
+        return null;
+    }
+    return Object.freeze({ provider: provider, model });
+}
+/** Parse the `bakeoff:` block (reference arm + judge). `candidates` is the
+ * route's declared set — the candidate-set invariant is enforced here (#223 F3
+ * for the judge; the reference must be declared unless allow-external). */
+function parseBakeoffConfig(raw, candidates, problems) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        problems.push("bakeoff must be an object");
+        return undefined;
+    }
+    const declared = (c) => candidates.some((rc) => rc.provider === c.provider && rc.model === c.model);
+    let referenceAllowExternal = false;
+    if (raw.reference_allow_external !== undefined) {
+        if (typeof raw.reference_allow_external !== "boolean") {
+            problems.push("bakeoff.reference_allow_external must be a boolean");
+        }
+        else {
+            referenceAllowExternal = raw.reference_allow_external;
+        }
+    }
+    let reference;
+    if (raw.reference !== undefined && raw.reference !== null) {
+        if (raw.reference === "auto") {
+            reference = "auto";
+        }
+        else {
+            const ref = parseModelRef(raw.reference, "bakeoff.reference", problems);
+            if (ref !== null) {
+                if (!declared(ref) && !referenceAllowExternal) {
+                    problems.push(`bakeoff.reference (${ref.provider}/${ref.model}) is not a declared candidate — ` +
+                        "add it to candidates, or set bakeoff.reference_allow_external: true to record the exception");
+                }
+                else {
+                    reference = { provider: ref.provider, model: ref.model };
+                }
+            }
+        }
+    }
+    let referenceEnvelopeUsd;
+    if (raw.reference_envelope_usd !== undefined) {
+        if (typeof raw.reference_envelope_usd !== "number" ||
+            !Number.isFinite(raw.reference_envelope_usd) ||
+            raw.reference_envelope_usd <= 0) {
+            problems.push("bakeoff.reference_envelope_usd must be a positive number");
+        }
+        else {
+            referenceEnvelopeUsd = raw.reference_envelope_usd;
+        }
+    }
+    let judge;
+    if (raw.judge !== undefined && raw.judge !== null) {
+        if (!isRecord(raw.judge)) {
+            problems.push("bakeoff.judge must be an object { model, max_samples }");
+        }
+        else {
+            const model = parseModelRef(raw.judge.model, "bakeoff.judge.model", problems);
+            const maxSamples = raw.judge.max_samples;
+            if (typeof maxSamples !== "number" || !Number.isInteger(maxSamples) || maxSamples < 1) {
+                problems.push("bakeoff.judge.max_samples must be a positive integer");
+            }
+            if (model !== null && !declared(model)) {
+                // #223 F3: the judge model must be a declared candidate.
+                problems.push(`bakeoff.judge.model (${model.provider}/${model.model}) is not a declared candidate ` +
+                    "(a judge model must be one of the route's declared candidates, #223 F3)");
+            }
+            else if (model !== null && typeof maxSamples === "number" && Number.isInteger(maxSamples) && maxSamples >= 1) {
+                judge = { model, maxSamples };
+            }
+        }
+    }
+    const out = {
+        ...(reference !== undefined ? { reference } : {}),
+        ...(referenceAllowExternal ? { referenceAllowExternal: true } : {}),
+        ...(referenceEnvelopeUsd !== undefined ? { referenceEnvelopeUsd } : {}),
+        ...(judge !== undefined ? { judge } : {}),
+    };
+    return Object.freeze(out);
+}
+/** Parse `value_checks:` — a list of {path, expect}. `path` is a JSON pointer;
+ * `expect` is a literal or {regex}. */
+function parseValueChecks(raw, problems) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!Array.isArray(raw)) {
+        problems.push("value_checks must be a list");
+        return undefined;
+    }
+    const out = [];
+    for (const [i, c] of raw.entries()) {
+        const field = `value_checks[${i}]`;
+        if (!isRecord(c)) {
+            problems.push(`${field} must be an object { path, expect }`);
+            continue;
+        }
+        if (typeof c.path !== "string" || c.path === "" || !c.path.startsWith("/")) {
+            problems.push(`${field}.path must be a non-empty JSON pointer starting with "/"`);
+            continue;
+        }
+        if (c.expect === undefined) {
+            problems.push(`${field}.expect is required (a literal value or { regex })`);
+            continue;
+        }
+        let expect;
+        if (isRecord(c.expect) && typeof c.expect.regex === "string") {
+            try {
+                // eslint-disable-next-line no-new
+                new RegExp(c.expect.regex);
+            }
+            catch (err) {
+                problems.push(`${field}.expect.regex is not a valid regular expression: ${err.message}`);
+                continue;
+            }
+            expect = { regex: c.expect.regex };
+        }
+        else {
+            expect = { literal: c.expect };
+        }
+        out.push(Object.freeze({ path: c.path, expect: Object.freeze(expect) }));
+    }
+    return Object.freeze(out);
+}
+/**
+ * Non-fatal advisory (CE-2 teaching-hint style): a route declares an objective
+ * with NEITHER a regret bound NOR a price ceiling, so a bake-off will REPORT
+ * regret but never propose anything. Warn so the missing bound is deliberate.
+ * Returns the warning line, or null. Only meaningful for quality-first/balanced
+ * (cost-first has its own gate and needs no bound).
+ */
+function missingBoundWarning(route, objective) {
+    const mode = objective?.mode ?? "quality-first";
+    if (mode === "cost-first")
+        return null;
+    const hasBound = objective?.maxRegret !== undefined || objective?.priceCeiling !== undefined;
+    if (hasBound)
+        return null;
+    return (`route "${route}" has no objective bound (neither max_regret nor price_ceiling): a bake-off ` +
+        "will REPORT regret vs the reference but propose nothing. Declare objective.max_regret and/or " +
+        "objective.price_ceiling to let a challenger be proposed under your ceiling.");
+}

package/dist/run/accept.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Accept-path builders, extracted from run.ts (which sits at the 700-LOC cap so
+ * the Q1 quality-gate seam has to pull its shared shapes out). Two pure builders:
+ *
+ *  - `successAttemptRow` — the AttemptTelemetry token/cost fields for a
+ *    SUCCESSFUL adapter result, shared by the accept path and the Q1
+ *    quality-REJECT path (which records the same billed row with a
+ *    `quality_rejected` failure instead of `null`).
+ *  - `buildSuccessMeta` — the validated `RunMeta` returned on the accept path.
+ *
+ * Behavior is byte-identical to the former inline literals; nothing new is
+ * computed here.
+ */
+import type { CandidateRef } from "../types/provider";
+import type { AdapterUsage } from "../types/provider";
+import type { FailureClass, RigFailure } from "../types/failures";
+import type { RouteBundle, RunMeta } from "../types/route";
+import type { AttemptTelemetry } from "./dispatch";
+import type { AttemptMetaSource } from "../telemetry/attempt-meta";
+/** The AttemptTelemetry for a successful adapter result. `failure` is null on the
+ * accept path and the `quality_rejected` failure on the Q1 reject path;
+ * `metaInputs` is the WI-1 attempt-meta envelope; `extraTags` carries the Q1
+ * quality tags (`quality` / `quality_score`). */
+export declare function successAttemptRow(candidate: CandidateRef, usage: AdapterUsage, costUsd: number, latencyMs: number, pricingMissing: boolean, failure: RigFailure | null, metaInputs: AttemptMetaSource, extraTags?: Record<string, string>): AttemptTelemetry;
+export interface SuccessMetaInput {
+    readonly inferenceId: string;
+    readonly route: RouteBundle;
+    readonly candidate: CandidateRef;
+    readonly usage: AdapterUsage;
+    readonly costUsd: number;
+    readonly latencyMs: number;
+    readonly attemptsByClass: Partial<Record<FailureClass, number>>;
+    readonly servedVariant: string | null;
+    readonly callId: string;
+    /** Grounding-inject citations, when the search rung served this run. */
+    readonly citations?: RunMeta["citations"];
+    /** Q1 quality verdict, when a gate ran on this run. */
+    readonly quality?: RunMeta["quality"];
+}
+/** The validated `RunMeta` for the accept path — `repairedBy` is null here (the
+ * repair path builds its own meta), `validated` is always true. */
+export declare function buildSuccessMeta(input: SuccessMetaInput): RunMeta;
+//# sourceMappingURL=accept.d.ts.map

package/dist/run/accept.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accept.d.ts","sourceRoot":"","sources":["../../src/run/accept.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE;;;iDAGiD;AACjD,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,OAAO,EACvB,OAAO,EAAE,UAAU,GAAG,IAAI,EAC1B,UAAU,EAAE,iBAAiB,EAC7B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,gBAAgB,CAiBlB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1C,uDAAuD;IACvD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CACvC;AAED;mEACmE;AACnE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAuBjE"}