modelrig 0.4.0 → 0.5.0

package/dist/run/run.d.ts

@@ -12,7 +12,7 @@ import type { RigManifest } from "../routes/manifest";
 import type { RunOptions, RunResult } from "../types/route";
 import type { TelemetryStore } from "../types/telemetry";
 import type { CaptureStore } from "../telemetry/capture";
-import type { CapabilityLookup } from "./resolve";
+import type { CapabilityLookup, RunMode } from "./resolve";
 import type { SearchProvider } from "./grounding";
 import type { StreamDeltaSink } from "./dispatch";
 import type { TaskSettingsResolver } from "../settings/task-settings";
@@ -50,6 +50,12 @@ export interface RunDeps {
      * content before a capture row is written. null/omitted = local-only (the
      * YAML flag governs, no per-task scrub policy). */
     readonly settings?: TaskSettingsResolver | null;
+    /** Resolution mode (routing-console spec §4.4, R3) — `live` (default) on every
+     * production surface, `trial` ONLY on the bake-off replay path (`replayVariant`
+     * sets it). `trial` keeps declared `trial` candidates and permits selecting a
+     * trial variant; `live` drops trial candidates before minting and rejects a
+     * trial variant. Absent ⇒ live ⇒ byte-identical to the pre-R3 loop. */
+    readonly mode?: RunMode;
 }
 export declare function run(deps: RunDeps, routeName: string, opts: RunOptions): Promise<RunResult>;
 //# sourceMappingURL=run.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAMrD,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,mBAAmB,CAAC;AAGvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAsC,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAQlD,OAAO,KAAK,EAAE,cAAc,EAAoC,MAAM,aAAa,CAAC;AAUpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAKlD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC,+EAA+E;IAC/E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;gDAE4C;IAC5C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC;2EACuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACxC;;0BAEsB;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;mFAG+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,eAAe,CAAC;IACzC;;;;;uDAKmD;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACjD;AAqDD,wBAAsB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAmjBhG"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAMrD,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,mBAAmB,CAAC;AAGvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAW,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAS3D,OAAO,KAAK,EAAE,cAAc,EAAoC,MAAM,aAAa,CAAC;AAUpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAKlD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC,+EAA+E;IAC/E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;gDAE4C;IAC5C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC;2EACuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACxC;;0BAEsB;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;mFAG+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,eAAe,CAAC;IACzC;;;;;uDAKmD;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAChD;;;;2EAIuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAsBD,wBAAsB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAgkBhG"}

package/dist/run/run.js

@@ -17,6 +17,7 @@ const pricing_1 = require("../registry/pricing");
 const failures_1 = require("../types/failures");
 const manifest_1 = require("../routes/manifest");
 const resolve_1 = require("./resolve");
+const variant_1 = require("./variant");
 const envelope_1 = require("./envelope");
 const retry_1 = require("./retry");
 const repair_1 = require("./repair");
@@ -27,35 +28,6 @@ const record_attempt_1 = require("./record-attempt");
 const ladder_key_1 = require("./ladder-key");
 const run_context_1 = require("../artifacts/run-context");
 const capture_write_1 = require("./capture-write");
