modelrig 0.0.1 → 0.2.0

package/dist/savings/cache-stats.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Cache-hit-rate rollup — cache-aware-routing spec §5.1, WS-B. PURE: a function
+ * over telemetry rows, no store/clock/network (an injected `now` bounds the
+ * window). Feeds the effective-rate blend (§4.2), the derived ledger (§5.2), and
+ * the console (WS-D).
+ *
+ * ── THE ODOMETER RULE (replay exclusion) ──────────────────────────────────
+ * Trailing-window measurements count PRODUCTION serving only: a bake-off replay
+ * pass runs real (billed) calls tagged `replay`, and those must NEVER inflate a
+ * route's measured hit rate any more than they inflate measured savings. This is
+ * the SAME 5-line filter the savings odometer uses — see
+ * `savings/odometer.ts` (`JSON.parse(r.tagsJson).replay !== undefined`). It is
+ * duplicated (not imported) deliberately: the two live in different modules with
+ * different row shapes, and a shared 5-line helper would couple them for no real
+ * gain. If the replay tag convention ever changes, change BOTH.
+ *
+ * ── UNPRICED ROWS ARE KEPT ────────────────────────────────────────────────
+ * Unlike the odometer (which drops `pricingMissing` rows so a $0 cannot inflate
+ * dollar savings), the hit-rate rollup is a TOKEN measurement, not a dollar one:
+ * an unpriced row still carries honest token counts, so it counts toward h/w.
+ * Pricing enters later, in the effective-rate blend, where a missing rate
+ * fail-closes on its own.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CACHE_WINDOW_DAYS = void 0;
+exports.rollupCacheStats = rollupCacheStats;
+/** Trailing window for the rollup — 7 days by default (spec §5.1). */
+exports.DEFAULT_CACHE_WINDOW_DAYS = 7;
+/** The replay-exclusion predicate — see the module header (odometer parity).
+ * A row is production unless its tags carry a `replay` key. Unparseable tags
+ * are treated as production (a malformed tag never hides real traffic). */
+function isProductionRow(row) {
+    try {
+        return JSON.parse(row.tagsJson).replay === undefined;
+    }
+    catch {
+        return true;
+    }
+}
+// Grouping key: none of route / provider / model contains a newline, so a
+// newline separator splits back unambiguously.
+const KEY_SEP = "\n";
+/**
+ * Roll telemetry rows up into per-(route, provider, model) cache stats over the
+ * trailing window. Rows outside `[now − windowDays, now]`, with an unparseable
+ * ts, or tagged `replay` are excluded. Output is sorted (route, provider, model)
+ * for deterministic downstream rendering and stable snapshots.
+ */
+function rollupCacheStats(rows, opts) {
+    const windowDays = opts.windowDays ?? exports.DEFAULT_CACHE_WINDOW_DAYS;
+    const windowStartMs = opts.now - windowDays * 86400000;
+    const byKey = new Map();
+    for (const row of rows) {
+        if (!isProductionRow(row))
+            continue;
+        const t = Date.parse(row.ts);
+        if (Number.isNaN(t) || t < windowStartMs || t > opts.now)
+            continue;
+        const key = `${row.route}${KEY_SEP}${row.provider}${KEY_SEP}${row.model}`;
+        let acc = byKey.get(key);
+        if (acc === undefined) {
+            acc = {
+                sampleN: 0,
+                tokensIn: 0,
+                tokensCached: 0,
+                tokensCacheWrite: 0,
+                lastSeenAtMs: -1,
+                lastSeenAt: null,
+                fingerprints: new Set(),
+            };
+            byKey.set(key, acc);
+        }
+        acc.sampleN += 1;
+        acc.tokensIn += Math.max(row.tokensIn, 0);
+        acc.tokensCached += Math.max(row.tokensCached, 0);
+        acc.tokensCacheWrite += Math.max(row.tokensCacheWrite ?? 0, 0);
+        if (t > acc.lastSeenAtMs) {
+            acc.lastSeenAtMs = t;
+            acc.lastSeenAt = row.ts;
+        }
+        if (row.prefixFingerprint != null && row.prefixFingerprint !== "") {
+            acc.fingerprints.add(row.prefixFingerprint);
+        }
+    }
+    const out = [];
+    for (const [key, acc] of byKey) {
+        const [route, provider, model] = key.split(KEY_SEP);
+        out.push({
+            route,
+            provider,
+            model,
+            sampleN: acc.sampleN,
+            tokensIn: acc.tokensIn,
+            tokensCached: acc.tokensCached,
+            tokensCacheWrite: acc.tokensCacheWrite,
+            h: acc.tokensIn > 0 ? acc.tokensCached / acc.tokensIn : 0,
+            w: acc.tokensIn > 0 ? acc.tokensCacheWrite / acc.tokensIn : 0,
+            lastSeenAt: acc.lastSeenAt,
+            prefixFingerprints: [...acc.fingerprints].sort(),
+        });
+    }
+    return out.sort((a, b) => a.route !== b.route
+        ? a.route.localeCompare(b.route)
+        : a.provider !== b.provider
+            ? a.provider.localeCompare(b.provider)
+            : a.model.localeCompare(b.model));
+}

