modelrig 0.4.0 → 0.6.0

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");
@@ -25,37 +26,10 @@ const validate_1 = require("./validate");
 const dispatch_1 = require("./dispatch");
 const record_attempt_1 = require("./record-attempt");
 const ladder_key_1 = require("./ladder-key");
+const quality_gate_1 = require("./quality-gate");
+const accept_1 = require("./accept");
 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 +47,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 +71,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 +121,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)
@@ -190,6 +173,7 @@ async function run(deps, routeName, opts) {
                 failure: result.failure,
                 repairedBy,
                 pricingMissing: repairFailurePricingMissing,
+                metaInputs: (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: REPAIR_DIRECTIVE, outputSchema: route.outputSchema, result }),
             });
             if (failures_1.TERMINAL_CLASSES.has(result.failure.class)) {
                 throw new failures_1.RigFailureError(result.failure);
@@ -221,6 +205,7 @@ async function run(deps, routeName, opts) {
             failure,
             repairedBy,
             pricingMissing: repairPricingMissing,
+            metaInputs: (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: REPAIR_DIRECTIVE, outputSchema: route.outputSchema, result }),
         });
         captureAttempt(inferenceId, result.text);
         if (!outcome.valid) {
@@ -255,7 +240,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 = () => {
@@ -405,47 +390,45 @@ async function run(deps, routeName, opts) {
                     servedVariant,
                     pricingMissing,
                     callId: ladder.callId,
+                    metaInputs: (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: USER_DIRECTIVE, outputSchema: route.outputSchema, result, tools: opts.tools }),
                 });
             }
             const outcome = (0, validate_1.validateOutput)(route, result.text);