-/** Look up a named variant; null = default (base config). Unknown names are
- * config errors — the caller asked for something the bundle doesn't define. */
-function resolveVariant(route, name) {
-    if (name === undefined || name === "default")
-        return null;
-    const variant = route.variants.find((v) => v.name === name);
-    if (variant === undefined) {
-        throw new loader_1.RouteConfigError(`route "${route.route}" has no variant "${name}" — defined: [${route.variants
-            .map((v) => v.name)
-            .join(", ")}]`);
-    }
-    return variant;
-}
-/** The variant-effective view of a route: narrowed candidates, overridden
- * json rung, overridden template. Loader validation guarantees variant
- * candidates ⊆ declared candidates, so the candidate-set invariant holds. */
-function effectiveRoute(route, variant) {
-    if (variant === null)
-        return route;
-    return Object.freeze({
-        ...route,
-        candidates: variant.candidates ?? route.candidates,
-        systemTemplate: variant.promptOverride ?? route.systemTemplate,
-        policy: Object.freeze({
-            ...route.policy,
-            json: variant.json ?? route.policy.json,
-        }),
-    });
-}
 /** Phase 1 prompt convention: the bundle's system template carries the whole
  * task (constitution, data, step instructions); the user turn is a terse
  * trigger. Providers treat long system prompts + short user turns well, and
@@ -73,10 +45,11 @@ function costPerMTok(provider, model) {
 }
 const DEFAULT_SLEEP = (ms) => ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms));
 async function run(deps, routeName, opts) {
+    const mode = deps.mode ?? "live";
     const baseRoute = deps.routes.get(routeName);
-    const variant = resolveVariant(baseRoute, opts.variant);
+    const variant = (0, variant_1.resolveVariant)(baseRoute, opts.variant, mode);
     const servedVariant = variant?.name ?? null;
-    const route = (0, resolve_1.applyRunRequirements)(effectiveRoute(baseRoute, variant), opts.zeroRetention === true);
+    const route = (0, resolve_1.applyRunRequirements)((0, variant_1.effectiveRoute)(baseRoute, variant), opts.zeroRetention === true);
     const effectiveTags = route.require.includes("zero_retention") ? { ...opts.tags, zdr_enforced: "true" } : opts.tags;
     // Data-hygiene warning (spec WS5): once per process per dimension.
     (0, manifest_1.warnMissingRequiredDimensions)(deps.manifest ?? null, opts.tags);
@@ -96,7 +69,7 @@ async function run(deps, routeName, opts) {
     // exit that records an inference also records a ground-truth step referencing
     // it (attempt-per-row, ruling c). Inert without a run.start on this path.
     const runCtx = (0, run_context_1.getActiveRunContext)();
-    const autoStepKey = runCtx !== null ? runCtx.nextStepKey(route.route) : null;
+    const autoStepKey = runCtx !== null ? (0, run_context_1.resolveStepKey)(opts.stepKey, opts.tags.step, () => runCtx.nextStepKey(route.route)) : null;
     // Per-call ladder key (spec §2.1 R0): one call_id, a monotonic attempt_seq per
     // row, and the current candidate_index (advanced by nextCandidate below).
     const ladder = (0, ladder_key_1.createLadderKeyMinter)();
@@ -146,6 +119,14 @@ async function run(deps, routeName, opts) {
             systemPrompt = originalSystemPrompt + (0, repair_1.repairFeedbackBlock)(errors);
         }
         else {
+            // Declare-first backstop (spec §4.4): the loader rejects a `trial` candidate
+            // as `repair_model`, but a programmatically-built bundle (runBundle) could
+            // bypass the loader — so refuse to mint a trial candidate for LIVE repair
+            // here too (the primary ladder's trial-drop has no repair-path equivalent).
+            if (mode === "live" &&
+                route.candidates.some((c) => c.provider === step.model.provider && c.model === step.model.model && c.trial === true)) {
+                return null;
+            }
             // Brand stays in resolve.ts; loader validated repairModel ⊆ declared.
             const minted = (0, resolve_1.resolveDeclaredCandidate)(route, step.model);
             if (minted === null)
@@ -255,7 +236,7 @@ async function run(deps, routeName, opts) {
         };
     }
     const searchAvailable = deps.search !== undefined && deps.search !== null;
-    const iter = (0, resolve_1.resolveCandidates)(route, deps.capabilities, costPerMTok, searchAvailable, (0, resolve_1.candidateFilterFromOptions)(opts));
+    const iter = (0, resolve_1.resolveCandidates)(route, deps.capabilities, costPerMTok, searchAvailable, (0, resolve_1.candidateFilterFromOptions)(opts), undefined, mode);
     // Advance the iterator AND publish the served candidate's index to the ladder,
     // so every row of this candidate's turn (incl. repair rows) carries it (§2.1).
     const nextCandidate = () => {

package/dist/run/variant.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Variant resolution — extracted from run.ts (spec §4.4, R3) to host the
+ * declare-first "a trial variant selected live is a config error" rule and to
+ * keep run.ts under the LOC cap. Pure: bundle + requested name (+ run mode) →
+ * the resolved variant and the variant-effective route view.
+ */
+import type { RouteBundle, RouteVariant } from "../types/route";
+import type { RunMode } from "./resolve";
+/**
+ * A variant is trial-only when it has candidates and EVERY one maps to a
+ * declared `trial` candidate. Computed dynamically from `route.candidates`
+ * rather than trusted from the stored `variant.trialOnly` stamp, so a bundle
+ * built in code — a programmatic `runBundle` whose variants never passed
+ * through the loader that sets the flag — is judged exactly like a loaded one
+ * (and still earns the teaching error on a live trial selection). The loader's
+ * stamp, when present, is honored as a fast path.
+ */
+export declare function isTrialOnlyVariant(route: RouteBundle, variant: RouteVariant): boolean;
+/**
+ * Look up a named variant; null = default (base config). Unknown names are
+ * config errors — the caller asked for something the bundle doesn't define.
+ *
+ * Declare-first (spec §4.4): a `trialOnly` variant — one whose candidates are
+ * ALL declared `trial` candidates — is valid only in bake-off replay
+ * (`mode: "trial"`). Selecting it on a LIVE path is a `RouteConfigError` with a
+ * teaching message that names the bake-off, never a silent fallback (residual
+ * flag F2′): the run loop must not dispatch an undeclared OR trial model live.
+ */
+export declare function resolveVariant(route: RouteBundle, name: string | undefined, mode?: RunMode): RouteVariant | null;
+/**
+ * The variant-effective view of a route: narrowed candidates, overridden json
+ * rung, overridden template. Loader validation guarantees variant candidates ⊆
+ * declared candidates, so the candidate-set invariant holds.
+ *
+ * Declare-first (spec §4.4): a variant's `candidates` entries are authored as
+ * bare `{provider, model}` and do NOT carry the route-level `trial` flag. We
+ * MUST re-attach it from the matching declared candidate — otherwise a variant
+ * that narrows to a trial candidate (e.g. a mixed trial+live variant, which is
+ * not `trialOnly` and IS selectable live) would strip the flag and
+ * `resolveCandidates`' live trial-drop would let the trial model serve live.
+ */
+export declare function effectiveRoute(route: RouteBundle, variant: RouteVariant | null): RouteBundle;
+//# sourceMappingURL=variant.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"variant.d.ts","sourceRoot":"","sources":["../../src/run/variant.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAYrF;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,GAAE,OAAgB,GACrB,YAAY,GAAG,IAAI,CAkBrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,WAAW,CAoB5F"}

