modelrig 0.0.1 → 0.1.0

package/dist/run/resolve.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Candidate resolution — plan §4. THE ONLY constructor of CandidateRef in the
+ * codebase (the candidate-set invariant is enforced here structurally).
+ * Phase 1 selection: first candidate whose static capability flags satisfy
+ * route.require, ordered by prefer:[cost] via the pricing snapshot; on a
+ * retryable failure the run loop asks for the next candidate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCandidates = resolveCandidates;
+exports.resolveDeclaredCandidate = resolveDeclaredCandidate;
+function satisfiesRequirements(route, flags, searchAvailable) {
+    for (const requirement of route.require) {
+        switch (requirement) {
+            case "schema_conformant":
+                // The native rung demands native strict enforcement; the json_mode
+                // rung accepts either mechanism (a native-capable model still serves
+                // a json_mode route).
+                if (route.policy.json === "native") {
+                    if (!flags.has("structured_native"))
+                        return false;
+                }
+                else if (!flags.has("structured_native") && !flags.has("json_mode")) {
+                    return false;
+                }
+                break;
+            case "grounded":
+                // Phase 3 WS3: a configured search provider satisfies `grounded` for
+                // candidates without native grounding — the run loop orchestrates
+                // search-and-inject for them.
+                if (!flags.has("grounded_native") && !searchAvailable)
+                    return false;
+                break;
+            case "trace_visible":
+                // Phase 3 WS6: reasoning-observability — the model's chain of thought
+                // is exposed to the caller (regulated/audit buyers hard-require this).
+                if (!flags.has("trace_visible"))
+                    return false;
+                break;
+            case "zero_retention":
+                // Phase 1: validated by the loader, not solvable — no capability flag
+                // exists yet (registry work, Phase 2). Declared intent only.
+                break;
+        }
+    }
+    return true;
+}
+function resolveCandidates(route, capabilities, costUsdPerMTok, searchAvailable = false) {
+    const eligible = route.candidates.filter((c) => satisfiesRequirements(route, capabilities(c.provider, c.model), searchAvailable));
+    // prefer: [cost] — ascending, unknown cost sorts last, stable otherwise.
+    // "latency" is advisory in Phase 1 (no probe data): declared order stands.
+    const ordered = [...eligible];
+    if (route.prefer.includes("cost")) {
+        const cost = (c) => {
+            const usd = costUsdPerMTok(c.provider, c.model);
+            return usd === null ? Number.POSITIVE_INFINITY : usd;
+        };
+        ordered.sort((a, b) => cost(a) - cost(b));
+    }
+    // THE brand site — the only place in the codebase a CandidateRef may be
+    // 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;
+    return {
+        next() {
+            return index < refs.length ? refs[index++] : null;
+        },
+    };
+}
+/**
+ * Mint a CandidateRef for a SPECIFIC declared candidate (the repair rung's
+ * designated repair model — loader-validated to be in the route's candidate
+ * list; re-checked here). Same brand site, same sanctioned-cast scope.
+ */
+function resolveDeclaredCandidate(route, spec) {
+    const declared = route.candidates.some((c) => c.provider === spec.provider && c.model === spec.model);
+    if (!declared)
+        return null;
+    return Object.freeze({ provider: spec.provider, model: spec.model });
+}

package/dist/run/retry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Per-class retry accounting — spec §2, plan §4. Budgets are NON-FUNGIBLE:
+ * exhausting one class never consumes another. Terminal classes
+ * (budget_exhausted, invariant_violation) are never retried.
+ */
+import type { FailureClass } from "../types/failures";
+import type { RoutePolicy } from "../types/route";
+export interface RetryLedger {
+    /** True if a retry is permitted for this class (and consumes one unit). */
+    consume(cls: FailureClass): boolean;
+    remaining(cls: FailureClass): number;
+    snapshot(): Partial<Record<FailureClass, number>>;
+    /** Backoff before the retry the most recent consume() granted — per-class:
+     * exponential for capacity_shed (30s base, mirrors the production flex
+     * backoff ladder) and network (1s base); immediate for content classes. */
+    delayMs(cls: FailureClass): number;
+}
+export declare function createRetryLedger(policy: RoutePolicy): RetryLedger;
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/run/retry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC;IACpC,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAAC;IACrC,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD;;+EAE2E;IAC3E,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAAC;CACpC;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAsClE"}