+            const metaInputs = (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: USER_DIRECTIVE, outputSchema: route.outputSchema, result, tools: opts.tools });
             if (outcome.valid) {
-                const inferenceId = recordAttempt({
-                    candidate,
-                    servedTier: result.usage.servedTier,
-                    tokensIn: result.usage.tokensIn,
-                    tokensOut: result.usage.tokensOut,
-                    tokensCached: result.usage.tokensCached,
-                    tokensCacheWrite: result.usage.tokensCacheWrite ?? 0,
-                    tokensCacheWrite1h: result.usage.tokensCacheWrite1h ?? 0,
-                    costUsd,
-                    latencyMs,
-                    ...(result.usage.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
-                    failure: null,
-                    pricingMissing,
-                });
+                // Q1 quality gate (spec §4.1): a schema-valid output must still clear the
+                // builder's bar before it is accepted. Tool-call turns never reach here;
+                // a `schema: null` route gates on the parsed JSON just the same. Gate
+                // logic (async await, fail-closed throw, tag/message shaping) lives in
+                // ./quality-gate.ts so this stays ONE seam.
+                const gateMeta = { route: route.route, provider: candidate.provider, model: candidate.model,
+                    candidateIndex: iter.index, attemptSeq: ladder.peekNextSeq(), servedVariant };
+                const gate = opts.qualityGate === undefined
+                    ? null
+                    : await (0, quality_gate_1.evaluateQualityGate)(opts.qualityGate, outcome.parsed, gateMeta);
+                if (gate !== null && !gate.pass) {
+                    // Rejected on quality: its OWN class + budget; the repair rung is NEVER
+                    // entered from here (spec §4.1 step 3). The rejected text is captured
+                    // so it stays replayable.
+                    const failure = { class: "quality_rejected",
+                        message: (0, quality_gate_1.qualityRejectedMessage)(gate), provider: candidate.provider, model: candidate.model };
+                    const rejectedId = recordAttempt((0, accept_1.successAttemptRow)(candidate, result.usage, costUsd, latencyMs, pricingMissing, failure, metaInputs, (0, quality_gate_1.qualityTags)(gate)));
+                    captureAttempt(rejectedId, result.text);
+                    lastFailure = failure;
+                    if (ledger.consume("quality_rejected"))
+                        continue; // re-sample the SAME candidate
+                    candidate = nextCandidate();
+                    continue;
+                }
+                const acceptTags = gate !== null ? (0, quality_gate_1.qualityTags)(gate) : undefined;
+                const inferenceId = recordAttempt((0, accept_1.successAttemptRow)(candidate, result.usage, costUsd, latencyMs, pricingMissing, null, metaInputs, acceptTags));
                 captureAttempt(inferenceId, result.text);
-                const meta = {
-                    inferenceId,
-                    route: route.route,
-                    routeVersion: route.version,
-                    provider: candidate.provider,
-                    model: candidate.model,
-                    requestedTier: route.policy.tier,
-                    servedTier: result.usage.servedTier,
-                    tokensIn: result.usage.tokensIn,
-                    tokensOut: result.usage.tokensOut,
-                    tokensCached: result.usage.tokensCached,
-                    costEstimateUsd: costUsd,
-                    latencyMs,
-                    validated: true,
-                    attemptsByClass: ledger.snapshot(),
-                    servedVariant,
-                    repairedBy: null,
-                    callId: ladder.callId,
-                    ...(injectedSources !== null
-                        ? { citations: (0, grounding_1.extractCitations)(result.text, injectedSources) }
-                        : {}),
-                };
+                const meta = (0, accept_1.buildSuccessMeta)({
+                    inferenceId, route, candidate, usage: result.usage, costUsd, latencyMs,
+                    attemptsByClass: ledger.snapshot(), servedVariant, callId: ladder.callId,
+                    ...(injectedSources !== null ? { citations: (0, grounding_1.extractCitations)(result.text, injectedSources) } : {}),
+                    ...(gate !== null ? { quality: { score: gate.score, verdict: "pass", judgedBy: null } } : {}),
+                });
                 return { output: outcome.parsed, meta };
             }
             // Schema-invalid output — a real (billed) attempt that failed.
@@ -468,6 +451,7 @@ async function run(deps, routeName, opts) {
                 ...(result.usage.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
                 failure,
                 pricingMissing,
+                metaInputs, // computed once above (same `result`) — reused across valid/invalid
             });
             captureAttempt(invalidId, result.text);
             lastFailure = failure;
@@ -520,6 +504,7 @@ async function run(deps, routeName, opts) {
             ...(result.usage?.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
             failure,
             pricingMissing: failurePricingMissing,
+            metaInputs: (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: USER_DIRECTIVE, outputSchema: route.outputSchema, result, tools: opts.tools }),
         });
         if (failures_1.TERMINAL_CLASSES.has(failure.class)) {
             throw new failures_1.RigFailureError(failure);

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/settings/index.d.ts

@@ -3,7 +3,7 @@
  * Re-exported from the SDK entrypoint so `index.ts` stays under the LOC cap and
  * the settings surface has one home.
  */
-export { createTaskSettingsResolver, effectiveCapture, DEFAULT_TASK_SETTINGS, } from "./task-settings";
+export { createTaskSettingsResolver, effectiveCapture, effectiveScrubMode, DEFAULT_TASK_SETTINGS, } from "./task-settings";
 export type { TaskSettings, TaskSettingsResolver, TaskSettingsFetcher } from "./task-settings";
 export { createApiTaskSettingsFetcher, startApiSettings } from "./api-fetcher";
 export type { ApiTaskSettingsFetcherConfig } from "./api-fetcher";

package/dist/settings/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/settings/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,EAAE,4BAA4B,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC/E,YAAY,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/settings/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,EAAE,4BAA4B,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC/E,YAAY,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC"}

package/dist/settings/index.js

@@ -5,10 +5,11 @@
  * the settings surface has one home.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startApiSettings = exports.createApiTaskSettingsFetcher = exports.DEFAULT_TASK_SETTINGS = exports.effectiveCapture = exports.createTaskSettingsResolver = void 0;
+exports.startApiSettings = exports.createApiTaskSettingsFetcher = exports.DEFAULT_TASK_SETTINGS = exports.effectiveScrubMode = exports.effectiveCapture = exports.createTaskSettingsResolver = void 0;
 var task_settings_1 = require("./task-settings");
 Object.defineProperty(exports, "createTaskSettingsResolver", { enumerable: true, get: function () { return task_settings_1.createTaskSettingsResolver; } });
 Object.defineProperty(exports, "effectiveCapture", { enumerable: true, get: function () { return task_settings_1.effectiveCapture; } });
+Object.defineProperty(exports, "effectiveScrubMode", { enumerable: true, get: function () { return task_settings_1.effectiveScrubMode; } });
 Object.defineProperty(exports, "DEFAULT_TASK_SETTINGS", { enumerable: true, get: function () { return task_settings_1.DEFAULT_TASK_SETTINGS; } });
 var api_fetcher_1 = require("./api-fetcher");
 Object.defineProperty(exports, "createApiTaskSettingsFetcher", { enumerable: true, get: function () { return api_fetcher_1.createApiTaskSettingsFetcher; } });

package/dist/settings/task-settings.d.ts

@@ -88,4 +88,14 @@ export declare function createTaskSettingsResolver(config: TaskSettingsResolverC
  * because there is no control-plane row to resolve.
  */
 export declare function effectiveCapture(resolver: TaskSettingsResolver | null, task: string | undefined, yamlCapture: boolean): boolean;
+/**
+ * The EFFECTIVE scrub mode for an artifact, given the task's configured mode and
+ * the artifact's `data_classification` (screening SC-0 S8-c). A `pii`/`phi`
+ * artifact resolves a FLOOR of `redact` — content carrying PII/PHI is never
+ * uploaded verbatim just because the task's mode was `off`/`detect`. A stronger
+ * configured mode wins: `block` stays `block` (block ≥ redact — it refuses the
+ * upload entirely). A non-sensitive (or absent) classification leaves the
+ * configured mode untouched. Pure; the single place the floor is spelled.
+ */
+export declare function effectiveScrubMode(configured: ScrubMode, classification: string | null | undefined): ScrubMode;
 //# sourceMappingURL=task-settings.d.ts.map

package/dist/settings/task-settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-settings.d.ts","sourceRoot":"","sources":["../../src/settings/task-settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C;0EAC0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,iBAAiB,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B;AAED;;;uCAGuC;AACvC,eAAO,MAAM,qBAAqB,EAAE,YAKnC,CAAC;AAEF;;;2EAG2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,oBAAoB;IACnC;sFACkF;IAClF,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC;IAChC;oEACgE;IAChE,QAAQ,IAAI,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC9C;;gEAE4D;IAC5D,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;2EACuE;IACvE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,4CAA4C;IAC5C,KAAK,IAAI,IAAI,CAAC;IACd,2CAA2C;IAC3C,IAAI,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC;gFAC4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;IACtF,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,KAAK,IAAI,CAAC;CAC3E;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,0BAA0B,GACjC,oBAAoB,CA4DtB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,oBAAoB,GAAG,IAAI,EACrC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,WAAW,EAAE,OAAO,GACnB,OAAO,CAGT"}
+{"version":3,"file":"task-settings.d.ts","sourceRoot":"","sources":["../../src/settings/task-settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C;0EAC0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,iBAAiB,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B;AAED;;;uCAGuC;AACvC,eAAO,MAAM,qBAAqB,EAAE,YAKnC,CAAC;AAEF;;;2EAG2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,oBAAoB;IACnC;sFACkF;IAClF,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC;IAChC;oEACgE;IAChE,QAAQ,IAAI,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC9C;;gEAE4D;IAC5D,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;2EACuE;IACvE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,4CAA4C;IAC5C,KAAK,IAAI,IAAI,CAAC;IACd,2CAA2C;IAC3C,IAAI,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC;gFAC4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;IACtF,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,KAAK,IAAI,CAAC;CAC3E;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,0BAA0B,GACjC,oBAAoB,CA4DtB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,oBAAoB,GAAG,IAAI,EACrC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,WAAW,EAAE,OAAO,GACnB,OAAO,CAGT;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,SAAS,EACrB,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACxC,SAAS,CAIX"}

package/dist/settings/task-settings.js

@@ -27,6 +27,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_TASK_SETTINGS = void 0;
 exports.createTaskSettingsResolver = createTaskSettingsResolver;
 exports.effectiveCapture = effectiveCapture;
+exports.effectiveScrubMode = effectiveScrubMode;
+const classification_1 = require("../artifacts/classification");
 /** The safe floor for a task the control plane has not answered for yet: capture
  * OFF, artifacts inherit the default, content OFF, scrub the schema default. A
  * run that reaches the cache before the first fetch lands sees this — never a
@@ -114,3 +116,18 @@ function effectiveCapture(resolver, task, yamlCapture) {
         return yamlCapture;
     return resolver.get(task).capture;
 }
+/**
+ * The EFFECTIVE scrub mode for an artifact, given the task's configured mode and
+ * the artifact's `data_classification` (screening SC-0 S8-c). A `pii`/`phi`
+ * artifact resolves a FLOOR of `redact` — content carrying PII/PHI is never
+ * uploaded verbatim just because the task's mode was `off`/`detect`. A stronger
+ * configured mode wins: `block` stays `block` (block ≥ redact — it refuses the
+ * upload entirely). A non-sensitive (or absent) classification leaves the
+ * configured mode untouched. Pure; the single place the floor is spelled.
+ */
+function effectiveScrubMode(configured, classification) {
+    if (classification == null || !classification_1.SENSITIVE_CLASSIFICATIONS.has(classification))
+        return configured;
+    // Sensitive tier: never below `redact`. `block` is stronger and stays.
+    return configured === "block" ? "block" : "redact";
+}