modelrig 0.3.0 → 0.5.0

package/dist/run/resolve.d.ts

@@ -9,10 +9,30 @@ import type { RouteBundle, RunOptions } from "../types/route";
 import type { CandidateRef, CapabilityFlag, ProviderId } from "../types/provider";
 /** Static capability stub — replaced by the probed registry in Phase 2. */
 export type CapabilityLookup = (provider: ProviderId, model: string) => ReadonlySet<CapabilityFlag>;
+/**
+ * Resolution mode (routing-console spec §4.4, R3). `live` is every production
+ * path (`rig.run`, `runStream`, `runBundle`, the hosted gateway slug lane) and
+ * DROPS `trial` candidates before minting — a declared trial candidate is never
+ * served live. `trial` is the bake-off replay path ONLY (`replayVariant`), which
+ * keeps trial candidates so a customer can measure a new model on captured
+ * traffic before promoting it. Default `live` — every existing caller is
+ * byte-for-byte unchanged (no trial candidates ⇒ the filter is a no-op anyway).
+ */
+export type RunMode = "live" | "trial";
 export interface CandidateIterator {
     /** Next eligible candidate, or null when the set is exhausted. */
     next(): CandidateRef | null;
+    /** Position in the EFFECTIVE eligible list of the candidate the most recent
+     * `next()` returned (0 = first eligible; ladder key, spec §2.1). `-1` before
+     * the first `next()`; unchanged by a `next()` that returns null. */
+    readonly index: number;
 }