package/dist/run/retry.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Per-class retry accounting — spec §2, plan §4. Budgets are NON-FUNGIBLE:
+ * exhausting one class never consumes another. Terminal classes
+ * (budget_exhausted, invariant_violation) are never retried.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRetryLedger = createRetryLedger;
+const failures_1 = require("../types/failures");
+const CAPACITY_BACKOFF_MS = [30000, 60000, 120000, 240000];
+const NETWORK_BACKOFF_BASE_MS = 1000;
+const NETWORK_BACKOFF_CAP_MS = 30000;
+function createRetryLedger(policy) {
+    const used = new Map();
+    function budget(cls) {
+        return policy.retries[cls] ?? 0;
+    }
+    return {
+        consume(cls) {
+            if (failures_1.TERMINAL_CLASSES.has(cls))
+                return false;
+            const attemptsUsed = used.get(cls) ?? 0;
+            if (attemptsUsed >= budget(cls))
+                return false;
+            used.set(cls, attemptsUsed + 1);
+            return true;
+        },
+        remaining(cls) {
+            if (failures_1.TERMINAL_CLASSES.has(cls))
+                return 0;
+            return Math.max(0, budget(cls) - (used.get(cls) ?? 0));
+        },
+        snapshot() {
+            const out = {};
+            for (const [cls, n] of used)
+                out[cls] = n;
+            return out;
+        },
+        delayMs(cls) {
+            const attempt = Math.max(0, (used.get(cls) ?? 1) - 1);
+            if (cls === "capacity_shed") {
+                return CAPACITY_BACKOFF_MS[Math.min(attempt, CAPACITY_BACKOFF_MS.length - 1)];
+            }
+            if (cls === "network") {
+                return Math.min(NETWORK_BACKOFF_BASE_MS * 2 ** attempt, NETWORK_BACKOFF_CAP_MS);
+            }
+            return 0;
+        },
+    };
+}

package/dist/run/run.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The run loop — spec §4, plan §4/step 6. State machine:
+ *   resolve → render → (envelope check) → dispatch → validate
+ *     → retry per failure class | advance candidate | fail typed | succeed
+ *   → record telemetry on every INFERENCE exit path (RouteConfigError exits
+ *     record nothing by design — config errors precede any dispatch; C1
+ *     ruling 2 / finding F3).
+ */
+import type { LoadedRoutes } from "../routes/loader";
+import type { ProviderAdapter } from "../types/provider";
+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 { SearchProvider } from "./grounding";
+export interface RunDeps {
+    readonly routes: LoadedRoutes;
+    readonly adapters: ReadonlyMap<string, ProviderAdapter>;
+    readonly telemetry: TelemetryStore;
+    readonly capabilities: CapabilityLookup;
+    /** Budget for envelopes first opened by this rig (see envelope.ts default). */
+    readonly envelopeBudgetUsd?: number;
+    /** Addendum A1: USD per million tokens charged against an ACTIVE envelope
+     * when a model has no pricing entry — envelopes fail closed, never free.
+     * Deliberately generous-high by default. */
+    readonly unpricedRateUsdPerMTok?: number;
+    /** Rig manifest (declared dimensions) — null/omitted when no rig.yaml. */
+    readonly manifest?: RigManifest | null;
+    /** Local-only capture store (Phase 3 WS4) — writes gated per route by the
+     * bundle's `capture: true`; null/omitted disables capture entirely. */
+    readonly captures?: CaptureStore | null;
+    /** Search provider for the grounding-inject rung (Phase 3 WS3) —
+     * null/omitted means `require: grounded` resolves natively-grounded
+     * candidates only. */
+    readonly search?: SearchProvider | null;
+    /** Injectable backoff sleep — tests pass a no-op. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+export declare function run(deps: RunDeps, routeName: string, opts: RunOptions): Promise<RunResult>;
+//# sourceMappingURL=run.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,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,EAAgB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AASlD,OAAO,KAAK,EAAE,cAAc,EAAoC,MAAM,aAAa,CAAC;AAGpF,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;CAChD;AAwFD,wBAAsB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAwiBhG"}

package/dist/run/validate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Output validation — plan §4. Ajv compiled once per (route, version), cached.
+ * Phase 1 checks schema conformance; value-accuracy gates arrive with the
+ * bake-off in Phase 3.
+ */
+import type { RouteBundle } from "../types/route";
+export interface ValidationOutcome {
+    readonly valid: boolean;
+    /** ajv error summaries, capped, human- and agent-readable. */
+    readonly errors: readonly string[];
+    /** Parsed output when text was JSON-parseable (even if schema-invalid). */
+    readonly parsed: unknown;
+}
+export declare function validateOutput(route: RouteBundle, text: string): ValidationOutcome;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/run/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAsBD,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CA6BlF"}

package/dist/run/validate.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Output validation — plan §4. Ajv compiled once per (route, version), cached.
+ * Phase 1 checks schema conformance; value-accuracy gates arrive with the
+ * bake-off in Phase 3.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOutput = validateOutput;
+const ajv_1 = __importDefault(require("ajv"));
+// Mirrors the production probe harness: new Ajv({ strict: false, allErrors:
+// true }) — the v3 schemas trip ajv strict-mode warnings by design.
+const ajv = new ajv_1.default({ strict: false, allErrors: true, allowUnionTypes: true });
+const MAX_ERRORS = 12;
+/** Compiled validators cached per (route, version) — recompiling a 300-line
+ * schema per attempt is measurable. */
+const validatorCache = new Map();
+function validatorFor(route) {
+    const key = `${route.route}@${route.version}`;
+    let compiled = validatorCache.get(key);
+    if (compiled === undefined) {
+        compiled = ajv.compile(route.outputSchema);
+        validatorCache.set(key, compiled);
+    }
+    return compiled;
+}
+function validateOutput(route, text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            errors: [`output is not valid JSON: ${err.message}`],
+            parsed: undefined,
+        };
+    }
+    if (route.outputSchema === null) {
+        return { valid: true, errors: [], parsed };
+    }
+    const validate = validatorFor(route);
+    if (validate(parsed)) {
+        return { valid: true, errors: [], parsed };
+    }
+    const all = validate.errors ?? [];
+    const errors = all
+        .slice(0, MAX_ERRORS)
+        .map((e) => `${e.instancePath || "/"} ${e.message ?? "invalid"}${e.keyword === "enum" ? ` (${JSON.stringify(e.params)})` : ""}`);
+    if (all.length > MAX_ERRORS) {
+        errors.push(`… ${all.length - MAX_ERRORS} more errors`);
+    }
+    return { valid: false, errors, parsed };
+}

