modelrig 0.0.1 → 0.2.0

package/dist/verify/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Shadow-equivalence verifier contracts (Expansion §9, autonomy-ladder Tier 2).
+ *
+ * The verifier proves a SAME-MODEL call replacement is behavior-preserving
+ * BEFORE a human merges the Tier-2 PR: capture N invocations of the original
+ * call site's inputs/outputs locally, replay the SAME inputs through the
+ * ModelRig-routed replacement (same provider/model PINNED — this verifies the
+ * PLUMBING, never the model choice), diff the outputs, and emit a report the
+ * skill embeds in the PR.
+ *
+ * Honest refusal is a first-class output: a call site that can't be captured
+ * or replayed (streaming, dynamically-assembled prompts, or a route that does
+ * not pin the original model) is REFUSED, not forced — those sites are T0/T1
+ * territory per the spec's stated limits.
+ */
+import type { CandidateSpec } from "../types/route";
+/** One recorded original invocation: the extracted template variables that
+ * reconstruct the original prompt through the drafted route, and the original
+ * call's raw output text. */
+export interface ShadowCapture {
+    /** The extracted template variables (Tier-2 turns a prompt into
+     * `systemTemplate` + variables); replayed through the route unchanged. */
+    readonly input: Record<string, unknown>;
+    /** The original call site's raw output text, verbatim. */
+    readonly output: string;
+}
+/** A call site (or a single input) that could NOT be captured/replayed.
+ * Refusing IS a correct output — these are T0/T1 territory, never a failure. */
+export interface CaptureRefusal {
+    readonly reason: "streaming" | "dynamic-prompt" | "uncapturable";
+    readonly detail: string;
+}
+/** The portable capture fixture the skill writes and the verifier reads. Stays
+ * local (SQLite/JSON in the SDK process) — nothing here uploads. */
+export interface ShadowCaptureFixture {
+    /** Where the original call lives, e.g. "src/pipeline/summarize.ts:42". */
+    readonly callSiteId: string;
+    /** The provider+model of the ORIGINAL call — the route MUST pin exactly this
+     * (same-model replacement; the verifier refuses otherwise). */
+    readonly original: CandidateSpec;
+    readonly capturedAt: string;
+    readonly samples: readonly ShadowCapture[];
+    /** Inputs/sites the capture step honestly declined (streaming, dynamic). */
+    readonly refusals?: readonly CaptureRefusal[];
+    /** JSON-pointer paths (exact, or subtree prefixes) whose value is allowed to
+     * differ without counting as a divergence — the migration's declared
+     * free-text / nondeterministic fields (e.g. "/summary"). Absent = every
+     * field must match (the conservative default). */
+    readonly nondeterministicPaths?: readonly string[];
+}
+/** Per-sample verdict — the honest three-way vocabulary. */
+export type SampleVerdict = "equivalent" | "equivalent-modulo-nondeterminism" | "divergent";
+/** Whole-run verdict: the per-sample vocabulary plus `refused` (the run never
+ * ran — pin violation, or nothing capturable). */
+export type EquivalenceVerdict = SampleVerdict | "refused";
+/** The result of diffing one original/routed output pair. */
+export interface SampleDiff {
+    readonly verdict: SampleVerdict;
+    /** First differing structured field (JSON-pointer) when divergent on
+     * structured output; null when equivalent, modulo, or divergent for a
+     * non-field reason (bad JSON, plumbing failure, model mismatch). */
+    readonly firstDivergentPath: string | null;
+    readonly detail: string;
+}
+export interface SampleReport extends SampleDiff {
+    readonly index: number;
+    /** "provider/model" that actually served the replay — null when the replay
+     * itself failed before any model served. */
+    readonly servedModel: string | null;
+    readonly costUsd: number;
+    /** Set when the routed replay threw a typed failure (the plumbing could not
+     * produce a conformant output for this input) — itself a divergence. */
+    readonly failureClass: string | null;
+}
+export interface EquivalenceReport {
+    readonly schemaVersion: 1;
+    readonly kind: "shadow-equivalence";
+    readonly callSiteId: string;
+    readonly route: string;
+    readonly routeVersion: number;
+    /** "provider/model" the route pins — equal to the original by construction
+     * (the verifier refuses when it isn't). */
+    readonly pinnedModel: string;
+    readonly ranAt: string;
+    readonly n: number;
+    readonly overall: EquivalenceVerdict;
+    readonly counts: {
+        readonly equivalent: number;
+        readonly equivalentModulo: number;
+        readonly divergent: number;
+    };
+    readonly samples: readonly SampleReport[];
+    /** Capture-time refusals, surfaced verbatim (never a silent subset). */
+    readonly refusals: readonly CaptureRefusal[];
+    /** Set when `overall === "refused"` — why the run never ran. */
+    readonly refusalReason: string | null;
+    /** The plumbing-not-model-choice statement, embedded in the report so a PR
+     * reader cannot mistake equivalence for a model-quality claim. */
+    readonly guarantee: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/verify/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/verify/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;6BAE6B;AAC7B,MAAM,WAAW,aAAa;IAC5B;8EAC0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;gFACgF;AAChF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,gBAAgB,GAAG,cAAc,CAAC;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;oEACoE;AACpE,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;mEAC+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC9C;;;sDAGkD;IAClD,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpD;AAED,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,kCAAkC,GAClC,WAAW,CAAC;AAEhB;kDACkD;AAClD,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,SAAS,CAAC;AAE3D,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC;;wEAEoE;IACpE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;gDAC4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;4EACwE;IACxE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;+CAC2C;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,gEAAgE;IAChE,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC;sEACkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/dist/verify/types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Shadow-equivalence verifier contracts (Expansion §9, autonomy-ladder Tier 2).
+ *
+ * The verifier proves a SAME-MODEL call replacement is behavior-preserving
+ * BEFORE a human merges the Tier-2 PR: capture N invocations of the original
+ * call site's inputs/outputs locally, replay the SAME inputs through the
+ * ModelRig-routed replacement (same provider/model PINNED — this verifies the
+ * PLUMBING, never the model choice), diff the outputs, and emit a report the
+ * skill embeds in the PR.
+ *
+ * Honest refusal is a first-class output: a call site that can't be captured
+ * or replayed (streaming, dynamically-assembled prompts, or a route that does
+ * not pin the original model) is REFUSED, not forced — those sites are T0/T1
+ * territory per the spec's stated limits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/verify/verify.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shadow-equivalence orchestrator (Expansion §9, Tier 2) — the replay-and-diff
+ * pass that proves a same-model call replacement is behavior-preserving before
+ * a human merges the Tier-2 PR.
+ *
+ * Reuse, not twin (dev-rule S1): the EXECUTOR is the run loop — the same
+ * verified pipeline `rig.run()` drives — and the replay POSTURE is the
+ * bake-off's (`bakeoff/replay.ts`): captures severed (no capture-of-verify),
+ * one hard envelope across the pass, per-sample cost reconstructed from the
+ * tagged telemetry rows. What differs, and why this is a sibling of
+ * `replayVariant` rather than a call into it: shadow-equivalence pins a
+ * SPECIFIC captured input (not "last N by route"), needs the routed OUTPUT for
+ * a pairwise diff (not an aggregate metric), and asserts the served model
+ * equals the pinned original (a plumbing check variant comparison never makes).
+ */
+import type { RunDeps } from "../run/run";
+import type { EquivalenceReport, ShadowCaptureFixture } from "./types";
+export interface VerifySwapRequest {
+    /** The drafted replacement route (must pin the original model — see below). */
+    readonly route: string;
+    /** The local capture fixture (original inputs/outputs). Never uploaded. */
+    readonly fixture: ShadowCaptureFixture;
+    /** Hard cap for the whole replay pass (default $10). */
+    readonly envelopeUsd?: number;
+    /** Injectable clock for a deterministic `ranAt` (tests). */
+    readonly now?: () => string;
+}
+export declare function verifySwap(deps: RunDeps, req: VerifySwapRequest): Promise<EquivalenceReport>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/verify/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAK1C,OAAO,KAAK,EACV,iBAAiB,EAIjB,oBAAoB,EACrB,MAAM,SAAS,CAAC;AAWjB,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAiCD,wBAAsB,UAAU,CAC9B,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAsH5B"}

package/dist/verify/verify.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Shadow-equivalence orchestrator (Expansion §9, Tier 2) — the replay-and-diff
+ * pass that proves a same-model call replacement is behavior-preserving before
+ * a human merges the Tier-2 PR.
+ *
+ * Reuse, not twin (dev-rule S1): the EXECUTOR is the run loop — the same
+ * verified pipeline `rig.run()` drives — and the replay POSTURE is the
+ * bake-off's (`bakeoff/replay.ts`): captures severed (no capture-of-verify),
+ * one hard envelope across the pass, per-sample cost reconstructed from the
+ * tagged telemetry rows. What differs, and why this is a sibling of
+ * `replayVariant` rather than a call into it: shadow-equivalence pins a
+ * SPECIFIC captured input (not "last N by route"), needs the routed OUTPUT for
+ * a pairwise diff (not an aggregate metric), and asserts the served model
+ * equals the pinned original (a plumbing check variant comparison never makes).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifySwap = verifySwap;
+const run_1 = require("../run/run");
+const failures_1 = require("../types/failures");
+const diff_1 = require("./diff");
+/** One hard envelope for the whole verification pass when the caller sets none
+ * — replay is real, billed dispatch and must stay bounded (spec §9). */
+const DEFAULT_VERIFY_ENVELOPE_USD = 10;
+const GUARANTEE = "Same provider/model pinned on both sides: this verifies the PLUMBING of the " +
+    "ModelRig-routed replacement, never the model choice. Model optimization is a " +
+    "separate, human-gated bake-off decision.";
+function candidateEquals(a, b) {
+    return a.provider === b.provider && a.model === b.model;
+}
+/** Build a refused report — the run never ran (pin violation, or nothing to
+ * replay). Refusing IS a correct output; it costs nothing. */
+function refused(req, routeVersion, pinnedModel, reason, nowIso) {
+    return {
+        schemaVersion: 1,
+        kind: "shadow-equivalence",
+        callSiteId: req.fixture.callSiteId,
+        route: req.route,
+        routeVersion,
+        pinnedModel,
+        ranAt: nowIso,
+        n: 0,
+        overall: "refused",
+        counts: { equivalent: 0, equivalentModulo: 0, divergent: 0 },
+        samples: [],
+        refusals: req.fixture.refusals ?? [],
+        refusalReason: reason,
+        guarantee: GUARANTEE,
+    };
+}
+async function verifySwap(deps, req) {
+    const nowIso = (req.now ?? (() => new Date().toISOString()))();
+    const bundle = deps.routes.get(req.route);
+    const original = req.fixture.original;
+    const pinnedModel = `${original.provider}/${original.model}`;
+    // Same-model pin (the C2-exit gateway-substitution ruling): the route must
+    // pin EXACTLY the original model and nothing else. A route that offers other
+    // candidates would introduce model choice — which is not what this verifies.
+    const pins = bundle.candidates.length > 0 &&
+        bundle.candidates.every((c) => candidateEquals(c, original));
+    if (!pins) {
+        const declared = bundle.candidates.map((c) => `${c.provider}/${c.model}`).join(", ") || "none";
+        return refused(req, bundle.version, pinnedModel, `route "${req.route}" declares candidates [${declared}]; shadow-equivalence requires it to ` +
+            `pin exactly the original model ${pinnedModel} — this verifies plumbing, not model choice. ` +
+            "A multi-model route is a bake-off, not a Tier-2 replacement.", nowIso);
+    }
+    if (req.fixture.samples.length === 0) {
+        const hadRefusals = (req.fixture.refusals ?? []).length > 0;
+        return refused(req, bundle.version, pinnedModel, hadRefusals
+            ? "no replayable captures — every invocation was honestly refused (streaming / dynamic prompt); " +
+                "this call site is T0/T1 territory, not a Tier-2 replacement"
+            : "no captures to replay — capture N original invocations first", nowIso);
+    }
+    // Replay posture: sever captures (no capture-of-verify) and share one hard
+    // envelope, exactly as bakeoff/replay.ts does.
+    const envelopeUsd = req.envelopeUsd ?? DEFAULT_VERIFY_ENVELOPE_USD;
+    const replayDeps = { ...deps, captures: null, envelopeBudgetUsd: envelopeUsd };
+    const envelopeKey = `verify:${req.route}:${nowIso}`;
+    const nd = req.fixture.nondeterministicPaths ?? [];
+    const samples = [];
+    for (let index = 0; index < req.fixture.samples.length; index += 1) {
+        const capture = req.fixture.samples[index];
+        const sampleTag = `${envelopeKey}#${index}`;
+        let servedModel = null;
+        let failureClass = null;
+        let diff = { verdict: "divergent", firstDivergentPath: null, detail: "" };
+        try {
+            const result = await (0, run_1.run)(replayDeps, req.route, {
+                input: capture.input,
+                tags: { shadow_verify: envelopeKey, shadow_verify_sample: sampleTag },
+                budget: { envelope: envelopeKey, budgetUsd: envelopeUsd },
+            });
+            servedModel = `${result.meta.provider}/${result.meta.model}`;
+            if (servedModel !== pinnedModel) {
+                // A declared candidate served something other than the original — the
+                // plumbing does not preserve the model. Divergent, not equivalent.
+                diff = {
+                    verdict: "divergent",
+                    firstDivergentPath: null,
+                    detail: `routed run served ${servedModel}, not the pinned original ${pinnedModel} — a fallback fired`,
+                };
+            }
+            else {
+                const routedText = JSON.stringify(result.output);
+                diff = (0, diff_1.diffOutputs)(capture.output, result.output, routedText, nd);
+            }
+        }
+        catch (err) {
+            if (!(err instanceof failures_1.RigFailureError))
+                throw err;
+            failureClass = err.failure.class;
+            diff = {
+                verdict: "divergent",
+                firstDivergentPath: null,
+                detail: `routed replacement did not return a conformant output (${err.failure.class}): ` +
+                    `${err.failure.message} — the plumbing regressed for this input`,
+            };
+        }
+        // Per-sample cost from the tagged rows — base + retries + repair, exactly
+        // what telemetry billed (the bake-off's F1-correct accounting).
+        const costUsd = deps.telemetry
+            .queryByTag("shadow_verify_sample", sampleTag)
+            .reduce((a, r) => a + r.costEstimateUsd, 0);
+        samples.push({ index, ...diff, servedModel, costUsd, failureClass });
+    }
+    const counts = {
+        equivalent: samples.filter((s) => s.verdict === "equivalent").length,
+        equivalentModulo: samples.filter((s) => s.verdict === "equivalent-modulo-nondeterminism").length,
+        divergent: samples.filter((s) => s.verdict === "divergent").length,
+    };
+    const overall = counts.divergent > 0 ? "divergent" : counts.equivalentModulo > 0 ? "equivalent-modulo-nondeterminism" : "equivalent";
+    return {
+        schemaVersion: 1,
+        kind: "shadow-equivalence",
+        callSiteId: req.fixture.callSiteId,
+        route: req.route,
+        routeVersion: bundle.version,
+        pinnedModel,
+        ranAt: nowIso,
+        n: samples.length,
+        overall,
+        counts,
+        samples,
+        refusals: req.fixture.refusals ?? [],
+        refusalReason: null,
+        guarantee: GUARANTEE,
+    };
+}

package/dist/watch/budget.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Watch monthly spend cap — Phase 4 WS1 (spec: MODELRIG_WATCH_MONTHLY_USD,
+ * default $50). Every paid run the loop triggers (--from-proposal
+ * bake-offs, future re-probes) draws from a calendar-month envelope in the
+ * SAME envelope machinery that guards everything else — one budget system,
+ * not two.
+ */
+import type { TelemetryStore } from "../types/telemetry";
+export declare const DEFAULT_WATCH_MONTHLY_USD = 50;
+export declare function watchEnvelopeKey(now: Date): string;
+export interface WatchBudgetReservation {
+    readonly key: string;
+    readonly remainingUsd: number;
+}
+/** Open (idempotently) this month's watch envelope and report the headroom.
+ * Throws typed budget_exhausted when the month's cap is spent — the caller
+ * refuses the paid run; nothing silently overruns. */
+export declare function reserveWatchBudget(store: TelemetryStore, monthlyUsd: number, now: Date): WatchBudgetReservation;
+//# sourceMappingURL=budget.d.ts.map

package/dist/watch/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/watch/budget.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAElD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;sDAEsD;AACtD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,IAAI,GACR,sBAAsB,CAgBxB"}

package/dist/watch/budget.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Watch monthly spend cap — Phase 4 WS1 (spec: MODELRIG_WATCH_MONTHLY_USD,
+ * default $50). Every paid run the loop triggers (--from-proposal
+ * bake-offs, future re-probes) draws from a calendar-month envelope in the
+ * SAME envelope machinery that guards everything else — one budget system,
+ * not two.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WATCH_MONTHLY_USD = void 0;
+exports.watchEnvelopeKey = watchEnvelopeKey;
+exports.reserveWatchBudget = reserveWatchBudget;
+const failures_1 = require("../types/failures");
+exports.DEFAULT_WATCH_MONTHLY_USD = 50;
+function watchEnvelopeKey(now) {
+    return `watch-${now.toISOString().slice(0, 7)}`;
+}
+/** Open (idempotently) this month's watch envelope and report the headroom.
+ * Throws typed budget_exhausted when the month's cap is spent — the caller
+ * refuses the paid run; nothing silently overruns. */
+function reserveWatchBudget(store, monthlyUsd, now) {
+    const key = watchEnvelopeKey(now);
+    const envelope = store.openEnvelope(key, monthlyUsd);
+    const remainingUsd = Math.max(0, envelope.budgetUsd - envelope.spentUsd);
+    if (envelope.status === "exhausted" || remainingUsd <= 0) {
+        throw new failures_1.RigFailureError({
+            class: "budget_exhausted",
+            message: `watch monthly budget ${key} exhausted ` +
+                `($${envelope.spentUsd.toFixed(2)} of $${envelope.budgetUsd.toFixed(2)} spent)`,
+            fixHint: "Raise MODELRIG_WATCH_MONTHLY_USD or wait for the next calendar month — " +
+                "the watch loop never overruns its cap.",
+        });
+    }
+    return { key, remainingUsd };
+}

package/dist/watch/evaluate.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Watch diff-evaluators — Phase 4 WS1 (plan §4). Pure: no store, no
+ * network, no clock beyond the expiry stamp. Two event classes:
+ *
+ *   price_change — a candidate's pricing moved; when the blended cost shift
+ *     clears the threshold (default ±10%), every route declaring that
+ *     candidate gets a suggested bake-off proposal.
+ *   new_model    — a new pricing-map entry on a provider a route already
+ *     uses → suggested bake-off (the re-probe/bake-off run IS the evidence
+ *     step; the proposal never claims conformance it hasn't measured).
+ *
+ * Proposals NEVER execute anything. Idempotency: the trigger hash is a
+ * stable digest of (route, trigger content) — re-running a watch cycle over
+ * the same facts produces the same hashes, and the control-plane unique
+ * index (route, trigger_hash) makes duplicates a no-op.
+ */
+import type { CacheHysteresisConfig, CacheVerdict, EffectiveRates, ObservedCacheRates } from "../registry/effective-rate";
+export interface CandidateEconomics {
+    readonly provider: string;
+    readonly model: string;
+}
+export interface RouteEconomics {
+    readonly route: string;
+    readonly candidates: readonly CandidateEconomics[];
+}
+export interface TokenRates {
+    readonly inputUsdPerTok: number;
+    readonly outputUsdPerTok: number;
+}
+export type WatchEvent = {
+    readonly type: "price_change";
+    readonly provider: string;
+    readonly model: string;
+    readonly old: TokenRates;
+    readonly new: TokenRates;
+} | {
+    readonly type: "new_model";
+    readonly provider: string;
+    readonly model: string;
+    readonly pricing: TokenRates | null;
+};
+export interface WatchConfig {
+    /** Material-shift threshold in percent (spec default ±10). */
+    readonly thresholdPct: number;
+    /** Cache-aware hysteresis (cache-aware-routing spec §4.3) — the absolute
+     * per-call floor and relative window-spend threshold a cache-adjusted swap
+     * must clear to be `cache_positive`. OPTIONAL & additive: absent ⇒
+     * `DEFAULT_CACHE_HYSTERESIS`. Same home as `thresholdPct`, distinct numbers —
+     * the price-move threshold and the cache-swap hysteresis are different gates. */
+    readonly cacheHysteresis?: CacheHysteresisConfig;
+}
+/** Trigger payload persisted on the proposal row (jsonb). A discriminated union
+ * on `type`: the watch loop's price/model economics triggers, the Monitor's
+ * conform-rate degradation trigger (E4 chunk B), and the Rig Analyst's cluster
+ * findings (E6 chunk A). The watch/monitor triggers keep KIND `bakeoff`; the
+ * Analyst's triggers ride the widened kinds (`insight`/`promote-eval`) or reuse
+ * `bakeoff` for an Analyst-initiated bake-off — all through the SAME proposals
+ * machinery and the SAME `submitDrafts` seam (trajectory F1/F4, one emission path). */
+export type ProposalTrigger = EconomicsTrigger | ConformDegradationTrigger | AnalystClusterTrigger | AnalystPromoteEvalTrigger | AnalystBakeoffTrigger;
+/** The measured statistics behind one Analyst cluster — all deterministic. */
+export interface AnalystClusterStats {
+    /** Runs in this (task, cluster) over the window. */
+    readonly runs: number;
+    /** This cluster's fail rate, 0..1 (run-outcome@v1 verdicts). */
+    readonly failRate: number;
+    /** The org's window-wide fail rate, 0..1 — the salience baseline. */
+    readonly windowFailRate: number;
+    /** failRate − windowFailRate, in percentage POINTS (the salience margin). */
+    readonly failPtsOverWindow: number;
+    /** Feedback down-rate for the task, 0..1 (downs / (ups+downs)); 0 when none. */
+    readonly downRate: number;
+    /** Feedback signals (ups+downs) behind `downRate` — the min-n gate input. */
+    readonly feedbackN: number;
+    /** The dominant run-outcome failure_class label for the cluster, or null. */
+    readonly dominantFailureClass: string | null;
+}
+/** One reporting cluster → the `insight` proposal's trigger. `clusterKey` is the
+ * within-task discriminator (`fail:<class>` | `feedback` | `ok`); the window END
+ * (quantized to day) is what the trigger_hash keys on so re-runs dedupe. */
+export interface AnalystClusterTrigger {
+    readonly type: "analyst_cluster";
+    readonly task: string;
+    readonly clusterKey: string;
+    /** Trailing window bounds — inclusive-from / exclusive-to ISO days. */
+    readonly windowFrom: string;
+    readonly windowTo: string;
+    readonly stats: AnalystClusterStats;
+    /** Exemplar run ids (≤10) so a human can open the E2 run pages. */
+    readonly exemplarRunIds: readonly string[];
+}
+/** A failing cluster's promotable failing artifacts → the `promote-eval`
+ * proposal's trigger. Approving iterates `candidates` through the EXISTING
+ * promote path (≤ ANALYST_PROMOTE_MAX items). `task` is what each promote records. */
+export interface AnalystPromoteEvalTrigger {
+    readonly type: "analyst_promote_eval";
+    readonly task: string;
+    readonly clusterKey: string;
+    readonly windowFrom: string;
+    readonly windowTo: string;
+    readonly candidates: readonly AnalystPromoteCandidate[];
+}
+export interface AnalystPromoteCandidate {
+    readonly runId: string;
+    readonly artifactId: string;
+}
+/** A cluster on a route with a cheaper NON-serving candidate → an Analyst-
+ * initiated `bakeoff` proposal's trigger (the wedge motion). Only candidates the
+ * route already DECLARES may appear (STOP list: no novel challenger generation,
+ * that is E8). */
+export interface AnalystBakeoffTrigger {
+    readonly type: "analyst_bakeoff";
+    readonly task: string;
+    readonly route: string;
+    readonly clusterKey: string;
+    readonly windowFrom: string;
+    readonly windowTo: string;
+    /** The cheaper non-serving candidate the Analyst proposes baking off. */
+    readonly challenger: CandidateEconomics;
+    /** The route's current serving candidates (context for the human). */
+    readonly incumbents: readonly CandidateEconomics[];
+}
+/** Watch-loop trigger: a candidate's price moved, or a new model appeared. */
+export interface EconomicsTrigger {
+    readonly type: "price_change" | "new_model";
+    readonly provider: string;
+    readonly model: string;
+    /** Blended-cost percent change (price_change only). */
+    readonly deltaPct?: number;
+    readonly oldRates?: TokenRates;
+    readonly newRates?: TokenRates;
+    readonly pricing?: TokenRates | null;
+}
+/** One side of the degradation comparison (E4 chunk B) — a window's conform
+ * rate over its evaluations. Dates are inclusive-from / exclusive-to ISO days. */
+export interface ConformWindow {
+    readonly from: string;
+    readonly to: string;
+    readonly n: number;
+    readonly conformRate: number;
+}
+/** Monitor trigger (E4 chunk B): the recent window's deterministic conform rate
+ * fell below the trailing baseline by ≥ the ruled margin, with min-n met on both
+ * sides. Records BOTH windows + their ns so the evidence is self-explanatory. */
+export interface ConformDegradationTrigger {
+    readonly type: "conform_degradation";
+    readonly task: string;
+    readonly window: ConformWindow;
+    readonly baseline: ConformWindow;
+    /** The drop that flagged it, in percentage POINTS of conform rate. */
+    readonly dropPts: number;
+    readonly marginPts: number;
+    readonly minN: number;
+}
+/** The proposal-kind vocabulary. `bakeoff`/`swap` are the shipped watch/monitor
+ * kinds (00006); `insight`/`promote-eval` join for the Rig Analyst (E6, migration
+ * 00052 widens the DB CHECK to match). */
+export type ProposalKind = "bakeoff" | "swap" | "insight" | "promote-eval";
+export interface ProposalDraft {
+    readonly route: string;
+    readonly kind: ProposalKind;
+    readonly trigger: ProposalTrigger;
+    readonly triggerHash: string;
+    readonly expiresAt: string;
+    /** Evidence seeded AT INSERT (optional). The Rig Analyst embeds a new insight
+     * cluster's summary here (Chunk B) so the summary rides the same idempotent
+     * insert as the row — a duplicate (already-seen trigger_hash) is a no-op and
+     * never overwrites. Watch/monitor never set it. */
+    readonly evidence?: Record<string, unknown>;
+}
+export declare const PROPOSAL_TTL_DAYS = 30;
+export declare function triggerHash(route: string, trigger: ProposalTrigger): string;
+export declare function evaluateEvents(routes: readonly RouteEconomics[], events: readonly WatchEvent[], config: WatchConfig): ProposalDraft[];
+/** The §5.5 evidence block — every field the rendered explanation and the
+ * verdict need, in one self-describing object. Rates are per-Mtok (the surface
+ * unit); switch/option/spend quantities are USD. */
+export interface CacheContext {
+    readonly observed_hit_rate: number;
+    readonly observed_write_rate: number;
+    readonly window_days: number;
+    readonly incumbent_effective_in_per_mtok: number;
+    readonly challenger_cold_in_per_mtok: number;
+    readonly switch_cost_usd: number;
+    readonly cache_option_value_usd: number;
+    readonly breakeven_conformant_calls: number;
+    readonly verdict: CacheVerdict;
+}
+/** The inputs `buildCacheContext` needs — the incumbent's observed cache
+ * behavior + both candidates' rates + the switch geometry. Kept as explicit
+ * separate inputs (NOT a widened `watch/evaluate` local `TokenRates`) per the
+ * QA name-collision note: the effective blend takes the rollup and the rate
+ * cards as distinct arguments. */
+export interface CacheContextInput {
+    /** Incumbent's trailing-window observed cache rates (from `rollupCacheStats`). */
+    readonly observed: ObservedCacheRates;
+    readonly windowDays: number;
+    /** Incumbent (warm) rate card, USD/token. */
+    readonly incumbentRates: EffectiveRates;
+    /** Challenger (cold) rate card, USD/token. */
+    readonly challengerRates: EffectiveRates;
+    /** Warm prefix size the incumbent carries (tokens) — from the derived ledger. */
+    readonly incumbentPrefixTokens: number;
+    /** Expected remaining calls over which the decision amortizes. */
+    readonly remainingCalls: number;
+    /** Trailing-window spend on the route, USD — base of the relative bar. */
+    readonly windowSpendUsd: number;
+    /** True when the window carried ANY cache observation (read or write). When
+     * false the verdict is `no_cache_signal` regardless of the numbers. */
+    readonly hasCacheSignal: boolean;
+}
+/**
+ * Assemble the `cache_context` evidence block + verdict for a proposal (spec
+ * §5.5), pure. The verdict compares the incumbent's cache-ADJUSTED effective
+ * input rate against the challenger's COLD list rate, amortized over the switch
+ * cost, and gates on the hysteresis config. The advantage is measured PER
+ * CACHED PREFIX (the tokens the decision actually turns on), so a per-call
+ * dollar figure is directly comparable to the floor.
+ */
+export declare function buildCacheContext(input: CacheContextInput, config?: CacheHysteresisConfig): CacheContext;
+/**
+ * The [Briefing §30] rendered explanation — one prose line a human reads on the
+ * console and the `swap execute` approval prompt. Single-sourced here so the
+ * console, the CLI, and the OTLP span never phrase the same decision three ways.
+ */
+export declare function explainCacheContext(ctx: CacheContext, incumbentLabel: string, challengerLabel: string): string;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/watch/evaluate.d.ts.map

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