package/dist/savings/emit.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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[];
+}
+/**
+ * Restore-YAML for a REVERT — managed-loop §1 (`POST /v1/swaps/:id/revert`).
+ *
+ * A revert has no bake-off winner; it restores the swap's snapshotted incumbent
+ * candidates (`swap_events.baseline.incumbent_candidates`) at a version above the
+ * route's current one — history moves forward, never rewrites. Same
+ * no-filesystem, paste-ready shape as `buildSwapChange`; the server emits it and
+ * a human applies it via a PR (never-silent-swap extends to the revert).
+ */
+export declare function buildRestoreYaml(route: string, incumbent: readonly {
+    readonly provider: string;
+    readonly model: string;
+}[], currentVersion: number): string;
+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;AAmCD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,EAC3E,cAAc,EAAE,MAAM,GACrB,MAAM,CAgBR;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,UAAU,CA6CvF"}

package/dist/savings/emit.js

@@ -0,0 +1,100 @@
+"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.buildRestoreYaml = buildRestoreYaml;
+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)))];
+}
+/**
+ * Restore-YAML for a REVERT — managed-loop §1 (`POST /v1/swaps/:id/revert`).
+ *
+ * A revert has no bake-off winner; it restores the swap's snapshotted incumbent
+ * candidates (`swap_events.baseline.incumbent_candidates`) at a version above the
+ * route's current one — history moves forward, never rewrites. Same
+ * no-filesystem, paste-ready shape as `buildSwapChange`; the server emits it and
+ * a human applies it via a PR (never-silent-swap extends to the revert).
+ */
+function buildRestoreYaml(route, incumbent, currentVersion) {
+    if (incumbent.length === 0) {
+        throw new Error(`cannot emit a restore for "${route}" — the swap recorded no incumbent candidates to restore ` +
+            "(an older swap predating the baseline snapshot; revert it by hand from git history)");
+    }
+    const file = `modelrig/routes/${route}.yaml`;
+    return [
+        `# revert: restore ${route} to ${incumbent[0].provider}/${incumbent[0].model}`,
+        `# apply to ${file} — replace the version and candidates fields; nothing else changes`,
+        `version: ${currentVersion + 1}`,
+        "candidates:",
+        ...candidateLines(incumbent),
+        "",
+    ].join("\n");
+}
+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,58 @@
+/**
+ * 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 { CacheContext } from "../watch/evaluate";
+import type { CacheVerdict } from "../registry/effective-rate";
+import type { ProposalRecord, ProposalStatus } from "../watch/proposals";
+import type { RouteBundle } from "../types/route";
+/** Narrow a proposal's `evidence.cache_context` jsonb (spec §5.5 — additive,
+ * present only on cache-aware proposals) to a typed `CacheContext`, or null when
+ * absent/malformed. Defensive: an older or non-cache proposal has no block, and
+ * a partial block must degrade to "no cache explanation", never throw on the
+ * safety-critical execute path. */
+export declare function readCacheContext(evidence: Record<string, unknown> | null): CacheContext | null;
+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;
+    /** Cache-aware verdict from the proposal's `cache_context` evidence (spec
+     * §5.5), or null on a non-cache proposal. Additive — never gates execution
+     * (the human already approved); surfaced so the CLI/console can show WHY. */
+    readonly cacheVerdict: CacheVerdict | null;
+    /** The [Briefing §30] one-line explanation for the approval prompt, or null. */
+    readonly cacheExplanation: string | null;
+}
+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;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;;mCAImC;AACnC,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,YAAY,GAAG,IAAI,CAmB9F;AASD,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;IAC5B;;iFAE6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAwGnF"}

package/dist/savings/swap-execute.js