package/dist/savings/emit.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Swap-change emission — Phase 4 WS4 (plan §4/§7). The executor NEVER edits
+ * route files: it renders the exact YAML the human applies via git, plus the
+ * revert block. This file deliberately imports no filesystem API — the
+ * "actions live in your code" invariant is structural, and emit.test.ts
+ * greps for it.
+ */
+import type { CandidateSpec, RouteBundle } from "../types/route";
+export interface SwapChange {
+    readonly route: string;
+    readonly file: string;
+    readonly fromModel: string;
+    readonly toModel: string;
+    readonly newVersion: number;
+    /** Paste-ready YAML fragment applying the swap (complete, no elisions). */
+    readonly yaml: string;
+    /** Paste-ready YAML fragment reverting it (version bumps again — history
+     * moves forward, never rewrites). */
+    readonly revertYaml: string;
+    /** Original candidate order — snapshotted into swap_events.baseline so a
+     * revert can be emitted even without the pre-swap file. */
+    readonly incumbentCandidates: readonly CandidateSpec[];
+}
+export declare function buildSwapChange(bundle: RouteBundle, winningVariant: string): SwapChange;
+//# sourceMappingURL=emit.d.ts.map

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

@@ -0,0 +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;AAiCD,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,UAAU,CA6CvF"}

