modelrig 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -10,6 +10,135 @@ published package diverge.
 This project adheres to [Semantic Versioning](https://semver.org/). Dates are
 UTC.
 
+## [0.5.0] — 2026-08-22
+
+Released with the docs/registry mirror in one R-A ceremony. Headline for router
+codebases: `rig.runRaw` inside a run context now records a step (the `/runs`
+tree fills in), raw-lane timeouts are tier-aware and teach, the `trial:`
+candidate flag + console picker ship (deploy the server before any YAML uses
+`trial:`), and the console rollups show cost and quality together by route or
+tag. `modelrig-oracle` 0.2.0 ships alongside (`propose_candidates`).
+
+Raw-lane defaults (#245) — the raw lane teaches its own timeouts. The `timeoutMs`
+default becomes tier-aware, a `timeout` failure carries a teaching `fixHint`, an
+empty no-tools gemini response carries a hint naming grounding, and the raw-lane
+defaults are published as a generated table that cannot drift from the runtime.
+
+Declare-first experiment ergonomics (routing-console R3, #239) — a `trial:`
+candidate you declare but never serve live, a console challenger picker, and a
+one-command bake-off that measures it on real captured traffic before you
+promote it.
+
+### Changed
+
+- **Raw-lane `timeoutMs` default is now tier-aware** (was a flat 120 s):
+  `standard`/`priority` default to 300 s and `flex` to 900 s (the 15-minute budget
+  ModelRig advertises) — a passthrough should not be shorter-fused than the tier it
+  advertises, and grounded/large prompts routinely exceed 120 s even at standard.
+  An explicit `timeoutMs` **always wins** (no pre-dispatch rejection — a short
+  deadline is a choice), and a `timeout` failure on the raw lane now carries a
+  `fixHint` naming the elapsed time, the tier, that tier's budget, and the two
+  fixes (raise `timeoutMs`, or drop to `serviceTier: "standard"`). The routed
+  lane's required `policy.timeout_ms` is unchanged. Callers who relied on a fast
+  120 s failure should set `timeoutMs` explicitly.
+
+### Added — declare-first experiment (routing-console R3)
+
+- **`candidates[].trial: true`** (route bundle) — a DECLARED candidate that is
+  NEVER served live. The loader parses and validates it, marks an all-trial
+  variant `trialOnly`, and warns on a trial candidate no variant references;
+  `resolveCandidates` drops trial candidates on every live path (`rig.run`,
+  `runStream`, `runBundle`, the hosted gateway slug lane) and keeps them only in
+  bake-off replay. Selecting a trial variant on a live call is a
+  `RouteConfigError` that names the bake-off. This lets a customer measure a new
+  model on real captured traffic before promoting it. Additive: a route with no
+  trial candidate is byte-identical to before.
+  - CAVEAT — **deploy the server before any customer YAML carries `trial:`.** An
+    SDK/server older than 0.5.0 IGNORES `trial:` (the loader has always been
+    tolerant of unknown candidate keys) and its resolver has no trial-mode filter,
+    so it would serve the candidate LIVE — including an older hosted-gateway build
+    reading the flag through the mirror. Roll the server first, then let routes
+    start declaring `trial:`. The console's declare-YAML says so inline.
+- **`requirementPredicates(route)` / `evaluateChallengerEligibility(...)`** (new
+  exports) — decompose a route's `require` + json rung into capability-flag
+  requirements and answer "can this model be a trial challenger?", pinned in
+  agreement with the live resolver's `satisfiesRequirements`.
+- **`buildDeclareTrialChange(bundle, challenger)` / `trialVariantName(...)`** and
+  a trial-winner branch of **`buildSwapChange`** (new exports) — the paste-ready
+  declare-YAML (challenger appended `trial: true`, a `trial-<provider>-<model>`
+  variant, `version: n+1`) and the promote-YAML that drops the winner's trial
+  flag, moves it to position 0, and removes the trial variant. No filesystem, no
+  git — the human applies the PR (F6).
+- **`ManualChallengerTrigger` + `manualChallengerTriggerHash`**, and
+  **`proposalsClient.createManualChallenger`** — a console/oracle-initiated
+  declare-first proposal (`kind:"bakeoff"`, idempotent per `(route, challenger)`).
+- **`RunMeta`/`Rig` additions:** `rig.capabilities` and `rig.searchAvailable` are
+  exposed so the challenger picker answers eligibility with the exact live flags;
+  `modelrig bakeoff --from-proposal <id>` reads the trial variant from a
+  manual_challenger proposal (default vs that one variant).
+- **`resolveRouteBundle` / `hashResolvedBundle`** (new exports) — the canonical
+  `bundle_sha` helpers, used by the hosted-lane bake-off to prove the caller org's
+  mirrored bundle is the SAME bundle the deployment holds locally (a route-name
+  collision on a multi-tenant mirror otherwise baked off a foreign org's route).
+
+### Added
+
+- **A grounding-naming `fixHint` on an empty no-tools gemini response.** When a
+  call that declared no tools comes back with no text parts (a grounding turn
+  that produced only `functionCall` parts, for example), the `content_invalid`
+  "empty response" failure now names grounding as the likely cause. Note: the
+  text extraction itself is unchanged in effect — the SDK already concatenated
+  mixed `functionCall` + text parts — so the customer-zero empty-response report
+  (#245 secondary) remains an OPEN investigation pending a captured response.
+
+### Docs
+
+- **Raw-lane defaults table** — a generated table (`RAW_DEFAULTS`, rendered at the
+  `<!-- RAW_DEFAULTS -->` marker in `route-bundles.md` and in `llms.txt`) lists
+  every raw-lane knob and its default, with the tier-aware `timeoutMs` read from
+  the same constant the runtime resolves from — so the published defaults cannot
+  drift from what `rig.runRaw` sends. README / quickstart / migration-playbook
+  gain the "flex ⇒ set `timeoutMs` in minutes" one-liner.
+
+Raw-lane artifact graph + tags parity (G1). A `rig.runRaw` / `rig.runRawStream`
+call inside a `rig.artifacts.run.start` context now records a ground-truth step,
+so a router or report pipeline that wraps raw (BYOK) calls in a run context gets
+a real per-run tree at `/runs/[id]` instead of an empty one. ZERO DDL.
+
+### Added — raw-lane graph
+
+- **Raw calls record a ground-truth step.** Inside a run context,
+  `runRaw`/`runRawStream` emit a step (on success AND failure, buffered AND
+  streaming) whose `inference_id` joins the metered `lane=raw` row — parity with
+  the routed lane's auto-step. Fail-open: a buffer error there never affects the
+  returned result. Outside a run context the dispatch is byte-identical to 0.4.0
+  (no step row). Raw steps are **metadata only** — no artifact content is written
+  on the raw lane.
+- **`stepKey` on BOTH lanes.** `RunOptions.stepKey` (routed) and
+  `RawRunInput.stepKey` (raw) name the step. Resolution is `stepKey ?? tags.step
+  ?? auto` (`route#n` / `provider/model#n`), validated `[A-Za-z0-9_.:#-]{1,128}`;
+  an invalid value is warned once and dropped to the auto key (never thrown). A
+  raw row's step **task** is `tags.step ?? provider/model`.
+- **Ambient artifact step.** `artifact.save` without a `stepKey` now attaches to
+  the ambient step (the most recent step in the run context), so the two grouping
+  mechanisms compose — a raw/routed call and the artifacts saved around it land in
+  one group.
+- **Required-dimension hygiene on the raw lane.** `runRaw`/`runRawStream` run the
+  same once-per-process "required dimension missing from tags" warning the routed
+  lane does.
+
+### Added — docs
+
+- **instrumentation.md** gains "Tags, dimensions, and the graph": tags = flat
+  filter/rollup (`/costs`), the graph = the per-run tree (`/runs/[id]`), how
+  `stepKey` + ambient artifacts compose, and the raw-lane behavior.
+- **The per-service key rule** is now stated in the quickstart, the migration
+  playbook (F-6), and llms.txt: `MODELRIG_API_KEY` gates the exporter *per
+  process* — set it on EVERY service, worker, and cron, or a keyless process
+  buffers to its own local SQLite and ships nothing.
+- **route-bundles.md** points at where `rig.yaml` `dimensions` are declared; the
+  **README** documents `stepKey` on the raw lane.
+
 ## [0.4.0] — 2026-08-22
 
 Released with the docs/registry mirror in one R-A ceremony. NOT in this tag:

package/README.md

@@ -144,6 +144,19 @@ never stores it. It records one metered `lane=raw` telemetry row at the
 provider's list price (zero ModelRig margin) and throws a typed `RigFailureError`
 on failure, exactly like `rig.run`.
 
+Called inside a `rig.artifacts.run.start` context, `runRaw`/`runRawStream` also
+records a ground-truth **step** in the run's graph (`/runs/[id]`) — since
+modelrig 0.5.0, on success and on failure. Name it with `stepKey` (the same field
+`RunOptions` exposes on the routed lane; precedence `stepKey` > `tags.step` > an
+auto `provider/model#n` key), so a raw call and the artifacts you `save` around it
+group under one step.
+
+The raw-lane `timeoutMs` default is **tier-aware** since 0.5.0 — `standard`/
+`priority` 300 s, `flex` 900 s; an explicit `timeoutMs` always wins, and a
+`timeout` failure teaches the tier + budget in its `fixHint`. **flex ⇒ set
+`timeoutMs` in minutes** (default 900 s since 0.5.0). See the generated
+[raw-lane defaults table](https://modelrig.dev/route-bundles.html#raw-lane-defaults-rigrunraw).
+
 **runRaw-only construction (`routesDir: null`) — 0.4.0+.** A
 Lane-B deployment that ONLY calls `runRaw`/`runRawStream` has no routes. Build it
 with `routesDir: null` and `createRig` skips route loading, the `rig.yaml`

package/dist/adapters/gemini.d.ts

@@ -56,5 +56,44 @@ export interface GeminiShapedRequest {
 }
 /** Pure request shaping — everything except the abort signal. */
 export declare function buildGeminiRequest(model: string, req: ShapingInput): GeminiShapedRequest;
+/** A candidate's parts as we read them post-response — `functionCall`, `text`,
+ * and (if `includeThoughts` were ever set) a `thought`-flagged text part may all
+ * appear on the same candidate (a grounded / thinking turn). */
+type GeminiCandidatePart = {
+    readonly functionCall?: unknown;
+    readonly text?: string;
+    readonly thought?: boolean;
+};
+type GeminiCandidateShape = {
+    readonly content?: {
+        readonly parts?: readonly GeminiCandidatePart[];
+    };
+};
+/**
+ * #245 secondary — concatenate the answer `text` parts of a Gemini candidate's
+ * content. On the raw / no-tools lane a grounding-originated `functionCall` part
+ * (googleSearch) is NOT a tool-call turn, and the SDK's `response.text` getter
+ * returns empty (and logs a warning) on a response that mixes `functionCall` +
+ * `text` parts — so read the text parts directly. `thought`-flagged parts are
+ * skipped to match `response.text` semantics (they are the reasoning summary, not
+ * the answer). Pure + exported for the fixture regression test (no network).
+ * (spec §2 Secondary — the SNPS bug.)
+ */
+export declare function extractGeminiCandidateText(candidate: GeminiCandidateShape | undefined): string;
+/** #245 secondary — whether a candidate carries a `functionCall` part. On the
+ * no-tools lane this means grounding produced only a googleSearch invocation with
+ * no text answer, which the empty-response `fixHint` should name. */
+export declare function geminiCandidateHasFunctionCall(candidate: GeminiCandidateShape | undefined): boolean;
+/**
+ * #245 secondary — pick the answer text from a Gemini response. The branch the
+ * `call()` path uses, extracted pure so it is unit-testable without a network:
+ *  - tools declared: trust the SDK `response.text` getter, byte-identical to
+ *    pre-#245 (a functionCall turn is handled earlier as a tool-call).
+ *  - no tools declared: read the candidate's text parts directly, because
+ *    `response.text` returns empty on a grounding-originated functionCall+text
+ *    response; fall back to `response.text` only if there is no text part.
+ */
+export declare function resolveGeminiText(candidate: GeminiCandidateShape | undefined, responseText: string | undefined, hasTools: boolean): string;
 export declare function createGeminiAdapter(config: GeminiAdapterConfig): ProviderAdapter;
+export {};
 //# sourceMappingURL=gemini.d.ts.map

package/dist/adapters/gemini.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../src/adapters/gemini.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EACV,cAAc,EAGd,cAAc,EACd,eAAe,EAEhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,mBAAmB,CAAC;AAKlE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;mCAImC;AACnC,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,MAAM,CAI7D,CAAC;AA0BH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG9E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAyCxE;AAED;6EAC6E;AAC7E,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;AAE7D;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,iBAAiB,GAAG,IAAI,CAQrG;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,mBAAmB,CAqDxF;AA0BD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,eAAe,CA+JhF"}
+{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../src/adapters/gemini.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EACV,cAAc,EAGd,cAAc,EACd,eAAe,EAEhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,mBAAmB,CAAC;AAKlE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;mCAImC;AACnC,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,MAAM,CAI7D,CAAC;AA0BH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG9E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAyCxE;AAED;6EAC6E;AAC7E,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;AAE7D;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,iBAAiB,GAAG,IAAI,CAQrG;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,mBAAmB,CAqDxF;AA0BD;;gEAEgE;AAChE,KAAK,mBAAmB,GAAG;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AACF,KAAK,oBAAoB,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAA;KAAE,CAAA;CAAE,CAAC;AAEvG;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,oBAAoB,GAAG,SAAS,GAAG,MAAM,CAM9F;AAED;;qEAEqE;AACrE,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,oBAAoB,GAAG,SAAS,GAAG,OAAO,CAInG;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,oBAAoB,GAAG,SAAS,EAC3C,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,QAAQ,EAAE,OAAO,GAChB,MAAM,CAGR;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,eAAe,CA+KhF"}

package/dist/adapters/gemini.js

@@ -20,6 +20,9 @@ exports.geminiSupports = geminiSupports;
 exports.classifyGeminiFailure = classifyGeminiFailure;
 exports.geminiReasoningUnsupported = geminiReasoningUnsupported;
 exports.buildGeminiRequest = buildGeminiRequest;
+exports.extractGeminiCandidateText = extractGeminiCandidateText;
+exports.geminiCandidateHasFunctionCall = geminiCandidateHasFunctionCall;
+exports.resolveGeminiText = resolveGeminiText;
 exports.createGeminiAdapter = createGeminiAdapter;
 const genai_1 = require("@google/genai");
 const tool_mapping_1 = require("./tool-mapping");
@@ -190,6 +193,43 @@ function extractServedTier(rawServiceTier, trafficType, requested) {
         return "priority";
     return requested;
 }
+/**
+ * #245 secondary — concatenate the answer `text` parts of a Gemini candidate's
+ * content. On the raw / no-tools lane a grounding-originated `functionCall` part
+ * (googleSearch) is NOT a tool-call turn, and the SDK's `response.text` getter
+ * returns empty (and logs a warning) on a response that mixes `functionCall` +
+ * `text` parts — so read the text parts directly. `thought`-flagged parts are
+ * skipped to match `response.text` semantics (they are the reasoning summary, not
+ * the answer). Pure + exported for the fixture regression test (no network).
+ * (spec §2 Secondary — the SNPS bug.)
+ */
+function extractGeminiCandidateText(candidate) {
+    return (candidate?.content?.parts ?? [])
+        .filter((p) => p.thought !== true)
+        .map((p) => p.text)
+        .filter((t) => typeof t === "string")
+        .join("");
+}
+/** #245 secondary — whether a candidate carries a `functionCall` part. On the
+ * no-tools lane this means grounding produced only a googleSearch invocation with
+ * no text answer, which the empty-response `fixHint` should name. */
+function geminiCandidateHasFunctionCall(candidate) {
+    return (candidate?.content?.parts ?? []).some((p) => p.functionCall !== undefined && p.functionCall !== null);
+}
+/**
+ * #245 secondary — pick the answer text from a Gemini response. The branch the
+ * `call()` path uses, extracted pure so it is unit-testable without a network:
+ *  - tools declared: trust the SDK `response.text` getter, byte-identical to
+ *    pre-#245 (a functionCall turn is handled earlier as a tool-call).
+ *  - no tools declared: read the candidate's text parts directly, because
+ *    `response.text` returns empty on a grounding-originated functionCall+text
+ *    response; fall back to `response.text` only if there is no text part.
+ */
+function resolveGeminiText(candidate, responseText, hasTools) {
+    if (hasTools)
+        return responseText ?? "";
+    return extractGeminiCandidateText(candidate) || (responseText ?? "");
+}
 function createGeminiAdapter(config) {
     const ai = new genai_1.GoogleGenAI({ apiKey: config.apiKey });
     return {
@@ -266,9 +306,20 @@ function createGeminiAdapter(config) {
                 if (finishReason === "RECITATION") {
                     return fail("refusal", "Gemini blocked output via recitation filter (finishReason=RECITATION)", undefined, usage);
                 }
-                const text = response.text ?? "";
+                // #245 secondary: when the caller declared NO tools, a `functionCall`
+                // part is grounding-originated (googleSearch), NOT a tool-call turn — and
+                // `response.text` returns empty on a mixed functionCall+text response, so
+                // read the text parts directly. When tools WERE declared this path is
+                // reached only for a no-functionCall response, so `response.text` is
+                // byte-identical to before.
+                const noTools = req.tools === undefined || req.tools.length === 0;
+                const text = resolveGeminiText(candidates?.[0], response.text, !noTools);
                 if (text.trim().length === 0) {
-                    return fail("content_invalid", `empty response from Gemini (finishReason=${finishReason ?? "none"})`, undefined, usage);
+                    const groundedNoText = noTools &&
+                        geminiCandidateHasFunctionCall(candidates?.[0]);
+                    return fail("content_invalid", `empty response from Gemini (finishReason=${finishReason ?? "none"})`, groundedNoText
+                        ? "the grounded response returned only a googleSearch functionCall part with no text — refine the grounding query, or remove grounding if the model can answer directly"
+                        : undefined, usage);
                 }
                 if (finishReason === "MAX_TOKENS" && req.outputSchema !== null) {
                     // A truncated structured emission is mid-object and unparseable.

package/dist/artifacts/artifact.d.ts

@@ -39,8 +39,9 @@ export interface ArtifactSaveOptions {
     /** The pipeline step this artifact belongs to — the semantic grouping key the
      * console's chain view orders on (E3 spec §2.1). E2 deferred step attribution
      * ("refined when @step scopes persist, E3"); an EXPLICIT key set by the caller
-     * is the E3 refinement — safe under parallel step waves where an ambient
-     * mutable current-step would cross-attribute. Null (absent) ⇒ ungrouped. */
+     * is the E3 refinement and stays the safe choice under parallel steps inside
+     * ONE run; absent one, the ambient current step (G1) is used — see
+     * run-context.ts currentStepKey(). Null (no key, no context) ⇒ ungrouped. */
     readonly stepKey?: string;
     /** The step attempt this artifact came from (mirrors steps.attempt_no). Only
      * meaningful alongside stepKey; null for artifacts saved outside a step. */

package/dist/artifacts/artifact.d.ts.map

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

package/dist/artifacts/artifact.js

@@ -166,6 +166,11 @@ function createArtifactApi(deps) {
             const schema = opts.schema ?? null;
             const id = (0, node_crypto_1.randomUUID)();
             const version = opts.supersedes !== undefined ? opts.supersedes.version + 1 : 1;
+            // G1 (spec §3): an explicit stepKey wins; absent, the artifact lands in the
+            // AMBIENT step — the most recent auto-step in this run context — so
+            // `artifact.save` and the run/@step graph compose. Null outside a step (or
+            // outside a run context), exactly as before.
+            const stepKey = opts.stepKey ?? ctx?.currentStepKey() ?? null;
             // Custody applies only when a rig content policy exists AND the caller left
             // the bytes to us (a caller-supplied contentRef = their own store; managed
             // custody must not double-home it).
@@ -181,9 +186,10 @@ function createArtifactApi(deps) {
                 store.recordArtifact({
                     id,
                     runId: ctx?.runId ?? null,
-                    // E3: step attribution is now an explicit caller-supplied key (see
-                    // ArtifactSaveOptions.stepKey). Absent ⇒ null, exactly as before.
-                    stepKey: opts.stepKey ?? null,
+                    // E3: step attribution is an explicit caller-supplied key; G1 adds the
+                    // ambient-step fallback (resolved above) so a save with no stepKey joins
+                    // the current run/@step. Absent both ⇒ null, exactly as before.
+                    stepKey,
                     attemptNo: opts.attemptNo ?? null,
                     task: opts.task ?? null,
                     name: opts.name,
@@ -243,7 +249,8 @@ function createArtifactApi(deps) {
                         store.recordArtifact({
                             id: redactedId,
                             runId: ctx?.runId ?? null,
-                            stepKey: opts.stepKey ?? null,
+                            // Same ambient-step resolution as the original row it supersedes.
+                            stepKey,
                             attemptNo: opts.attemptNo ?? null,
                             task: opts.task ?? null,
                             name: opts.name,

package/dist/artifacts/run-context.d.ts

@@ -68,16 +68,35 @@ export interface ActiveRunContext {
     takeLoadedIds(): string[];
     /** Mint a unique step key for ONE rig.run()/@step invocation. Retries of that
      * invocation reuse the returned key (attempt_no distinguishes them); a later
-     * invocation gets a fresh key, so two calls never collapse into one step. */
+     * invocation gets a fresh key, so two calls never collapse into one step. Also
+     * marks the minted key as the ambient step (see currentStepKey). */
     nextStepKey(label: string): string;
+    /** The most recent step key in this context — the ambient step an
+     * `artifact.save` without an explicit `stepKey` attaches to (G1 spec §3). Set
+     * by both `nextStepKey` (auto-steps, `@step` scopes) and `emitGroundTruthStep`
+     * (a raw-lane call with a caller-supplied key that never minted). Null before
+     * any step in this run. NOTE: a single mutable current-step cross-attributes
+     * under parallel step waves on ONE context — use `run.scope()` (each concurrent
+     * run gets its own context) or an explicit `stepKey` when steps overlap. */
+    currentStepKey(): string | null;
     /** Record one ground-truth step attempt (the rig.run auto-step). attempt_no is
      * assigned here, per step key. Fail-open — a buffer error is logged, dropped,
-     * and never thrown into the run loop. */
+     * and never thrown into the run loop. Marks its key as the ambient step. */
     emitGroundTruthStep(input: GroundTruthStepInput): void;
 }
 /** The active run context, or null when none is set (namespace disabled, or no
  * run.start on this async path). Read by the run loop's auto-step seam. */
 export declare function getActiveRunContext(): ActiveRunContext | null;
+/** True when `key` is a valid caller-supplied step key (spec §3). */
+export declare function isValidStepKey(key: string): boolean;
+/** Resolve a ground-truth step key for either lane (spec §3): an explicit
+ * caller-supplied key wins, then the `tags.step` convention, else a freshly
+ * minted auto key. A caller key is validated `[A-Za-z0-9_.:#-]{1,128}`; an
+ * invalid one is warned (once per bad value) and DROPPED to the auto key —
+ * instrumentation never throws a telemetry-label error into customer code. */
+export declare function resolveStepKey(explicit: string | undefined, tagStep: string | undefined, auto: () => string): string;
+/** Test-only: clear the once-per-process invalid-stepKey warning latch. */
+export declare function resetStepKeyWarningsForTest(): void;
 /** A run-level evaluation the caller attaches (E5 chunk V.2) — the run-subject
  * mirror of ArtifactEvaluateOptions. The subject is the run, so there is no ref. */
 export interface RunEvaluateOptions {

package/dist/artifacts/run-context.d.ts.map

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

package/dist/artifacts/run-context.js

@@ -21,6 +21,9 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getActiveRunContext = getActiveRunContext;
+exports.isValidStepKey = isValidStepKey;
+exports.resolveStepKey = resolveStepKey;
+exports.resetStepKeyWarningsForTest = resetStepKeyWarningsForTest;
 exports.createRunNamespace = createRunNamespace;
 const node_async_hooks_1 = require("node:async_hooks");
 const node_crypto_1 = require("node:crypto");
@@ -32,6 +35,38 @@ function getActiveRunContext() {
     const ctx = storage.getStore();
     return ctx !== undefined && !ctx.ended ? ctx : null;
 }
+/** Valid ground-truth step key (G1 spec §3): a caller-supplied `stepKey` (either
+ * lane) or a `tags.step` used as one. Auto-minted keys (`label#seq`) may contain
+ * a `/` from a route slug or `provider/model` label and are NOT validated — the
+ * regex gates only what a customer types. */
+const STEP_KEY_PATTERN = /^[A-Za-z0-9_.:#-]{1,128}$/;
+/** True when `key` is a valid caller-supplied step key (spec §3). */
+function isValidStepKey(key) {
+    return STEP_KEY_PATTERN.test(key);
+}
+const warnedStepKeys = new Set();
+/** Resolve a ground-truth step key for either lane (spec §3): an explicit
+ * caller-supplied key wins, then the `tags.step` convention, else a freshly
+ * minted auto key. A caller key is validated `[A-Za-z0-9_.:#-]{1,128}`; an
+ * invalid one is warned (once per bad value) and DROPPED to the auto key —
+ * instrumentation never throws a telemetry-label error into customer code. */
+function resolveStepKey(explicit, tagStep, auto) {
+    const candidate = explicit ?? tagStep;
+    if (candidate === undefined)
+        return auto();
+    if (isValidStepKey(candidate))
+        return candidate;
+    if (!warnedStepKeys.has(candidate)) {
+        warnedStepKeys.add(candidate);
+        console.warn(`[modelrig artifacts] invalid stepKey "${candidate}" (allowed [A-Za-z0-9_.:#-], 1-128 chars) — ` +
+            "grouped under an auto-generated key instead.");
+    }
+    return auto();
+}
+/** Test-only: clear the once-per-process invalid-stepKey warning latch. */
+function resetStepKeyWarningsForTest() {
+    warnedStepKeys.clear();
+}
 function warnOnce(scope, err) {
     console.warn(`[modelrig artifacts] ${scope} buffer write failed (dropped, run unaffected): ` +
         `${err instanceof Error ? err.message : String(err)}`);
@@ -67,6 +102,9 @@ function createRunNamespace(deps) {
         const attemptByStep = new Map();
         const loaded = new Set();
         let stepSeq = 0;
+        // The ambient step key (G1): the last step minted or emitted in this run,
+        // which an artifact.save without an explicit stepKey attaches to.
+        let lastStepKey = null;
         return {
             runId,
             traceId,
@@ -84,9 +122,16 @@ function createRunNamespace(deps) {
             },
             nextStepKey(label) {
                 stepSeq += 1;
-                return `${label}#${stepSeq}`;
+                lastStepKey = `${label}#${stepSeq}`;
+                return lastStepKey;
+            },
+            currentStepKey() {
+                return lastStepKey;
             },
             emitGroundTruthStep(input) {
+                // A caller-supplied key on the raw lane never minted through nextStepKey;
+                // record it as the ambient step so artifacts saved around this call join it.
+                lastStepKey = input.stepKey;
                 const attemptNo = (attemptByStep.get(input.stepKey) ?? 0) + 1;
                 attemptByStep.set(input.stepKey, attemptNo);
                 try {

package/dist/bakeoff/replay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/bakeoff/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;uCAEmC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;yDACqD;IACrD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;sDACkD;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,YAAY,EACtB,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAsExC"}
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/bakeoff/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAI1C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;uCAEmC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;yDACqD;IACrD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;sDACkD;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,YAAY,EACtB,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAwFxC"}

package/dist/bakeoff/replay.js

@@ -23,16 +23,29 @@ exports.replayVariant = replayVariant;
 const node_crypto_1 = require("node:crypto");
 const failures_1 = require("../types/failures");
 const run_1 = require("../run/run");
+const variant_1 = require("../run/variant");
 async function replayVariant(deps, captures, req) {
     const rows = captures.readLast(req.route, req.lastN);
     const replayId = (0, node_crypto_1.randomUUID)();
     const envelopeKey = `replay:${replayId}`;
+    // Trial mode is scoped to the ARM being replayed, not the whole pass. A
+    // bake-off measures a declared trial candidate ONLY under a trial-only
+    // variant arm; the `default` arm (and any non-trial variant) must replay in
+    // LIVE mode so the incumbent never admits the cheaper trial candidate —
+    // otherwise `prefer:[cost]` would pick the trial model on BOTH arms and the
+    // comparison degenerates to trial-vs-trial (armMeta then misreports the
+    // incumbent). `mode: "trial"` keeps trial candidates and permits selecting a
+    // trial variant; `live` drops them, exactly as every production surface does.
+    const route = deps.routes.get(req.route);
+    const variant = req.variant === "default" ? undefined : route.variants.find((v) => v.name === req.variant);
+    const mode = variant !== undefined && (0, variant_1.isTrialOnlyVariant)(route, variant) ? "trial" : "live";
     // Zero production exposure knobs: no capture writes (no replay-of-replay),
     // and the whole pass shares one hard envelope.
     const replayDeps = {
         ...deps,
         captures: null,
         envelopeBudgetUsd: req.envelopeUsd,
+        mode,
     };
     const results = [];
     for (const capture of rows) {
@@ -48,8 +61,11 @@ async function replayVariant(deps, captures, req) {
             // text — plan §10 replay-validity risk), repair/grounding rungs and
             // retry budgets all behave exactly as production serving would.
             const result = await (0, run_1.run)(replayDeps, req.route, {
+                // `lane: "trial"` (spec §4.4) tags every replay attempt row so the R1
+                // route rollups and the savings odometer EXCLUDE trial spend — a
+                // bake-off's real dispatches must never move a live route's numbers.
+                tags: { replay: replayId, replay_capture: sampleTag, variant: req.variant, lane: "trial" },
                 input: JSON.parse(capture.variablesJson),
-                tags: { replay: replayId, replay_capture: sampleTag, variant: req.variant },
                 ...(req.variant !== "default" ? { variant: req.variant } : {}),
                 budget: { envelope: envelopeKey },
             });

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG;AAkCH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpC;AAeD,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAuBxD;AA0gBD,wBAAsB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqCnE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG;AAkCH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpC;AAeD,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAuBxD;AA+hBD,wBAAsB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqCnE"}

package/dist/cli.js

@@ -159,7 +159,27 @@ async function cmdBakeoff(flags) {
         }
         const routes = (0, loader_1.loadRoutes)((0, rawonly_1.requireRoutesDir)(config, "modelrig bakeoff"));
         const bundle = routes.get(proposal.route);
-        const variants = ["default", ...bundle.variants.map((v) => v.name)];
+        // Declare-first (routing-console spec §4.4, R3): a manual_challenger proposal
+        // names ONE trial variant — bake off default vs that variant only. The trial
+        // variant must be DECLARED in the local routes (the human merged the
+        // declare-YAML); until then it isn't loadable, so fail with a teaching error
+        // rather than a bake-off that silently omits the challenger.
+        let variants;
+        const trigger = proposal.trigger;
+        if (trigger.type === "manual_challenger") {
+            const trialVariant = trigger.variant;
+            if (typeof trialVariant !== "string" || trialVariant === "") {
+                throw new Error(`proposal ${proposalId} is a manual_challenger with no trial variant name`);
+            }
+            if (!bundle.variants.some((v) => v.name === trialVariant)) {
+                throw new Error(`route "${proposal.route}" does not declare the trial variant "${trialVariant}" yet — ` +
+                    "merge the declare-YAML from the proposal first (modelrig ... declare-body), then re-run");
+            }
+            variants = ["default", trialVariant];
+        }
+        else {
+            variants = ["default", ...bundle.variants.map((v) => v.name)];
+        }
         const lastRaw = flags.named.get("replay-last");
         const replayLastN = lastRaw !== undefined ? Number(lastRaw) : 25;
         if (!Number.isInteger(replayLastN) || replayLastN < 1) {