+/** The live-resolver capability filter. Exported so the declare-first challenger
+ * eligibility (`registry/select.ts` `requirementPredicates` +
+ * `evaluateChallengerEligibility`) can pin itself in agreement with what would
+ * actually serve — an eligibility that drifted from the live filter would offer
+ * a challenger the route could never dispatch. */
+export declare function satisfiesRequirements(route: RouteBundle, flags: ReadonlySet<CapabilityFlag>, searchAvailable: boolean): boolean;
 /**
  * Request-time candidate filters (G-2) — optional, applied by resolveCandidates
  * BEFORE the prefer:[cost] sort. Distinct from route.require (capability + ZDR):
@@ -56,7 +76,7 @@ export interface WarmthShadowLog {
     }[];
     readonly diverged: boolean;
 }
-export declare function resolveCandidates(route: RouteBundle, capabilities: CapabilityLookup, costUsdPerMTok: (provider: ProviderId, model: string) => number | null, searchAvailable?: boolean, filter?: CandidateFilter, shadowWarmth?: WarmthShadowOptions): CandidateIterator;
+export declare function resolveCandidates(route: RouteBundle, capabilities: CapabilityLookup, costUsdPerMTok: (provider: ProviderId, model: string) => number | null, searchAvailable?: boolean, filter?: CandidateFilter, shadowWarmth?: WarmthShadowOptions, mode?: RunMode): CandidateIterator;
 /**
  * Per-run requirement opt-ins (G-3). A caller can demand zero-retention routing
  * for a single run without editing the route bundle: `zero_retention` is unioned

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

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/run/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAElF,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,CAC7B,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,MAAM,KACV,WAAW,CAAC,cAAc,CAAC,CAAC;AAEjC,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,IAAI,YAAY,GAAG,IAAI,CAAC;CAC7B;AA6CD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;oFAEgF;IAChF,QAAQ,CAAC,uBAAuB,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACzF,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;CACjD;AAED;kFACkF;AAClF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtF,QAAQ,CAAC,WAAW,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,gBAAgB,EAC9B,cAAc,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,EACtE,eAAe,UAAQ,EACvB,MAAM,CAAC,EAAE,eAAe,EACxB,YAAY,CAAC,EAAE,mBAAmB,GACjC,iBAAiB,CAkFnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,GAAG,WAAW,CAM5F;AAED;mFACmF;AACnF,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,UAAU,GAAG,eAAe,GAAG,SAAS,CAUxF;AAED;;gDAEgD;AAChD,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAElF;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9D,YAAY,GAAG,IAAI,CAMrB"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/run/resolve.ts"],"names":[],"mappings":"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"}

package/dist/run/resolve.js

@@ -7,12 +7,18 @@
  * retryable failure the run loop asks for the next candidate.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.satisfiesRequirements = satisfiesRequirements;
 exports.resolveCandidates = resolveCandidates;
 exports.applyRunRequirements = applyRunRequirements;
 exports.candidateFilterFromOptions = candidateFilterFromOptions;
 exports.filterSummary = filterSummary;
 exports.mintRawCandidate = mintRawCandidate;
 exports.resolveDeclaredCandidate = resolveDeclaredCandidate;
+/** The live-resolver capability filter. Exported so the declare-first challenger
+ * eligibility (`registry/select.ts` `requirementPredicates` +
+ * `evaluateChallengerEligibility`) can pin itself in agreement with what would
+ * actually serve — an eligibility that drifted from the live filter would offer
+ * a challenger the route could never dispatch. */
 function satisfiesRequirements(route, flags, searchAvailable) {
     for (const requirement of route.require) {
         switch (requirement) {
@@ -56,11 +62,21 @@ function satisfiesRequirements(route, flags, searchAvailable) {
     }
     return true;
 }
-function resolveCandidates(route, capabilities, costUsdPerMTok, searchAvailable = false, filter, shadowWarmth) {
-    // Filter order (spec §4.1): provider only → provider ignore → capability+ZDR
-    // → maxPrice → prefer:[cost]. When `filter` is absent every step is a no-op,
-    // so the path is byte-for-byte the pre-G-2 behavior (back-compat).
+function resolveCandidates(route, capabilities, costUsdPerMTok, searchAvailable = false, filter, shadowWarmth, mode = "live") {
+    // Filter order (spec §4.1): trial-drop → provider only → provider ignore →
+    // capability+ZDR → maxPrice → prefer:[cost]. When `filter` is absent every
+    // step is a no-op, so the path is byte-for-byte the pre-G-2 behavior
+    // (back-compat).
     let pool = route.candidates;
+    // Declare-first (spec §4.4): a `trial` candidate is declared but NEVER served
+    // live — drop it first, exactly as a `providers.ignore` entry is dropped, on
+    // every live path. Only bake-off replay (`mode: "trial"`) keeps it. The
+    // candidate-set invariant is untouched: `route.candidates` (the declared set
+    // the run loop's runtime guard checks against) still includes trial entries;
+    // they are simply never minted into a CandidateRef on a live path.
+    if (mode === "live") {
+        pool = pool.filter((c) => c.trial !== true);
+    }
     if (filter?.only && filter.only.length > 0) {
         const only = new Set(filter.only);
         pool = pool.filter((c) => only.has(c.provider));
@@ -124,10 +140,17 @@ function resolveCandidates(route, capabilities, costUsdPerMTok, searchAvailable
     // minted. The cast below is the single sanctioned exception to the
     // "no `as CandidateRef`" grep (scoped to run/resolve.ts in CI).
     const refs = ordered.map((c) => Object.freeze({ provider: c.provider, model: c.model }));
-    let index = 0;
+    let cursor = 0;
+    let lastIndex = -1;
     return {
         next() {
-            return index < refs.length ? refs[index++] : null;
+            if (cursor >= refs.length)
+                return null;
+            lastIndex = cursor;
+            return refs[cursor++];
+        },
+        get index() {
+            return lastIndex;
         },
     };
 }

package/dist/run/routing-docs.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Routing & reliability — the code-anchored boundary and the failure-class
+ * section of https://modelrig.dev/routing-reliability.html.
+ *
+ * ONE table feeds the published page AND the tripwire test, the same way
+ * `RAW_KNOB_SUPPORT` (raw-support.ts) feeds the raw-lane matrix and its runtime
+ * guard. The docs builder (scripts/build-docs-site.ts) injects
+ * `renderRoutingBoundary()` at `<!-- ROUTING_BOUNDARY -->` and
+ * `renderFailureClasses()` at `<!-- FAILURE_CLASSES -->`, and inlines the
+ * boundary into llms.txt. Nothing here is exported from the package root.
+ *
+ * Spec: docs/ModelRig/routing-reliability-overview/spec.md §5–§6.
+ */
+import type { FailureClass } from "../types/failures";
+export type BoundaryStatus = "not_built" | "deferred" | "shadow" | "by_design";
+export interface BoundaryTripwire {
+    /** Path relative to packages/modelrig (the test reads it as text). */
+    readonly file: string;
+    /** Entry is STALE if this matches — the feature appeared. */
+    readonly mustNotMatch?: RegExp;
+    /** Entry is STALE if this stops matching — the no-op marker vanished. */
+    readonly mustMatch?: RegExp;
+}
+export interface BoundaryEntry {
+    /** Stable id (B1…) — becomes the first table column and a citable handle. */
+    readonly id: string;
+    readonly status: BoundaryStatus;
+    /** <= 8 words. */
+    readonly capability: string;
+    /** ONE sentence, present tense: what is true today. */
+    readonly statement: string;
+    /** Repo doc path (or issue) a reader can cite. */
+    readonly tracking: string;
+    readonly tripwire?: BoundaryTripwire | {
+        readonly noImportersOf: string;
+    };
+}
+/** Rendered group headings, in order. */
+export declare const BOUNDARY_STATUS_LABEL: Readonly<Record<BoundaryStatus, string>>;
+/**
+ * The ten boundary entries, transcribed verbatim from spec §5.3. Statuses,
+ * statements, and tripwires are BINDING content — do not add, drop, or reword
+ * an entry without an architect addendum to the spec. Shipping a capability
+ * listed here breaks `routing-docs.test.ts` until the entry is flipped or
+ * removed and the page updated.
+ */
+export declare const ROUTING_BOUNDARY: readonly BoundaryEntry[];
+/**
+ * Markdown (renderer subset only): one `###` per non-empty status group, a pipe
+ * table per group with columns id | capability | what is true today | tracking.
+ * No nested lists, no HTML — the docs-site renderer supports neither.
+ *
+ * `published` (the site's page slugs) is passed by the docs builder so a tracking
+ * cell naming a published page renders as a link; a bare call (the shape/tripwire
+ * tests, which assert the plain table) leaves every cell as plain text.
+ */
+export declare function renderRoutingBoundary(published?: ReadonlySet<string>): string;
+/** The failure classes in taxonomy order (types/failures.ts `FailureClass`
+ * union). FAILURE_TEACHING is keyed in that same order and its completeness is
+ * pinned by failures-teaching.test.ts, so its key order is the canonical walk.
+ * A test in routing-docs.test.ts asserts this equals the union order in
+ * failures.ts, so a taxonomy reorder cannot drift silently. */
+export declare function failureClassOrder(): readonly FailureClass[];
+/**
+ * Markdown: `### <class>` per FailureClass in taxonomy order, then the teaching
+ * `what`, the retry line, the backoff schedule (when any), and the `fixHint`.
+ * Heading text is the bare class name so the docs-site id equals the class
+ * (failures-teaching.ts docsUrl anchors depend on it — spec §6).
+ */
+export declare function renderFailureClasses(): string;
+/** Exposed for the anchor-completeness test: the heading id each class gets. */
+export declare function failureClassAnchor(cls: FailureClass): string;
+//# sourceMappingURL=routing-docs.d.ts.map

package/dist/run/routing-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-docs.d.ts","sourceRoot":"","sources":["../../src/run/routing-docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE/E,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,kBAAkB;IAClB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,GAAG;QAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3E;AAED,yCAAyC;AACzC,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAK1E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EA0FpD,CAAC;AAwBF;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,CAoB7E;AAED;;;;+DAI+D;AAC/D,wBAAgB,iBAAiB,IAAI,SAAS,YAAY,EAAE,CAE3D;AA0BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAW7C;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAE5D"}

package/dist/run/routing-docs.js

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * Routing & reliability — the code-anchored boundary and the failure-class
+ * section of https://modelrig.dev/routing-reliability.html.
+ *
+ * ONE table feeds the published page AND the tripwire test, the same way
+ * `RAW_KNOB_SUPPORT` (raw-support.ts) feeds the raw-lane matrix and its runtime
+ * guard. The docs builder (scripts/build-docs-site.ts) injects
+ * `renderRoutingBoundary()` at `<!-- ROUTING_BOUNDARY -->` and
+ * `renderFailureClasses()` at `<!-- FAILURE_CLASSES -->`, and inlines the
+ * boundary into llms.txt. Nothing here is exported from the package root.
+ *
+ * Spec: docs/ModelRig/routing-reliability-overview/spec.md §5–§6.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROUTING_BOUNDARY = exports.BOUNDARY_STATUS_LABEL = void 0;
+exports.renderRoutingBoundary = renderRoutingBoundary;
+exports.failureClassOrder = failureClassOrder;
+exports.renderFailureClasses = renderFailureClasses;
+exports.failureClassAnchor = failureClassAnchor;
+const failures_1 = require("../types/failures");
+const failures_teaching_1 = require("../types/failures-teaching");
+/** Rendered group headings, in order. */
+exports.BOUNDARY_STATUS_LABEL = {
+    not_built: "Not built",
+    deferred: "Deferred",
+    shadow: "Built, not actuating",
+    by_design: "By design — will not do",
+};
+/**
+ * The ten boundary entries, transcribed verbatim from spec §5.3. Statuses,
+ * statements, and tripwires are BINDING content — do not add, drop, or reword
+ * an entry without an architect addendum to the spec. Shipping a capability
+ * listed here breaks `routing-docs.test.ts` until the entry is flipped or
+ * removed and the page updated.
+ */
+exports.ROUTING_BOUNDARY = [
+    {
+        id: "B1",
+        status: "not_built",
+        capability: "Quality / value-accuracy gate in the ladder",
+        statement: "Fall-through is triggered by structure and infrastructure only; no builder-defined predicate or judge can reject a schema-valid output at run time — value accuracy exists offline, in bake-offs.",
+        tracking: "customer request on file (2026-08-21); not scheduled",
+        tripwire: { file: "src/types/route.ts", mustNotMatch: /qualityGate|"judged"/ },
+    },
+    {
+        id: "B2",
+        status: "not_built",
+        capability: "Structure on the raw lane",
+        statement: '`runRaw` never validates or repairs; `responseFormat: "json_object"` shapes MIME, not schema, so `meta.validated` stays false — structure on the raw lane is ruled out by design, and the path is to graduate that step to a route.',
+        tracking: "ruled schema-free on the raw lane; re-request on file",
+        tripwire: { file: "src/run/raw.ts", mustNotMatch: /readonly outputSchema\??:/ },
+    },
+    {
+        id: "B3",
+        status: "deferred",
+        capability: "`prefer: latency` / observed-health ordering",
+        statement: "`latency` is accepted and does nothing — declared order stands; observed p50/p90/p99 are aggregated but unused by routing.",
+        tracking: "deferred to the observed-health work (latency signal first)",
+        tripwire: { file: "src/run/resolve.ts", mustMatch: /declared order stands/ },
+    },
+    {
+        id: "B4",
+        status: "shadow",
+        capability: "Cache-aware (warmth) candidate ordering",
+        statement: "The cache-adjusted ranking is computed and logged beside the chosen order but never changes it.",
+        tracking: "cache-aware routing — shadow mode; see caching-lifecycle.md",
+        tripwire: { file: "src/run/resolve.ts", mustMatch: /returns the UNCHANGED list-cost order/ },
+    },
+    {
+        id: "B5",
+        status: "shadow",
+        capability: "Cache-miss streak alert",
+        statement: "A miss-streak detector exists; nothing consumes it yet, so no alert fires.",
+        tracking: "cache-aware routing — monitor wiring pending",
+        tripwire: { noImportersOf: "telemetry/cache-miss-streak" },
+    },
+    {
+        id: "B6",
+        status: "not_built",
+        capability: "Run-level idempotency / dedupe key",
+        statement: "Two identical `rig.run` calls dispatch twice; the only idempotency is the exporter's watermark.",
+        // Spec §5.3 tracking reads "— (record here)": B6 has no external tracking
+        // doc; this generated boundary IS its record, so the rendered cell is "—".
+        tracking: "—",
+        tripwire: { file: "src/types/route.ts", mustNotMatch: /idempotencyKey/ },
+    },
+    {
+        id: "B7",
+        status: "by_design",
+        capability: "Automatic model swap",
+        statement: "Nothing changes what serves a route without a bake-off and an explicit human approval (`modelrig swap execute <id> --approve`).",
+        tracking: "optimization-loop.md — human-approved swaps only",
+        // No file tripwire: the P6 never-silent-swap invariant is covered by its
+        // own dev-rule tests (spec §5.3).
+    },
+    {
+        id: "B8",
+        status: "by_design",
+        capability: "Provider cache resource lifecycle",
+        statement: "ModelRig passes your cache handle through and prices the hits; it never creates, refreshes, or deletes the resource — your heartbeat does.",
+        tracking: "caching-lifecycle.md — who owns what",
+    },
+    {
+        id: "B9",
+        status: "by_design",
+        capability: "Tool execution",
+        statement: "ModelRig normalizes the tool-call protocol and returns `meta.toolCalls`; the caller runs the tool.",
+        tracking: "route-bundles.md — tools are normalized, never executed",
+    },
+    {
+        id: "B10",
+        status: "by_design",
+        capability: "Raw-lane flex → standard degrade",
+        statement: "A flex capacity rejection on `runRaw` surfaces as `capacity_shed` for your own retry ladder; ModelRig does not degrade the tier for you.",
+        tracking: "route-bundles.md — raw-lane serviceTier (customer-side degrade)",
+    },
+];
+const STATUS_ORDER = ["not_built", "deferred", "shadow", "by_design"];
+/** Escape a table cell so a literal `|` in content cannot break the pipe table.
+ * (None of the current statements contain one; this keeps a future edit safe.) */
+function cell(text) {
+    return text.replace(/\|/g, "\\|");
+}
+/**
+ * Turn a `<slug>.md` token in a tracking cell into a markdown link to that
+ * published page (S8) — but ONLY when the slug is one the site actually
+ * publishes, so a stray `.md` reference never becomes a dead link. The URL is
+ * absolute (`modelrig.dev/<slug>.html`) so the same rendered text works on the
+ * page (the docs renderer leaves an already-`.html` href alone) AND inline in
+ * llms.txt, which is plain text and never runs the `.md`→`.html` rewrite.
+ */
+function linkifyTracking(text, published) {
+    return text.replace(/\b([a-z0-9][a-z0-9-]*)\.md\b/gi, (whole, slug) => published.has(slug) ? `[${slug}](https://modelrig.dev/${slug}.html)` : whole);
+}
+/**
+ * Markdown (renderer subset only): one `###` per non-empty status group, a pipe
+ * table per group with columns id | capability | what is true today | tracking.
+ * No nested lists, no HTML — the docs-site renderer supports neither.
+ *
+ * `published` (the site's page slugs) is passed by the docs builder so a tracking
+ * cell naming a published page renders as a link; a bare call (the shape/tripwire
+ * tests, which assert the plain table) leaves every cell as plain text.
+ */
+function renderRoutingBoundary(published) {
+    const blocks = [];
+    for (const status of STATUS_ORDER) {
+        const entries = exports.ROUTING_BOUNDARY.filter((e) => e.status === status);
+        if (entries.length === 0)
+            continue;
+        const rows = entries.map((e) => {
+            const tracking = published ? linkifyTracking(e.tracking, published) : e.tracking;
+            return `| ${e.id} | ${cell(e.capability)} | ${cell(e.statement)} | ${cell(tracking)} |`;
+        });
+        blocks.push([
+            `### ${exports.BOUNDARY_STATUS_LABEL[status]}`,
+            "",
+            "| id | capability | what is true today | tracking |",
+            "|---|---|---|---|",
+            ...rows,
+        ].join("\n"));
+    }
+    return blocks.join("\n\n");
+}
+/** The failure classes in taxonomy order (types/failures.ts `FailureClass`
+ * union). FAILURE_TEACHING is keyed in that same order and its completeness is
+ * pinned by failures-teaching.test.ts, so its key order is the canonical walk.
+ * A test in routing-docs.test.ts asserts this equals the union order in
+ * failures.ts, so a taxonomy reorder cannot drift silently. */
+function failureClassOrder() {
+    return Object.keys(failures_teaching_1.FAILURE_TEACHING);
+}
+/**
+ * Backoff schedule per class, in reader-facing words. The numbers mirror the
+ * (non-exported) constants in run/retry.ts — `CAPACITY_BACKOFF_MS` and the
+ * `NETWORK_BACKOFF_*` pair — and a test in routing-docs.test.ts reads retry.ts
+ * to pin them, so this string cannot drift from the engine (spec §6).
+ */
+function backoffLine(cls) {
+    if (cls === "capacity_shed")
+        return "Backoff between retries: 30 s -> 60 s -> 120 s -> 240 s.";
+    if (cls === "network")
+        return "Backoff between retries: 1 s, doubling each time, capped at 30 s.";
+    // A class that is never retried — terminal, or `config_auth` (straight to the
+    // next candidate) — has no backoff to describe. Every OTHER class is retryable
+    // with a zero delay, so say so: §2 promises "with backoff", and leaving the
+    // remaining classes silent read as "unspecified" rather than "none" (S7).
+    if (failures_1.TERMINAL_CLASSES.has(cls) || cls === "config_auth")
+        return null;
+    return "No backoff between retries (immediate retry).";
+}
+/** The retry disposition sentence for one class (spec §6). */
+function retryLine(cls) {
+    if (failures_1.TERMINAL_CLASSES.has(cls))
+        return "Terminal — never retried; aborts the run.";
+    if (cls === "config_auth")
+        return "Never retried — the run loop advances to the next candidate.";
+    return "Retryable — default budget 0 (declare every budget you want under `policy.retries`).";
+}
+/**
+ * Markdown: `### <class>` per FailureClass in taxonomy order, then the teaching
+ * `what`, the retry line, the backoff schedule (when any), and the `fixHint`.
+ * Heading text is the bare class name so the docs-site id equals the class
+ * (failures-teaching.ts docsUrl anchors depend on it — spec §6).
+ */
+function renderFailureClasses() {
+    const blocks = [];
+    for (const cls of failureClassOrder()) {
+        const teaching = failures_teaching_1.FAILURE_TEACHING[cls];
+        const parts = [`### ${cls}`, "", teaching.what, "", retryLine(cls)];
+        const backoff = backoffLine(cls);
+        if (backoff !== null)
+            parts.push("", backoff);
+        parts.push("", `Fix: ${teaching.fixHint}`);
+        blocks.push(parts.join("\n"));
+    }
+    return blocks.join("\n\n");
+}
+/** Exposed for the anchor-completeness test: the heading id each class gets. */
+function failureClassAnchor(cls) {
+    return cls;
+}

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;AASpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,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;AAsED,wBAAsB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAoiBhG"}
+{"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"}