package/dist/run/variant.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Variant resolution — extracted from run.ts (spec §4.4, R3) to host the
+ * declare-first "a trial variant selected live is a config error" rule and to
+ * keep run.ts under the LOC cap. Pure: bundle + requested name (+ run mode) →
+ * the resolved variant and the variant-effective route view.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTrialOnlyVariant = isTrialOnlyVariant;
+exports.resolveVariant = resolveVariant;
+exports.effectiveRoute = effectiveRoute;
+const loader_1 = require("../routes/loader");
+/**
+ * A variant is trial-only when it has candidates and EVERY one maps to a
+ * declared `trial` candidate. Computed dynamically from `route.candidates`
+ * rather than trusted from the stored `variant.trialOnly` stamp, so a bundle
+ * built in code — a programmatic `runBundle` whose variants never passed
+ * through the loader that sets the flag — is judged exactly like a loaded one
+ * (and still earns the teaching error on a live trial selection). The loader's
+ * stamp, when present, is honored as a fast path.
+ */
+function isTrialOnlyVariant(route, variant) {
+    if (variant.trialOnly === true)
+        return true;
+    const cands = variant.candidates;
+    return (cands !== undefined &&
+        cands.length > 0 &&
+        cands.every((vc) => route.candidates.some((rc) => rc.provider === vc.provider && rc.model === vc.model && rc.trial === true)));
+}
+/**
+ * Look up a named variant; null = default (base config). Unknown names are
+ * config errors — the caller asked for something the bundle doesn't define.
+ *
+ * Declare-first (spec §4.4): a `trialOnly` variant — one whose candidates are
+ * ALL declared `trial` candidates — is valid only in bake-off replay
+ * (`mode: "trial"`). Selecting it on a LIVE path is a `RouteConfigError` with a
+ * teaching message that names the bake-off, never a silent fallback (residual
+ * flag F2′): the run loop must not dispatch an undeclared OR trial model live.
+ */
+function resolveVariant(route, name, mode = "live") {
+    if (name === undefined || name === "default")
+        return null;
+    const variant = route.variants.find((v) => v.name === name);
+    if (variant === undefined) {
+        throw new loader_1.RouteConfigError(`route "${route.route}" has no variant "${name}" — defined: [${route.variants
+            .map((v) => v.name)
+            .join(", ")}]`);
+    }
+    if (mode === "live" && isTrialOnlyVariant(route, variant)) {
+        throw new loader_1.RouteConfigError(`route "${route.route}" variant "${name}" is a trial variant (all its candidates are declared ` +
+            `trial: true) — trial variants are declared but never served live. Measure it with a bake-off ` +
+            `(rig.bakeoff / "Run bake-off" in the console), then promote the winner to a live candidate.`);
+    }
+    return variant;
+}
+/**
+ * The variant-effective view of a route: narrowed candidates, overridden json
+ * rung, overridden template. Loader validation guarantees variant candidates ⊆
+ * declared candidates, so the candidate-set invariant holds.
+ *
+ * Declare-first (spec §4.4): a variant's `candidates` entries are authored as
+ * bare `{provider, model}` and do NOT carry the route-level `trial` flag. We
+ * MUST re-attach it from the matching declared candidate — otherwise a variant
+ * that narrows to a trial candidate (e.g. a mixed trial+live variant, which is
+ * not `trialOnly` and IS selectable live) would strip the flag and
+ * `resolveCandidates`' live trial-drop would let the trial model serve live.
+ */
+function effectiveRoute(route, variant) {
+    if (variant === null)
+        return route;
+    const candidates = variant.candidates === undefined
+        ? route.candidates
+        : variant.candidates.map((vc) => {
+            const declared = route.candidates.find((c) => c.provider === vc.provider && c.model === vc.model);
+            return declared?.trial === true ? { ...vc, trial: true } : vc;
+        });
+    return Object.freeze({
+        ...route,
+        candidates,
+        systemTemplate: variant.promptOverride ?? route.systemTemplate,
+        policy: Object.freeze({
+            ...route.policy,
+            json: variant.json ?? route.policy.json,
+        }),
+    });
+}