@@ -0,0 +1,130 @@
+"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.readCacheContext = readCacheContext;
+exports.executeSwap = executeSwap;
+const emit_1 = require("./emit");
+const evaluate_1 = require("../watch/evaluate");
+/** Narrow a proposal's `evidence.cache_context` jsonb (spec §5.5 — additive,
+ * present only on cache-aware proposals) to a typed `CacheContext`, or null when
+ * absent/malformed. Defensive: an older or non-cache proposal has no block, and
+ * a partial block must degrade to "no cache explanation", never throw on the
+ * safety-critical execute path. */
+function readCacheContext(evidence) {
+    const raw = evidence?.cache_context;
+    if (raw === null || typeof raw !== "object")
+        return null;
+    const c = raw;
+    const verdicts = ["cache_positive", "cache_marginal", "cache_negative", "no_cache_signal"];
+    if (typeof c.verdict !== "string" || !verdicts.includes(c.verdict))
+        return null;
+    const num = (v) => (typeof v === "number" ? v : 0);
+    return {
+        observed_hit_rate: num(c.observed_hit_rate),
+        observed_write_rate: num(c.observed_write_rate),
+        window_days: num(c.window_days),
+        incumbent_effective_in_per_mtok: num(c.incumbent_effective_in_per_mtok),
+        challenger_cold_in_per_mtok: num(c.challenger_cold_in_per_mtok),
+        switch_cost_usd: num(c.switch_cost_usd),
+        cache_option_value_usd: num(c.cache_option_value_usd),
+        breakeven_conformant_calls: typeof c.breakeven_conformant_calls === "number" ? c.breakeven_conformant_calls : Number.POSITIVE_INFINITY,
+        verdict: c.verdict,
+    };
+}
+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");
+    // Cache-aware explainability (spec §5.5) — additive, read-only. The verdict +
+    // prose ride along for the approval prompt / audit trail; they NEVER gate the
+    // swap (the human decision above is the only gate). Absent on non-cache
+    // proposals, in which case both are null and behavior is byte-identical.
+    const cacheContext = readCacheContext(proposal.evidence);
+    const incumbentLabel = change.incumbentCandidates.map((c) => `${c.provider}/${c.model}`).join(", ") || "incumbent";
+    const cacheExplanation = cacheContext !== null ? (0, evaluate_1.explainCacheContext)(cacheContext, incumbentLabel, winner.variant) : null;
+    return {
+        swapId,
+        route: proposal.route,
+        change,
+        approvedBy: deps.approvedBy,
+        executedAt,
+        cacheVerdict: cacheContext?.verdict ?? null,
+        cacheExplanation,
+    };
+}

package/dist/savings/swaps-client.d.ts

@@ -0,0 +1,55 @@
+/**
+ * swap_events control-plane client — Phase 4 WS4. One row per approved,
+ * EXECUTED swap; the baseline snapshot is the odometer's fixed comparison
+ * point. Same PostgREST transport as proposals/exporter.
+ */
+export interface SwapBaseline {
+    /** Incumbent's effective $ per 1K conformant from the evidence bake-off. */
+    readonly effective_usd_per_1k_conformant: number;
+    readonly conform_rate: number;
+    readonly samples: number;
+    readonly bakeoff_id: string;
+    /** Pre-swap candidate order — lets a revert be emitted later. */
+    readonly incumbent_candidates?: ReadonlyArray<{
+        provider: string;
+        model: string;
+    }>;
+}
+export interface SwapEventRecord {
+    readonly id: string;
+    readonly proposalId: string | null;
+    readonly route: string;
+    readonly fromVariant: string;
+    readonly toVariant: string;
+    readonly baseline: SwapBaseline;
+    readonly executedAt: string;
+    readonly approvedBy: string;
+    readonly revertedAt: string | null;
+}
+export interface SwapsClientConfig {
+    readonly supabaseUrl: string;
+    readonly serviceRoleKey: string;
+    /**
+     * The tenant this client writes/reads for. When set (the hosted managed-loop
+     * §1 swap surface + odometer): `record` STAMPS `org_id` on the row (else it
+     * falls to the house-org column default — filing a customer's swap under ours)
+     * and `list` scopes to this org (the odometer must never sum another tenant's
+     * swaps). When omitted, behaviour is unchanged for the CLI/self-host lane.
+     * `get`/`orgOf`/`markReverted` are keyed by id and org-agnostic.
+     */
+    readonly orgId?: string;
+    readonly fetchFn?: typeof fetch;
+}
+export interface SwapsClient {
+    record(event: SwapEventRecord): Promise<void>;
+    /** All executed swaps for this client's org (when `orgId` set) or every org
+     * (unscoped) — newest first. The odometer reader's source. */
+    list(): Promise<SwapEventRecord[]>;
+    get(id: string): Promise<SwapEventRecord | null>;
+    /** The org that owns a swap, or null if no such swap — the tenant a revert
+     * must be authorized against (T11), mirroring `proposals.orgOf`. */
+    orgOf(id: string): Promise<string | null>;
+    markReverted(id: string, revertedAt: string): Promise<void>;
+}
+export declare function createSwapsClient(config: SwapsClientConfig): SwapsClient;
+//# sourceMappingURL=swaps-client.d.ts.map

package/dist/savings/swaps-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swaps-client.d.ts","sourceRoot":"","sources":["../../src/savings/swaps-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,+BAA+B,EAAE,MAAM,CAAC;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpF;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AA4BD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C;kEAC8D;IAC9D,IAAI,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IACnC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IACjD;wEACoE;IACpE,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1C,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAiFxE"}