package/dist/savings/emit.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Swap-change emission — Phase 4 WS4 (plan §4/§7). The executor NEVER edits
+ * route files: it renders the exact YAML the human applies via git, plus the
+ * revert block. This file deliberately imports no filesystem API — the
+ * "actions live in your code" invariant is structural, and emit.test.ts
+ * greps for it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSwapChange = buildSwapChange;
+function candidateLines(candidates) {
+    return candidates.flatMap((c) => [`  - provider: ${c.provider}`, `    model: ${c.model}`]);
+}
+function overrideLines(variant) {
+    const lines = [];
+    if (variant.json !== undefined)
+        lines.push(`json: ${variant.json}`);
+    if (variant.repair !== undefined) {
+        lines.push("repair:");
+        lines.push(`  max_repairs: ${variant.repair.maxRepairs}`);
+        if (variant.repair.repairModel !== undefined) {
+            lines.push(`  repair_model: ${variant.repair.repairModel.provider}/${variant.repair.repairModel.model}`);
+        }
+    }
+    return lines;
+}
+/** Winner-first candidate order: the variant's candidates, then every other
+ * declared candidate in original order. Nothing is deleted — fallbacks and
+ * bake-off challengers keep their standing. */
+function promotedOrder(declared, winners) {
+    const key = (c) => `${c.provider}/${c.model}`;
+    const winnerKeys = new Set(winners.map(key));
+    return [...winners, ...declared.filter((c) => !winnerKeys.has(key(c)))];
+}
+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;
+    if (winners.length === 0) {
+        throw new Error(`variant "${winningVariant}" has no candidates to promote`);
+    }
+    const incumbent = bundle.candidates[0];
+    const promoted = promotedOrder(bundle.candidates, winners);
+    const file = `modelrig/routes/${bundle.route}.yaml`;
+    const newVersion = bundle.version + 1;
+    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`,
+        `version: ${newVersion}`,
+        "candidates:",
+        ...candidateLines(promoted),
+        ...overrideLines(variant),
+        "",
+    ].join("\n");
+    const revertYaml = [
+        `# revert: restore ${bundle.route} to ${incumbent.provider}/${incumbent.model}`,
+        `# apply to ${file} — replace the version and candidates fields; nothing else changes`,
+        `version: ${newVersion + 1}`,
+        "candidates:",
+        ...candidateLines(bundle.candidates),
+        "",
+    ].join("\n");
+    return {
+        route: bundle.route,
+        file,
+        fromModel: `${incumbent.provider}/${incumbent.model}`,
+        toModel: `${winners[0].provider}/${winners[0].model}`,
+        newVersion,
+        yaml,
+        revertYaml,
+        incumbentCandidates: bundle.candidates,
+    };
+}