package/dist/savings/emit.d.ts

@@ -6,6 +6,13 @@
  * greps for it.
  */
 import type { CandidateSpec, RouteBundle } from "../types/route";
+/** A challenger to declare/promote — just the identifying pair. Loose on purpose
+ * (`provider: string`): a challenger comes from a stored proposal or the picker,
+ * where the provider is already validated, and the emitters only render YAML. */
+export interface ChallengerRef {
+    readonly provider: string;
+    readonly model: string;
+}
 export interface SwapChange {
     readonly route: string;
     readonly file: string;
@@ -34,5 +41,31 @@ export declare function buildRestoreYaml(route: string, incumbent: readonly {
     readonly provider: string;
     readonly model: string;
 }[], currentVersion: number): string;
+/** The paste-ready change that DECLARES a `trial` challenger (routing-console
+ * spec §4.4, declare step). Additive-only: nothing existing is removed. */
+export interface DeclareTrialChange {
+    readonly route: string;
+    readonly file: string;
+    readonly challenger: ChallengerRef;
+    /** The auto-named trial variant a bake-off replays (`trial-<provider>-<model>`). */
+    readonly trialVariant: string;
+    readonly newVersion: number;
+    /** Paste-ready YAML: version bump + full candidates block (challenger appended
+     * with `trial: true`) + the trial variant to add. Complete, no elisions (A4). */
+    readonly yaml: string;
+}
+/** A stable, YAML-safe trial variant name for a challenger. */
+export declare function trialVariantName(challenger: ChallengerRef): string;
+/**
+ * Emit the declare-first YAML that adds a `trial` challenger to a route (spec
+ * §4.4 step 1): the challenger appended to `candidates` with `trial: true`, a
+ * `trial-<provider>-<model>` variant that narrows to it, and `version: n+1`. The
+ * challenger is DECLARED but never served live (the loader/resolver enforce
+ * that) — so a bake-off can measure it on real traffic before promotion. Pure,
+ * no filesystem (emit.test.ts greps for that). Throws when the challenger is
+ * already a declared candidate — you don't declare what's already declared (the
+ * server maps this to 422).
+ */
+export declare function buildDeclareTrialChange(bundle: RouteBundle, challenger: ChallengerRef): DeclareTrialChange;
 export declare function buildSwapChange(bundle: RouteBundle, winningVariant: string): SwapChange;
 //# sourceMappingURL=emit.d.ts.map

package/dist/savings/emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/savings/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAgB,MAAM,gBAAgB,CAAC;AAE/E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;yCACqC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;+DAC2D;IAC3D,QAAQ,CAAC,mBAAmB,EAAE,SAAS,aAAa,EAAE,CAAC;CACxD;AAmCD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,EAC3E,cAAc,EAAE,MAAM,GACrB,MAAM,CAgBR;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,UAAU,CA6CvF"}
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/savings/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAgB,MAAM,gBAAgB,CAAC;AAE/E;;iFAEiF;AACjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;yCACqC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;+DAC2D;IAC3D,QAAQ,CAAC,mBAAmB,EAAE,SAAS,aAAa,EAAE,CAAC;CACxD;AA2CD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,EAC3E,cAAc,EAAE,MAAM,GACrB,MAAM,CAgBR;AAED;2EAC2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,oFAAoF;IACpF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;qFACiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,aAAa,GAAG,MAAM,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,GAAG,kBAAkB,CAiC1G;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,UAAU,CAgEvF"}

package/dist/savings/emit.js

@@ -8,9 +8,19 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildRestoreYaml = buildRestoreYaml;
+exports.trialVariantName = trialVariantName;
+exports.buildDeclareTrialChange = buildDeclareTrialChange;
 exports.buildSwapChange = buildSwapChange;
 function candidateLines(candidates) {
-    return candidates.flatMap((c) => [`  - provider: ${c.provider}`, `    model: ${c.model}`]);
+    // Preserve a candidate's `trial: true` (declare-first, spec §4.4) so an
+    // emitted candidates block never silently promotes a DECLARED-trial candidate
+    // to live. The promote path drops the flag from the WINNER explicitly (it
+    // passes a winner entry without `trial`), never here.
+    return candidates.flatMap((c) => [
+        `  - provider: ${c.provider}`,
+        `    model: ${c.model}`,
+        ...(c.trial === true ? ["    trial: true"] : []),
+    ]);
 }
 function overrideLines(variant) {
     const lines = [];
@@ -57,26 +67,88 @@ function buildRestoreYaml(route, incumbent, currentVersion) {
         "",
     ].join("\n");
 }
+/** A stable, YAML-safe trial variant name for a challenger. */
+function trialVariantName(challenger) {
+    return `trial-${challenger.provider}-${challenger.model}`.replace(/[^A-Za-z0-9._-]/g, "-");
+}
+/**
+ * Emit the declare-first YAML that adds a `trial` challenger to a route (spec
+ * §4.4 step 1): the challenger appended to `candidates` with `trial: true`, a
+ * `trial-<provider>-<model>` variant that narrows to it, and `version: n+1`. The
+ * challenger is DECLARED but never served live (the loader/resolver enforce
+ * that) — so a bake-off can measure it on real traffic before promotion. Pure,
+ * no filesystem (emit.test.ts greps for that). Throws when the challenger is
+ * already a declared candidate — you don't declare what's already declared (the
+ * server maps this to 422).
+ */
+function buildDeclareTrialChange(bundle, challenger) {
+    if (bundle.candidates.some((c) => c.provider === challenger.provider && c.model === challenger.model)) {
+        throw new Error(`${challenger.provider}/${challenger.model} is already a declared candidate on "${bundle.route}" — ` +
+            "nothing to declare (pick a model that is not yet in the route to trial it)");
+    }
+    const file = `modelrig/routes/${bundle.route}.yaml`;
+    const newVersion = bundle.version + 1;
+    const variant = trialVariantName(challenger);
+    const newCandidates = [...bundle.candidates, { ...challenger, trial: true }];
+    const yaml = [
+        `# declare a trial of ${challenger.provider}/${challenger.model} on ${bundle.route}`,
+        `# a trial candidate is DECLARED but NEVER served live — a bake-off measures it, then Promote makes it live.`,
+        `# apply to ${file}:`,
+        `# 1) bump the version`,
+        `version: ${newVersion}`,
+        `# 2) replace your candidates: block with this (the challenger is appended and marked for trial)`,
+        "candidates:",
+        ...candidateLines(newCandidates),
+        `# 3) add this entry to your variants: block (create the block if the route has none)`,
+        "variants:",
+        `  - name: ${variant}`,
+        "    candidates:",
+        `      - provider: ${challenger.provider}`,
+        `        model: ${challenger.model}`,
+        `# Requires the modelrig SDK release that understands \`trial:\` — an older SDK ignores the flag and`,
+        `# would serve the model live. Bake it off with: modelrig bakeoff --from-proposal <id>`,
+        "",
+    ].join("\n");
+    return { route: bundle.route, file, challenger, trialVariant: variant, newVersion, yaml };
+}
 function buildSwapChange(bundle, winningVariant) {
     const variant = bundle.variants.find((v) => v.name === winningVariant);
     if (variant === undefined) {
         throw new Error(`route "${bundle.route}" has no variant "${winningVariant}" — cannot emit a swap for it`);
     }
-    const winners = variant.candidates ?? bundle.candidates;
+    // Promote drops `trial: true` from the WINNER and moves it to position 0. The
+    // flag is stripped EXPLICITLY here (not merely relied upon being absent from a
+    // bare variant candidate) so a hand-authored `trial: true` inside the variant's
+    // candidate block can never leave the promoted winner as a trial candidate — a
+    // silent no-op promotion where the "promoted" model is then dropped live. Other
+    // declared candidates keep their own trial flags (candidateLines preserves them).
+    const winners = (variant.candidates ?? bundle.candidates).map((c) => ({
+        provider: c.provider,
+        model: c.model,
+    }));
     if (winners.length === 0) {
         throw new Error(`variant "${winningVariant}" has no candidates to promote`);
     }
     const incumbent = bundle.candidates[0];
+    // Trial-winner promotes also remove the now-redundant trial variant (spec §4.4).
+    const isTrialPromotion = variant.trialOnly === true;
     const promoted = promotedOrder(bundle.candidates, winners);
     const file = `modelrig/routes/${bundle.route}.yaml`;
     const newVersion = bundle.version + 1;
+    const applyComment = isTrialPromotion
+        ? `# apply to ${file} — replace version + candidates, and REMOVE the trial variant "${winningVariant}" from variants:`
+        : `# apply to ${file} — replace the version and candidates fields; nothing else changes`;
+    const trialRemovalLine = isTrialPromotion
+        ? [`# remove this now-promoted trial variant from variants: (its candidate is live at position 0 above):`, `#   - name: ${winningVariant}`]
+        : [];
     const yaml = [
         `# swap: serve ${bundle.route} on ${winners[0].provider}/${winners[0].model}`,
-        `# apply to ${file} — replace the version and candidates fields; nothing else changes`,
+        applyComment,
         `version: ${newVersion}`,
         "candidates:",
         ...candidateLines(promoted),
         ...overrideLines(variant),
+        ...trialRemovalLine,
         "",
     ].join("\n");
     const revertYaml = [

package/dist/types/route.d.ts

@@ -7,6 +7,23 @@ import type { ProviderId, SamplingParams, ServiceTier, ToolCall, ToolChoice, Too
 export interface CandidateSpec {
     readonly provider: ProviderId;
     readonly model: string;
+    /**
+     * Declare-first experiment flag (routing-console spec §4.4, R3). A `trial`
+     * candidate is DECLARED — it is in the list the brand type, the loader and the
+     * runtime candidate-set guard all derive from, so the candidate-set invariant
+     * is untouched — but `resolveCandidates` drops it on EVERY live path
+     * (`rig.run`, `runStream`, `runBundle`, the hosted gateway slug lane) exactly
+     * as it drops a `providers.ignore` entry. Only the bake-off replay path
+     * (`replayVariant`, run `mode: "trial"`) keeps it, so a customer can measure a
+     * new model on real captured traffic before promoting it to a live candidate.
+     * Optional & additive (S3): absent ⇒ false ⇒ an ordinary live candidate.
+     *
+     * OLDER-SDK CAVEAT (spec §7): the pre-0.4.0 loader is TOLERANT of unknown
+     * candidate keys — it would ignore `trial` and serve the candidate LIVE. A
+     * bundle using `trial: true` therefore REQUIRES the SDK release that
+     * understands it; the console's declare-YAML says so.
+     */
+    readonly trial?: boolean;
 }
 export type Requirement = "schema_conformant" | "grounded" | "zero_retention" | "trace_visible";
 export type Preference = "cost" | "latency";
@@ -57,6 +74,14 @@ export interface RouteVariant {
     /** JSON rung override for this variant. */
     readonly json?: "native" | "json_mode";
     readonly repair?: RepairPolicy;
+    /**
+     * COMPUTED at load (not authored): true when every candidate this variant
+     * narrows to is a declared `trial` candidate (routing-console spec §4.4). A
+     * trial variant is valid for `rig.bakeoff` but a `RouteConfigError` if a live
+     * caller selects it — trial candidates are declared, never live-served. The
+     * declare-first flow's `trial-<provider>-<model>` variant is exactly this.
+     */
+    readonly trialOnly?: boolean;
 }
 export interface RouteBundle {
     readonly route: string;
@@ -100,6 +125,12 @@ export interface RunTags {
 export interface RunOptions {
     readonly input: Record<string, unknown>;
     readonly tags: RunTags;
+    /** Names the ground-truth step this run records (G1 spec §3) — the same field
+     * the raw lane exposes, so a routed and a raw call, plus an `artifact.save`,
+     * can be composed into ONE step group. Resolution: `stepKey ?? tags.step ??`
+     * an auto-minted `route#n`. Validated `[A-Za-z0-9_.:#-]{1,128}`; an invalid
+     * value is warned and dropped to the auto key. Absent ⇒ unchanged behavior. */
+    readonly stepKey?: string;
     readonly budget?: {
         readonly envelope: string;
         /** Budget for this envelope when it is FIRST opened (open-or-get: the first

package/dist/types/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"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"}

package/dist/watch/evaluate.d.ts

@@ -56,7 +56,26 @@ export interface WatchConfig {
  * Analyst's triggers ride the widened kinds (`insight`/`promote-eval`) or reuse
  * `bakeoff` for an Analyst-initiated bake-off — all through the SAME proposals
  * machinery and the SAME `submitDrafts` seam (trajectory F1/F4, one emission path). */
-export type ProposalTrigger = EconomicsTrigger | ConformDegradationTrigger | AnalystClusterTrigger | AnalystPromoteEvalTrigger | AnalystBakeoffTrigger;
+export type ProposalTrigger = EconomicsTrigger | ConformDegradationTrigger | AnalystClusterTrigger | AnalystPromoteEvalTrigger | AnalystBakeoffTrigger | ManualChallengerTrigger;
+/**
+ * A human-initiated declare-first challenger (routing-console spec §2.4 / §3, R3)
+ * — the console picker (or the oracle) proposes trialing a specific model on a
+ * route. `kind` stays `"bakeoff"`; this trigger carries the challenger and the
+ * `trial-<provider>-<model>` variant name a bake-off replays. `reason` /
+ * `requestedBy` are audit context and are DELIBERATELY excluded from the
+ * idempotency hash (see {@link manualChallengerTriggerHash}) so two people
+ * declaring the same challenger dedupe to one proposal.
+ */
+export interface ManualChallengerTrigger {
+    readonly type: "manual_challenger";
+    readonly route: string;
+    readonly challenger: CandidateEconomics;
+    /** The trial variant a bake-off replays: `trial-<provider>-<model>`. */
+    readonly variant: string;
+    readonly reason?: string;
+    /** Actor id (user or key) that initiated the declare — audit only. */
+    readonly requestedBy?: string;
+}
 /** The measured statistics behind one Analyst cluster — all deterministic. */
 export interface AnalystClusterStats {
     /** Runs in this (task, cluster) over the window. */
@@ -169,6 +188,13 @@ export interface ProposalDraft {
 }
 export declare const PROPOSAL_TTL_DAYS = 30;
 export declare function triggerHash(route: string, trigger: ProposalTrigger): string;
+/**
+ * Idempotency key for a declare-first manual challenger — per (route, challenger)
+ * ONLY (spec §2.4), so `reason`/`requestedBy` never split a dedupe. The
+ * control-plane unique index is (org_id, route, trigger_hash), so the same
+ * challenger declared twice on a route by the same org is a no-op.
+ */
+export declare function manualChallengerTriggerHash(route: string, challenger: CandidateEconomics): string;
 export declare function evaluateEvents(routes: readonly RouteEconomics[], events: readonly WatchEvent[], config: WatchConfig): ProposalDraft[];
 /** The §5.5 evidence block — every field the rendered explanation and the
  * verdict need, in one self-describing object. Rates are per-Mtok (the surface

package/dist/watch/evaluate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/watch/evaluate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/watch/evaluate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAYH,OAAO,KAAK,EACV,qBAAqB,EACrB,YAAY,EACZ,cAAc,EACd,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AAEpC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,MAAM,UAAU,GAClB;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;CACrC,CAAC;AAEN,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;qFAIiF;IACjF,QAAQ,CAAC,eAAe,CAAC,EAAE,qBAAqB,CAAC;CAClD;AAED;;;;;;uFAMuF;AACvF,MAAM,MAAM,eAAe,GACvB,gBAAgB,GAChB,yBAAyB,GACzB,qBAAqB,GACrB,yBAAyB,GACzB,qBAAqB,GACrB,uBAAuB,CAAC;AAE5B;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAQD,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C;AAED;;4EAE4E;AAC5E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;sFAEsF;AACtF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACzD;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;kBAGkB;AAClB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,WAAW,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;CACtC;AAED;kFACkF;AAClF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;iFAEiF;AACjF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;0CAE0C;AAC1C,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,cAAc,CAAC;AAE3E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;uDAGmD;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAYpC,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,kBAAkB,GAC7B,MAAM,CAKR;AAMD,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,MAAM,EAAE,WAAW,GAClB,aAAa,EAAE,CAoDjB;AAUD;;oDAEoD;AACpD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,+BAA+B,EAAE,MAAM,CAAC;IACjD,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;IAC7C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;CAChC;AAED;;;;kCAIkC;AAClC,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,8CAA8C;IAC9C,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC;IACzC,iFAAiF;IACjF,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,kEAAkE;IAClE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;2EACuE;IACvE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AAID;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,iBAAiB,EACxB,MAAM,GAAE,qBAAgD,GACvD,YAAY,CA8Cd;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,YAAY,EACjB,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,GACtB,MAAM,CAaR"}

package/dist/watch/evaluate.js

@@ -18,6 +18,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROPOSAL_TTL_DAYS = void 0;
 exports.triggerHash = triggerHash;
+exports.manualChallengerTriggerHash = manualChallengerTriggerHash;
 exports.evaluateEvents = evaluateEvents;
 exports.buildCacheContext = buildCacheContext;
 exports.explainCacheContext = explainCacheContext;
@@ -35,6 +36,18 @@ function blended(rates) {
 function triggerHash(route, trigger) {
     return (0, node_crypto_1.createHash)("sha256").update(`${route}\n${JSON.stringify(trigger)}`).digest("hex").slice(0, 32);
 }
+/**
+ * Idempotency key for a declare-first manual challenger — per (route, challenger)
+ * ONLY (spec §2.4), so `reason`/`requestedBy` never split a dedupe. The
+ * control-plane unique index is (org_id, route, trigger_hash), so the same
+ * challenger declared twice on a route by the same org is a no-op.
+ */
+function manualChallengerTriggerHash(route, challenger) {
+    return (0, node_crypto_1.createHash)("sha256")
+        .update(`manual_challenger\n${route}\n${challenger.provider}/${challenger.model}`)
+        .digest("hex")
+        .slice(0, 32);
+}
 function expiryStamp() {
     return new Date(Date.now() + exports.PROPOSAL_TTL_DAYS * 24 * 3600 * 1000).toISOString();
 }

package/dist/watch/proposals.d.ts

@@ -84,6 +84,34 @@ export interface ProposalsClient {
     decide(id: string, from: ProposalStatus, to: "approved" | "rejected", decidedBy: string, decidedByUserId?: string | null, orgId?: string): Promise<boolean>;
     /** One sweep: overdue suggested/evidenced → expired. */
     expireOverdue(now: Date): Promise<void>;
+    /**
+     * Declare-first (routing-console spec §3, R3): create a HUMAN/oracle-initiated
+     * `manual_challenger` proposal (kind `"bakeoff"`). Idempotent on
+     * (org_id, route, trigger_hash) where the hash keys on (route, challenger)
+     * only — a duplicate returns the EXISTING id with `created:false` (the caller
+     * maps that to 409). Provenance (`created_by`/`created_by_key`, migration
+     * 00055) records the actor. Returns the row id + whether it was newly created.
+     */
+    createManualChallenger(input: CreateManualChallengerInput): Promise<{
+        id: string;
+        created: boolean;
+        status?: ProposalStatus;
+    }>;
+}
+export interface CreateManualChallengerInput {
+    readonly route: string;
+    readonly challenger: {
+        readonly provider: string;
+        readonly model: string;
+    };
+    /** The trial variant a bake-off replays (`trial-<provider>-<model>`). */
+    readonly variant: string;
+    readonly reason?: string;
+    /** Actor recorded in the trigger for the console (audit); NOT part of the hash. */
+    readonly requestedBy?: string;
+    /** Provenance columns (00055): exactly one is set for a console/oracle draft. */
+    readonly createdByUserId?: string | null;
+    readonly createdByKeyId?: string | null;
 }
 export declare function createProposalsClient(config: ProposalsClientConfig): ProposalsClient;
 //# sourceMappingURL=proposals.d.ts.map