modelrig 0.0.1 → 0.1.0

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG;AAgBH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,iBAAiB,CAAC;AAcvE,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpC;AAaD,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAuBxD;AAMD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CA6B3D;AAqfD,wBAAsB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgCnE"}

package/dist/cli.js

@@ -0,0 +1,572 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * modelrig CLI — Phase 3 plan §3 + Phase 4 plan §3:
+ *   modelrig bakeoff --route X --variants a,b,c --replay-last N
+ *     [--envelope usd] [--json] [--no-mirror]
+ *   modelrig bakeoff --from-proposal <id> [--replay-last N] [--json]
+ *   modelrig watch run [--events fixtures.json] [--json]
+ *
+ * Bake-offs replay locally captured traffic, write the artifact JSON next
+ * to the telemetry db (.modelrig/bakeoffs/<id>.json), upsert the `bakeoffs`
+ * mirror when the Supabase sink is configured, and print the matrix.
+ * Captures never travel — only aggregate metrics. Watch cycles spend $0;
+ * --from-proposal runs draw from the monthly watch envelope and attach
+ * their evidence to the proposal (suggested → evidenced). Nothing here
+ * executes a swap — that is `modelrig swap execute --approve`, a separate,
+ * human command.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.printMatrix = printMatrix;
+exports.main = main;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const run_1 = require("./init/run");
+const failures_1 = require("./types/failures");
+const failures_teaching_1 = require("./types/failures-teaching");
+const rows_1 = require("./registry/rows");
+const config_1 = require("./config");
+const index_1 = require("./index");
+const engine_1 = require("./bakeoff/engine");
+const samples_1 = require("./bakeoff/samples");
+const loader_1 = require("./routes/loader");
+const store_1 = require("./telemetry/store");
+const budget_1 = require("./watch/budget");
+const proposals_1 = require("./watch/proposals");
+const run_reported_1 = require("./watch/run-reported");
+const state_1 = require("./watch/state");
+const state_store_1 = require("./watch/state-store");
+const swaps_client_1 = require("./savings/swaps-client");
+const swap_execute_1 = require("./savings/swap-execute");
+const BARE_FLAGS = new Set([
+    "json",
+    "no-mirror",
+    "approve",
+    "keep-outputs",
+    "keep-outputs=all",
+    // modelrig init (Phase 5 WS2)
+    "dry-run",
+    "include-tests",
+]);
+function parseArgs(argv) {
+    const positional = [];
+    const named = new Map();
+    const bare = new Set();
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const name = arg.slice(2);
+            if (BARE_FLAGS.has(name)) {
+                bare.add(name);
+                continue;
+            }
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                throw new Error(`flag ${arg} needs a value`);
+            }
+            named.set(name, value);
+            i += 1;
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { positional, named, bare };
+}
+function fmtEff(usd) {
+    return Number.isFinite(usd) ? `$${usd.toFixed(4)}` : "∞ (0 conformant)";
+}
+function printMatrix(artifact) {
+    console.log(`bakeoff ${artifact.id}\nroute ${artifact.route}@${artifact.routeVersion} · replayed ${artifact.replayN} captured inputs · ${artifact.ranAt}`);
+    const header = ["variant", "n", "conform", "ci95", "repair", "repair$", "lat(ms)", "eff-$/1K-conf"];
+    const rows = artifact.variants.map((m) => [
+        m.variant,
+        String(m.samples),
+        `${(m.conformRate * 100).toFixed(0)}%`,
+        `[${(m.conformCi95[0] * 100).toFixed(0)},${(m.conformCi95[1] * 100).toFixed(0)}]`,
+        `${(m.repairRate * 100).toFixed(0)}%`,
+        `$${m.meanRepairCostUsd.toFixed(4)}`,
+        m.meanLatencyMs.toFixed(0),
+        m.pricingMissing ? "UNPRICED (no ranking)" : fmtEff(m.effectiveUsdPer1kConformant),
+    ]);
+    const widths = header.map((h, c) => Math.max(h.length, ...rows.map((r) => r[c].length)));
+    const line = (cells) => cells.map((cell, c) => cell.padEnd(widths[c])).join("  ");
+    console.log(line(header));
+    for (const row of rows)
+        console.log(line(row));
+    if (artifact.proposal !== null) {
+        console.log(`PROPOSAL: variant "${artifact.proposal.variant}" beats the incumbent by ` +
+            `${artifact.proposal.vsIncumbentSavingsPct.toFixed(1)}% effective cost — human decision required; ` +
+            "nothing is executed.");
+    }
+    else {
+        console.log("proposal: none (no variant beats the incumbent's gates)");
+    }
+}
+/** Control-plane client from config.export — the watch/proposal surfaces
+ * need it; a clear error beats a silent no-op. */
+function proposalsClientFrom(config) {
+    const exp = (0, config_1.directExportOf)(config, "this command");
+    return (0, proposals_1.createProposalsClient)({
+        supabaseUrl: exp.supabaseUrl,
+        serviceRoleKey: exp.serviceRoleKey,
+    });
+}
+/** A3: --keep-outputs (winner) | --keep-outputs=all | off. */
+function keepOutputsMode(flags) {
+    if (flags.bare.has("keep-outputs=all"))
+        return "all";
+    if (flags.bare.has("keep-outputs"))
+        return "winner";
+    return undefined;
+}
+async function runAndReportBakeoff(config, flags, route, variants, replayLastN, envelope) {
+    const keep = keepOutputsMode(flags);
+    if (keep !== undefined)
+        (0, config_1.directExportOf)(config, "--keep-outputs (bakeoff_samples lives there)");
+    const mirrorTarget = config.export?.mode === "direct" ? config.export : undefined;
+    const rig = (0, index_1.createRig)(config);
+    try {
+        const artifact = await rig.bakeoff(route, {
+            variants,
+            replayLastN,
+            ...(envelope !== undefined ? { envelopeUsdPerVariant: envelope } : {}),
+            ...(keep !== undefined ? { keepOutputs: keep } : {}),
+        });
+        const outDir = (0, node_path_1.join)((0, node_path_1.dirname)(config.telemetryDbPath), "bakeoffs");
+        (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+        const artifactPath = (0, node_path_1.join)(outDir, `${artifact.id}.json`);
+        (0, node_fs_1.writeFileSync)(artifactPath, `${JSON.stringify(artifact, null, 2)}\n`);
+        let mirrored = false;
+        if (mirrorTarget !== undefined && !flags.bare.has("no-mirror")) {
+            await (0, engine_1.mirrorBakeoff)(artifact, {
+                supabaseUrl: mirrorTarget.supabaseUrl,
+                serviceRoleKey: mirrorTarget.serviceRoleKey,
+                sourceId: mirrorTarget.sourceId ?? (0, node_os_1.hostname)(),
+            });
+            mirrored = true;
+        }
+        if (flags.bare.has("json")) {
+            console.log(JSON.stringify(artifact, null, 2));
+        }
+        else {
+            printMatrix(artifact);
+        }
+        console.log(`artifact → ${artifactPath}${mirrored ? " · mirrored to bakeoffs" : ""}` +
+            (keep !== undefined
+                ? ` · review samples kept (${keep}) → console /samples?bakeoff=${artifact.id}`
+                : ""));
+        return artifact;
+    }
+    finally {
+        rig.close();
+    }
+}
+async function cmdBakeoff(flags) {
+    const config = (0, config_1.loadConfigFromEnv)();
+    const proposalId = flags.named.get("from-proposal");
+    if (proposalId !== undefined) {
+        // Evidence run for a watch proposal — budget-enveloped by the monthly
+        // watch cap, evidence attached on completion (suggested → evidenced).
+        const client = proposalsClientFrom(config);
+        const proposal = await client.get(proposalId);
+        if (proposal === null)
+            throw new Error(`no proposal "${proposalId}" on the control plane`);
+        if (proposal.status !== "suggested" && proposal.status !== "evidenced") {
+            throw new Error(`proposal ${proposalId} is ${proposal.status} — evidence runs apply to ` +
+                "suggested/evidenced proposals only");
+        }
+        const routes = (0, loader_1.loadRoutes)(config.routesDir);
+        const bundle = routes.get(proposal.route);
+        const variants = ["default", ...bundle.variants.map((v) => v.name)];
+        const lastRaw = flags.named.get("replay-last");
+        const replayLastN = lastRaw !== undefined ? Number(lastRaw) : 25;
+        if (!Number.isInteger(replayLastN) || replayLastN < 1) {
+            throw new Error("--replay-last must be a positive integer");
+        }
+        // Monthly watch budget: reserve headroom, split it across variants,
+        // accrue what the run actually spent afterwards.
+        const budgetStore = (0, store_1.openTelemetryStore)(config.telemetryDbPath);
+        try {
+            const monthlyUsd = config.watch?.monthlyUsd ?? budget_1.DEFAULT_WATCH_MONTHLY_USD;
+            const reservation = (0, budget_1.reserveWatchBudget)(budgetStore, monthlyUsd, new Date());
+            const perVariant = reservation.remainingUsd / variants.length;
+            console.log(`watch budget ${reservation.key}: $${reservation.remainingUsd.toFixed(2)} remaining → ` +
+                `$${perVariant.toFixed(2)}/variant cap`);
+            const artifact = await runAndReportBakeoff(config, flags, proposal.route, variants, replayLastN, perVariant);
+            const spentUsd = artifact.variants.reduce((a, m) => a + m.samples * m.meanCostUsd, 0);
+            budgetStore.accrue(reservation.key, spentUsd);
+            await client.attachEvidence(proposal.id, {
+                bakeoff_id: artifact.id,
+                replay_n: artifact.replayN,
+                ran_at: artifact.ranAt,
+                spent_usd: spentUsd,
+                proposal: artifact.proposal,
+                matrix: artifact.variants.map((m) => ({
+                    variant: m.variant,
+                    samples: m.samples,
+                    conform_rate: m.conformRate,
+                    conform_ci95: m.conformCi95,
+                    effective_usd_per_1k_conformant: Number.isFinite(m.effectiveUsdPer1kConformant)
+                        ? m.effectiveUsdPer1kConformant
+                        : null,
+                    pricing_missing: m.pricingMissing,
+                })),
+            });
+            console.log(`evidence attached → proposal ${proposal.id} is now evidenced ` +
+                `($${spentUsd.toFixed(2)} accrued to ${reservation.key}). ` +
+                "Approval stays human: modelrig swap execute <proposalId> --approve");
+            return 0;
+        }
+        finally {
+            budgetStore.close();
+        }
+    }
+    const route = flags.named.get("route");
+    const variantsRaw = flags.named.get("variants");
+    const lastRaw = flags.named.get("replay-last");
+    if (route === undefined || variantsRaw === undefined || lastRaw === undefined) {
+        throw new Error("bakeoff requires --route, --variants a,b,c and --replay-last N (or --from-proposal <id>)");
+    }
+    const variants = variantsRaw.split(",").map((v) => v.trim()).filter((v) => v !== "");
+    const replayLastN = Number(lastRaw);
+    if (!Number.isInteger(replayLastN) || replayLastN < 1) {
+        throw new Error("--replay-last must be a positive integer");
+    }
+    const envelopeRaw = flags.named.get("envelope");
+    const envelope = envelopeRaw !== undefined ? Number(envelopeRaw) : undefined;
+    if (envelope !== undefined && (!Number.isFinite(envelope) || envelope <= 0)) {
+        throw new Error("--envelope must be positive");
+    }
+    await runAndReportBakeoff(config, flags, route, variants, replayLastN, envelope);
+    return 0;
+}
+const DEFAULT_WATCH_THRESHOLD_PCT = 10;
+async function cmdWatch(flags) {
+    const sub = flags.positional[0];
+    if (sub !== "run") {
+        throw new Error("usage: modelrig watch run [--events fixtures.json] [--json]");
+    }
+    const config = (0, config_1.loadConfigFromEnv)();
+    const client = proposalsClientFrom(config);
+    const routes = (0, loader_1.loadRoutes)(config.routesDir);
+    const routeEconomics = routes.list().map((b) => ({
+        route: b.route,
+        candidates: b.candidates.map((c) => ({ provider: c.provider, model: c.model })),
+    }));
+    const providers = new Set(routeEconomics.flatMap((r) => r.candidates.map((c) => c.provider)));
+    const eventsPath = flags.named.get("events");
+    const injectedEvents = eventsPath !== undefined
+        ? JSON.parse((0, node_fs_1.readFileSync)(eventsPath, "utf8"))
+        : undefined;
+    // A4: on a cron container the pricing snapshot MUST outlive the process.
+    // A file-backed store there re-seeds every run and can never fire an event.
+    // Durable watch state needs the database itself, so api mode gets the local
+    // file (and the warning below) exactly as an unconfigured rig does.
+    const watchExport = config.export?.mode === "direct" ? config.export : undefined;
+    const store = (0, state_store_1.createWatchStateStore)({
+        filePath: (0, node_path_1.join)((0, node_path_1.dirname)(config.telemetryDbPath), "watch-state.json"),
+        export: watchExport,
+    });
+    if (watchExport === undefined) {
+        console.warn("[modelrig] watch state is local-file only — fine on your machine, but on an ephemeral " +
+            "container every cycle re-seeds and no price change can ever fire. Configure " +
+            "MODELRIG_SUPABASE_URL + MODELRIG_SUPABASE_SERVICE_ROLE_KEY for durable state.");
+    }
+    // The cycle reports its own outcome to the control plane. A4 gave this job
+    // durable state but no proof of life: `control_state` sat empty for a week
+    // and "never scheduled", "running and failing" and "running and finding
+    // nothing" were indistinguishable from outside, readable only through the
+    // hosting platform's log viewer. Now the job answers for itself.
+    const result = await (0, run_reported_1.runWatchCycleReported)({
+        routes: routeEconomics,
+        store,
+        universe: (0, state_1.buildPriceUniverse)(providers),
+        client,
+        thresholdPct: config.watch?.thresholdPct ?? DEFAULT_WATCH_THRESHOLD_PCT,
+        ...(injectedEvents !== undefined ? { injectedEvents } : {}),
+    }, {
+        supabaseUrl: watchExport?.supabaseUrl ?? "",
+        serviceRoleKey: watchExport?.serviceRoleKey ?? "",
+    });
+    if (flags.bare.has("json")) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else if (result.seeded) {
+        console.log("watch: seeded pricing state (first run watches silently — events fire from the next cycle)\n" +
+            `       state → ${store.description}`);
+    }
+    else {
+        console.log(`watch: ${result.events} event(s) → ${result.drafts} draft(s) → ` +
+            `${result.inserted} new proposal(s) (duplicates deduped; run \`modelrig bakeoff ` +
+            "--from-proposal <id>` to attach evidence — nothing executes automatically)");
+    }
+    return 0;
+}
+function swapsClientFrom(config) {
+    const exp = (0, config_1.directExportOf)(config, "this command");
+    return (0, swaps_client_1.createSwapsClient)({
+        supabaseUrl: exp.supabaseUrl,
+        serviceRoleKey: exp.serviceRoleKey,
+    });
+}
+async function cmdSwapExecute(flags) {
+    const proposalId = flags.positional[1];
+    if (proposalId === undefined) {
+        throw new Error("usage: modelrig swap execute <proposalId> --approve [--approved-by name]");
+    }
+    // THE gate (spec hard rule): no --approve, no execution — full stop,
+    // before any config or network access.
+    if (!flags.bare.has("approve")) {
+        throw new Error("swap execution requires explicit --approve — proposals never auto-execute. " +
+            `Re-run: modelrig swap execute ${proposalId} --approve`);
+    }
+    const config = (0, config_1.loadConfigFromEnv)();
+    const proposals = proposalsClientFrom(config);
+    const swaps = swapsClientFrom(config);
+    const routes = (0, loader_1.loadRoutes)(config.routesDir);
+    // The orchestration (guards, ordering, baseline snapshot) lives in the
+    // hermetically-tested executeSwap; the CLI only injects the real config
+    // deps and prints. The --approve gate is enforced here (fast-fail before
+    // config) AND inside executeSwap (defense in depth).
+    const result = await (0, swap_execute_1.executeSwap)({
+        proposalId,
+        approve: flags.bare.has("approve"),
+        approvedBy: flags.named.get("approved-by") ?? (0, node_os_1.userInfo)().username,
+        proposals,
+        swaps,
+        loadBundle: (route) => routes.get(route),
+        newId: () => (0, node_crypto_1.randomUUID)(),
+        now: () => new Date().toISOString(),
+    });
+    console.log(`swap ${result.swapId} recorded (approved by ${result.approvedBy}) — ` +
+        `${result.change.fromModel} → ${result.change.toModel}\n`);
+    console.log("APPLY THIS CHANGE (the executor never edits route files — git does):\n");
+    console.log(result.change.yaml);
+    console.log(`REVERT COMMAND (any time): modelrig swap revert ${result.swapId}\n` +
+        `The odometer starts measuring ${result.route} savings from the moment the change deploys.`);
+    return 0;
+}
+async function cmdSwapRevert(flags) {
+    const swapId = flags.positional[1];
+    if (swapId === undefined)
+        throw new Error("usage: modelrig swap revert <swapId>");
+    const config = (0, config_1.loadConfigFromEnv)();
+    const swaps = swapsClientFrom(config);
+    const swap = await swaps.get(swapId);
+    if (swap === null)
+        throw new Error(`no swap "${swapId}" on the control plane`);
+    if (swap.revertedAt !== null) {
+        console.log(`swap ${swapId} was already reverted at ${swap.revertedAt} — nothing to do`);
+        return 0;
+    }
+    const revertedAt = new Date().toISOString();
+    await swaps.markReverted(swapId, revertedAt);
+    const incumbents = swap.baseline.incumbent_candidates ?? [];
+    console.log(`swap ${swapId} marked reverted — the odometer stops accruing it at ${revertedAt}\n`);
+    console.log("APPLY THIS CHANGE (git is the actuator, as always):\n");
+    const routes = (0, loader_1.loadRoutes)(config.routesDir);
+    let version = null;
+    try {
+        version = routes.get(swap.route).version + 1;
+    }
+    catch {
+        // Route no longer loads locally — emit without the version line.
+    }
+    console.log([
+        `# revert swap ${swapId}: restore ${swap.route} to its pre-swap candidate order`,
+        `# apply to modelrig/routes/${swap.route}.yaml`,
+        ...(version !== null ? [`version: ${version}`] : ["# bump the version field by 1"]),
+        "candidates:",
+        ...incumbents.flatMap((c) => [`  - provider: ${c.provider}`, `    model: ${c.model}`]),
+        "",
+    ].join("\n"));
+    return 0;
+}
+async function cmdSwap(flags) {
+    const sub = flags.positional[0];
+    if (sub === "execute")
+        return cmdSwapExecute(flags);
+    if (sub === "revert")
+        return cmdSwapRevert(flags);
+    throw new Error("usage: modelrig swap execute <proposalId> --approve [--approved-by name] | modelrig swap revert <swapId>");
+}
+async function cmdSamples(flags) {
+    const sub = flags.positional[0];
+    if (sub !== "purge") {
+        throw new Error("usage: modelrig samples purge [--bakeoff <id>]");
+    }
+    const config = (0, config_1.loadConfigFromEnv)();
+    const samplesExport = (0, config_1.directExportOf)(config, "samples purge");
+    const client = (0, samples_1.createBakeoffSamplesClient)({
+        supabaseUrl: samplesExport.supabaseUrl,
+        serviceRoleKey: samplesExport.serviceRoleKey,
+    });
+    const bakeoffId = flags.named.get("bakeoff");
+    const deleted = await client.purge(bakeoffId !== undefined ? { bakeoffId } : { nowIso: new Date().toISOString() });
+    console.log(bakeoffId !== undefined
+        ? `purged ${deleted} review sample(s) for bakeoff ${bakeoffId}`
+        : `purged ${deleted} expired review sample(s)`);
+    return 0;
+}
+/**
+ * `modelrig init [path]` — Phase 5 WS2. Scans a repo for provider call
+ * sites and drafts a route bundle per site, plus a MIGRATION.md map.
+ *
+ * It writes ONLY under <routes-dir>/drafts/. Your source is never edited;
+ * applying the migration is a human's diff to make.
+ */
+async function cmdInit(flags) {
+    const root = (0, node_path_1.resolve)(flags.positional[0] ?? ".");
+    const config = (0, config_1.loadConfigFromEnv)();
+    const draftsDir = flags.named.get("out") ?? (0, node_path_1.join)(config.routesDir, "drafts");
+    // Registry rows seed the challenger candidates. A missing/unbuilt registry
+    // is not fatal — drafts then carry the incumbent alone, and say so.
+    let registryRows = [];
+    try {
+        registryRows = (0, rows_1.loadRegistryRows)(config.registryPath);
+    }
+    catch {
+        registryRows = [];
+    }
+    const result = (0, run_1.runInit)({
+        root,
+        draftsDir,
+        fs: { readdirSync: node_fs_1.readdirSync, readFileSync: node_fs_1.readFileSync, statSync: node_fs_1.statSync, existsSync: node_fs_1.existsSync, mkdirSync: node_fs_1.mkdirSync, writeFileSync: node_fs_1.writeFileSync },
+        path: { join: node_path_1.join, relative: node_path_1.relative, dirname: node_path_1.dirname, basename: node_path_1.basename },
+    }, {
+        registryRows,
+        ...(flags.bare.has("dry-run") ? { dryRun: true } : {}),
+        ...(flags.bare.has("include-tests") ? { includeTests: true } : {}),
+    });
+    if (flags.bare.has("json")) {
+        console.log(JSON.stringify({
+            sitesFound: result.sitesFound,
+            filesScanned: result.filesScanned,
+            filesSkipped: result.filesSkipped,
+            routes: result.drafts.map((d) => ({
+                route: d.route,
+                file: d.site.file,
+                line: d.site.line,
+                provider: d.site.provider,
+                model: d.site.model,
+                notes: d.site.notes,
+            })),
+            written: result.written,
+            skipped: result.skipped,
+        }, null, 2));
+        return 0;
+    }
+    console.log(`modelrig init — scanned ${result.filesScanned} file(s) under ${root}\n` +
+        `found ${result.sitesFound} provider call site(s)`);
+    if (result.sitesFound === 0) {
+        console.log("\nNothing to draft. If you know there are model calls here, they may sit behind a helper\n" +
+            "that hides the SDK — point init at the file that actually calls the provider.");
+        return 0;
+    }
+    for (const draft of result.drafts) {
+        console.log(`  ${draft.site.file}:${draft.site.line} (${draft.site.provider}` +
+            `${draft.site.model !== null ? ` ${draft.site.model}` : ""}) → ${draft.route}`);
+    }
+    if (result.filesSkipped.length > 0) {
+        console.log(`\n${result.filesSkipped.length} file(s) skipped (too large or unreadable).`);
+    }
+    if (flags.bare.has("dry-run")) {
+        console.log("\n--dry-run: nothing written.");
+        return 0;
+    }
+    console.log(`\nwrote ${result.written.length} file(s) to ${draftsDir}` +
+        (result.skipped.length > 0 ? ` (${result.skipped.length} left alone — already there)` : "") +
+        `\nread ${(0, node_path_1.join)(draftsDir, "MIGRATION.md")} next. Your source was not touched.`);
+    return 0;
+}
+/**
+ * `modelrig serve` — Phase 5 WS4's zero-config path. The HTTP surface lives
+ * in the separate `modelrig-server` package (it has its own auth and budget
+ * concerns); this is the one command name people will reach for, so it
+ * hands off rather than making them learn a second package name.
+ *
+ * The dependency stays one-way: the core package does not depend on the
+ * server, it just calls it when present and teaches when it isn't.
+ */
+async function cmdServe() {
+    let serverMain = null;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const mod = require("modelrig-server");
+        serverMain = mod.main ?? null;
+    }
+    catch {
+        serverMain = null;
+    }
+    if (serverMain === null) {
+        console.error([
+            "`modelrig serve` needs the server package, which isn't installed here.",
+            "",
+            "  pnpm add modelrig-server        (or npm i / yarn add)",
+            "",
+            "It's a separate package because serving over HTTP brings its own concerns —",
+            "a bearer token and a daily spend cap — that a library shouldn't assume for you.",
+            "You do NOT need it to use ModelRig from your own code: `rig.run(...)` works",
+            "without any server at all. Docs: https://modelrig.dev/quickstart.html",
+        ].join("\n"));
+        return 1;
+    }
+    serverMain();
+    // The server owns the process from here (it holds the listener open).
+    return 0;
+}
+async function main(argv) {
+    const [command, ...rest] = argv;
+    const flags = parseArgs(rest);
+    switch (command) {
+        case "bakeoff":
+            return cmdBakeoff(flags);
+        case "watch":
+            return cmdWatch(flags);
+        case "swap":
+            return cmdSwap(flags);
+        case "samples":
+            return cmdSamples(flags);
+        case "init":
+            return cmdInit(flags);
+        case "serve":
+            return cmdServe();
+        default:
+            console.error([
+                "usage:",
+                "  modelrig init [path] [--out dir] [--dry-run] [--include-tests] [--json]",
+                "  modelrig serve                       (needs the modelrig-server package)",
+                "  modelrig bakeoff --route <route> --variants a,b,c --replay-last N [--envelope usd] [--keep-outputs[=all]] [--json] [--no-mirror]",
+                "  modelrig bakeoff --from-proposal <id> [--replay-last N] [--keep-outputs[=all]] [--json]",
+                "  modelrig watch run [--events fixtures.json] [--json]",
+                "  modelrig swap execute <proposalId> --approve [--approved-by name]",
+                "  modelrig swap revert <swapId>",
+                "  modelrig samples purge [--bakeoff <id>]",
+            ].join("\n"));
+            return 1;
+    }
+}
+if (require.main === module) {
+    main(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((err) => {
+        // Errors that teach (WS3): a typed failure prints what happened, what
+        // to do, and where to read — from the one table, not from here.
+        if (err instanceof failures_1.RigFailureError) {
+            console.error((0, failures_teaching_1.renderFailureForTerminal)(err.failure));
+        }
+        else if ((0, failures_1.isRigFailure)(err)) {
+            console.error((0, failures_teaching_1.renderFailureForTerminal)(err));
+        }
+        else {
+            console.error(err instanceof Error ? err.message : String(err));
+        }
+        process.exitCode = 1;
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Configuration — plan §3. THE ONLY FILE that reads process.env in this
+ * package (adapters receive keys via constructors; enforced by
+ * __tests__/package-invariants.test.ts).
+ */
+import type { CapabilityFlag, ProviderId } from "./types/provider";
+export interface RigConfig {
+    readonly routesDir: string;
+    readonly telemetryDbPath: string;
+    readonly keys: {
+        readonly gemini?: string;
+        readonly openai?: string;
+        readonly deepseek?: string;
+        readonly anthropic?: string;
+        /** xAI — env: XAI_API_KEY (xAI's own convention). */
+        readonly grok?: string;
+        /** A1 aggregator hosts (generic openai-compatible adapter). */
+        readonly deepinfra?: string;
+        readonly fireworks?: string;
+    };
+    /** Budget for envelopes first opened by this rig (default: envelope.ts's $25). */
+    readonly envelopeBudgetUsd?: number;
+    /** Addendum A1: USD/MTok charged to an active envelope for models with no
+     * pricing entry (default $100 — generous-high; envelopes fail closed). */
+    readonly unpricedRateUsdPerMTok?: number;
+    /** Capability overrides — the escape hatch ABOVE the registry (precedence:
+     * overrides > probed > declared). When set for a provider, REPLACES the
+     * whole resolved flag set for every model of that provider — any misprobed
+     * fact is one config line from fixed. */
+    readonly capabilityOverrides?: Partial<Record<ProviderId, readonly CapabilityFlag[]>>;
+    /** Registry facts file (Phase 3 WS6) — default: the packaged
+     * registry/registry.json. Env: MODELRIG_REGISTRY_PATH. */
+    readonly registryPath?: string;
+    /** Search provider for the grounding-inject rung (Phase 3 WS3) — omitted
+     * means `require: grounded` routes resolve natively-grounded candidates
+     * only. */
+    readonly search?: {
+        readonly tavilyApiKey: string;
+        readonly costPerSearchUsd?: number;
+        readonly searchDepth?: "basic" | "advanced";
+    };
+    /** Watch loop (Phase 4 WS1): monthly paid-run cap + material-shift
+     * threshold. Defaults apply when unset; the loop itself is opt-in (a cron
+     * running `modelrig watch run`). */
+    readonly watch?: {
+        readonly monthlyUsd?: number;
+        readonly thresholdPct?: number;
+    };
+    /**
+     * Cloud telemetry sink — omitted => local SQLite only.
+     *
+     * telemetry-ingestion-boundary.md §2.4's three modes, as a discriminated
+     * union rather than a bag of optional fields: `api` and `direct` need
+     * different credentials and it should be impossible to half-configure one.
+     *
+     *   local-only  pure-router users, ZDR-strict      no credentials
+     *   api         every hosted customer               their rig_sk_ key only
+     *   direct      self-host + our own deployments     their own database
+     */
+    readonly export?: ApiExportConfig | DirectExportConfig;
+}
+interface ExportCommon {
+    readonly sourceId?: string;
+    readonly batchSize?: number;
+    readonly intervalMs?: number;
+}
+export interface ApiExportConfig extends ExportCommon {
+    readonly mode: "api";
+    /** `rig_sk_…` with the `ingest` scope. The ONLY credential a hosted
+     * customer holds — database credentials never leave our infrastructure. */
+    readonly apiKey: string;
+    readonly ingestUrl: string;
+}
+export interface DirectExportConfig extends ExportCommon {
+    readonly mode: "direct";
+    readonly supabaseUrl: string;
+    readonly serviceRoleKey: string;
+    /** The tenant this deployment stamps. Defaults to the house org, which is
+     * the right answer for a self-hosted control plane: there is one org there
+     * and everything belongs to it. */
+    readonly orgId?: string;
+    readonly projectId?: string | null;
+}
+/** Provider → the env var that keys it. One table so error surfaces can say
+ * WHICH variable to set rather than "no key configured" (F1 / WS3: errors
+ * that teach). `loadConfigFromEnv` below reads the same names. */
+export declare const PROVIDER_KEY_ENV: Readonly<Record<string, string>>;
+export declare function loadConfigFromEnv(overrides?: Partial<RigConfig>): RigConfig;
+/**
+ * Narrow `config.export` to DIRECT mode, or explain why the command cannot run.
+ *
+ * Phase 6 WS2 gave the export config two modes. Every command below needs a
+ * service-role control-plane client — proposals, swap events, bake-off
+ * mirrors, sample purges — and none of those has an ingest endpoint. A rig
+ * configured in api mode therefore genuinely cannot run them, and saying so is
+ * better than the `undefined` deref this used to be one refactor away from.
+ */
+export declare function directExportOf(config: RigConfig, what: string): {
+    readonly supabaseUrl: string;
+    readonly serviceRoleKey: string;
+    readonly sourceId?: string;
+};
+export {};
+//# sourceMappingURL=config.d.ts.map