package/dist/savings/odometer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The savings odometer — Phase 4 WS4. Verified savings per executed swap:
+ *
+ *   (baseline effective $/conformant − actual $/conformant since swap)
+ *     × conformant volume since swap
+ *
+ * Rules (the odometer's credibility IS the brand — plan §10):
+ *  - MEASURED only: computed from telemetry rows that actually flowed.
+ *    Zero volume → $0, never a projection.
+ *  - Honest costs: failed-attempt spend counts against the actual side;
+ *    unpriced rows are excluded entirely (their $0 would inflate savings).
+ *  - Negative results stay negative — a swap that made things worse shows it.
+ *  - Reverted swaps stop accruing at reverted_at.
+ */
+import type { TelemetryRow } from "../types/telemetry";
+import type { SwapEventRecord } from "./swaps-client";
+export interface SwapSavings {
+    readonly swapId: string;
+    readonly route: string;
+    readonly toVariant: string;
+    readonly executedAt: string;
+    readonly conformantVolume: number;
+    readonly actualUsdPerConformant: number | null;
+    readonly baselineUsdPerConformant: number;
+    readonly verifiedUsd: number;
+}
+export interface Odometer {
+    readonly totalVerifiedUsd: number;
+    readonly perSwap: readonly SwapSavings[];
+}
+export declare function computeOdometer(swaps: readonly SwapEventRecord[], rows: readonly TelemetryRow[]): Odometer;
+//# sourceMappingURL=odometer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"odometer.d.ts","sourceRoot":"","sources":["../../src/savings/odometer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,IAAI,EAAE,SAAS,YAAY,EAAE,GAC5B,QAAQ,CAoDV"}

package/dist/savings/odometer.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * The savings odometer — Phase 4 WS4. Verified savings per executed swap:
+ *
+ *   (baseline effective $/conformant − actual $/conformant since swap)
+ *     × conformant volume since swap
+ *
+ * Rules (the odometer's credibility IS the brand — plan §10):
+ *  - MEASURED only: computed from telemetry rows that actually flowed.
+ *    Zero volume → $0, never a projection.
+ *  - Honest costs: failed-attempt spend counts against the actual side;
+ *    unpriced rows are excluded entirely (their $0 would inflate savings).
+ *  - Negative results stay negative — a swap that made things worse shows it.
+ *  - Reverted swaps stop accruing at reverted_at.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeOdometer = computeOdometer;
+function computeOdometer(swaps, rows) {
+    const perSwap = swaps.map((swap) => {
+        const from = Date.parse(swap.executedAt);
+        const until = swap.revertedAt !== null ? Date.parse(swap.revertedAt) : Number.POSITIVE_INFINITY;
+        const window = rows.filter((r) => {
+            if (r.route !== swap.route || r.pricingMissing)
+                return false;
+            // Replay/shadow traffic is not production serving — never let a
+            // bake-off run on the swapped route inflate measured savings.
+            try {
+                if (JSON.parse(r.tagsJson).replay !== undefined)
+                    return false;
+            }
+            catch {
+                // Unparseable tags: treat as production (the conservative default
+                // here is to keep the row; a malformed tag never hides real spend).
+            }
+            const t = Date.parse(r.ts);
+            return t >= from && t < until;
+        });
+        const conformant = window.filter((r) => r.failureClass === null).length;
+        const spentUsd = window.reduce((a, r) => a + r.costEstimateUsd, 0);
+        const baselinePerConformant = swap.baseline.effective_usd_per_1k_conformant / 1000;
+        if (conformant === 0) {
+            // No conformant volume → nothing verified. $0, not a projection.
+            return {
+                swapId: swap.id,
+                route: swap.route,
+                toVariant: swap.toVariant,
+                executedAt: swap.executedAt,
+                conformantVolume: 0,
+                actualUsdPerConformant: null,
+                baselineUsdPerConformant: baselinePerConformant,
+                verifiedUsd: 0,
+            };
+        }
+        const actualPerConformant = spentUsd / conformant;
+        return {
+            swapId: swap.id,
+            route: swap.route,
+            toVariant: swap.toVariant,
+            executedAt: swap.executedAt,
+            conformantVolume: conformant,
+            actualUsdPerConformant: actualPerConformant,
+            baselineUsdPerConformant: baselinePerConformant,
+            verifiedUsd: (baselinePerConformant - actualPerConformant) * conformant,
+        };
+    });
+    return {
+        totalVerifiedUsd: perSwap.reduce((a, s) => a + s.verifiedUsd, 0),
+        perSwap,
+    };
+}

package/dist/savings/swap-execute.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Swap execution orchestration — Phase 4 WS4, extracted from the CLI so the
+ * safety-critical path (the one that must NEVER auto-execute and must record
+ * exactly once) is hermetically testable with injected clients. The CLI is
+ * thin wiring over this; time, ids, and the approver are injected.
+ *
+ * Invariants enforced here (each has a test):
+ *  - `approve` MUST be true — no --approve, no execution, no side effects.
+ *  - Only an evidenced/approved proposal with a WINNING variant executes.
+ *  - The incumbent baseline is snapshotted into swap_events (odometer seed),
+ *    and it MUST be an explicit `default` evidence row — never a fallback.
+ *  - Control-plane writes happen BEFORE the YAML is emitted (a process death
+ *    after apply must not leave an unrecorded swap): approved → record →
+ *    executed. Applying the YAML stays a human/git action.
+ */
+import type { SwapChange } from "./emit";
+import type { SwapEventRecord } from "./swaps-client";
+import type { ProposalRecord, ProposalStatus } from "../watch/proposals";
+import type { RouteBundle } from "../types/route";
+export interface SwapExecuteDeps {
+    readonly proposalId: string;
+    /** THE gate — false throws before any read or write. */
+    readonly approve: boolean;
+    readonly approvedBy: string;
+    readonly proposals: {
+        get(id: string): Promise<ProposalRecord | null>;
+        setStatus(id: string, from: ProposalStatus, to: ProposalStatus): Promise<void>;
+    };
+    readonly swaps: {
+        record(event: SwapEventRecord): Promise<void>;
+    };
+    readonly loadBundle: (route: string) => RouteBundle;
+    readonly newId: () => string;
+    readonly now: () => string;
+}
+export interface SwapExecuteResult {
+    readonly swapId: string;
+    readonly route: string;
+    readonly change: SwapChange;
+    readonly approvedBy: string;
+    readonly executedAt: string;
+}
+export declare function executeSwap(deps: SwapExecuteDeps): Promise<SwapExecuteResult>;
+//# sourceMappingURL=swap-execute.d.ts.map

package/dist/savings/swap-execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swap-execute.d.ts","sourceRoot":"","sources":["../../src/savings/swap-execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAgB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AASlD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE;QAClB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;QAChD,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAChF,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE;QAAE,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAClE,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,WAAW,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuFnF"}

package/dist/savings/swap-execute.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Swap execution orchestration — Phase 4 WS4, extracted from the CLI so the
+ * safety-critical path (the one that must NEVER auto-execute and must record
+ * exactly once) is hermetically testable with injected clients. The CLI is
+ * thin wiring over this; time, ids, and the approver are injected.
+ *
+ * Invariants enforced here (each has a test):
+ *  - `approve` MUST be true — no --approve, no execution, no side effects.
+ *  - Only an evidenced/approved proposal with a WINNING variant executes.
+ *  - The incumbent baseline is snapshotted into swap_events (odometer seed),
+ *    and it MUST be an explicit `default` evidence row — never a fallback.
+ *  - Control-plane writes happen BEFORE the YAML is emitted (a process death
+ *    after apply must not leave an unrecorded swap): approved → record →
+ *    executed. Applying the YAML stays a human/git action.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeSwap = executeSwap;
+const emit_1 = require("./emit");
+async function executeSwap(deps) {
+    // The gate first — before any client call, so a non-approved invocation
+    // has zero side effects (defense in depth with the CLI's fast-fail check).
+    if (!deps.approve) {
+        throw new Error("swap execution requires explicit --approve — proposals never auto-execute. " +
+            `Re-run: modelrig swap execute ${deps.proposalId} --approve`);
+    }
+    const proposal = await deps.proposals.get(deps.proposalId);
+    if (proposal === null)
+        throw new Error(`no proposal "${deps.proposalId}" on the control plane`);
+    if (proposal.status !== "evidenced" && proposal.status !== "approved") {
+        throw new Error(`proposal ${deps.proposalId} is ${proposal.status} — only evidenced proposals can be approved ` +
+            "(run `modelrig bakeoff --from-proposal` first; approval without evidence is not a thing)");
+    }
+    const winner = proposal.evidence?.proposal;
+    if (winner === null || winner === undefined) {
+        throw new Error(`proposal ${deps.proposalId} has no winning variant in its evidence — the incumbent stood; ` +
+            "nothing to execute");
+    }
+    // The odometer baseline MUST come from the incumbent — the `default` variant
+    // — and nothing else. There is no "close enough" row: seeding from a
+    // challenger would report savings against another challenger and quietly
+    // inflate every number the odometer ever shows. If in doubt, refuse.
+    const matrix = proposal.evidence?.matrix;
+    const incumbentRow = matrix?.find((m) => m.variant === "default");
+    if (incumbentRow === undefined) {
+        const seen = (matrix ?? []).map((m) => m.variant).join(", ") || "none";
+        throw new Error(`proposal ${deps.proposalId} evidence has no incumbent (variant "default") row — ` +
+            `cannot seed the odometer from a challenger. Variants present: ${seen}. ` +
+            "Re-run the bake-off so the incumbent is measured alongside the challengers " +
+            `(modelrig bakeoff --from-proposal ${deps.proposalId}).`);
+    }
+    if (incumbentRow.effective_usd_per_1k_conformant === null) {
+        throw new Error(`proposal ${deps.proposalId} evidence has no usable incumbent baseline — cannot seed the odometer`);
+    }
+    const bundle = deps.loadBundle(proposal.route);
+    const change = (0, emit_1.buildSwapChange)(bundle, winner.variant);
+    const baseline = {
+        effective_usd_per_1k_conformant: incumbentRow.effective_usd_per_1k_conformant,
+        conform_rate: incumbentRow.conform_rate,
+        samples: incumbentRow.samples,
+        bakeoff_id: String(proposal.evidence?.bakeoff_id ?? ""),
+        incumbent_candidates: change.incumbentCandidates.map((c) => ({
+            provider: c.provider,
+            model: c.model,
+        })),
+    };
+    const swapId = deps.newId();
+    const executedAt = deps.now();
+    // Record on the control plane FIRST — the emitted YAML is worthless as
+    // history if the process dies after the operator applies it.
+    if (proposal.status === "evidenced") {
+        await deps.proposals.setStatus(proposal.id, "evidenced", "approved");
+    }
+    await deps.swaps.record({
+        id: swapId,
+        proposalId: proposal.id,
+        route: proposal.route,
+        fromVariant: "default",
+        toVariant: winner.variant,
+        baseline,
+        executedAt,
+        approvedBy: deps.approvedBy,
+        revertedAt: null,
+    });
+    await deps.proposals.setStatus(proposal.id, "approved", "executed");
+    return { swapId, route: proposal.route, change, approvedBy: deps.approvedBy, executedAt };
+}