modelrig 0.0.1 → 0.2.0

package/dist/watch/proposals.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * Proposal lifecycle + control-plane client — Phase 4 WS1 (plan §4).
+ *
+ *   suggested → evidenced (bake-off attached)
+ *             → approved (human, recorded) → executed (swap machinery)
+ *   suggested|evidenced → rejected | expired
+ *
+ * Proposals NEVER auto-execute: "executed" is only reachable through
+ * "approved", and approval is a human CLI action (`swap execute --approve`).
+ * Transport is PostgREST with the service-role key — proposals are
+ * control-plane-only state (cross-run truth, not per-inference telemetry).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertTransition = assertTransition;
+exports.createProposalsClient = createProposalsClient;
+const ALLOWED_TRANSITIONS = {
+    suggested: ["evidenced", "rejected", "expired"],
+    evidenced: ["approved", "rejected", "expired"],
+    approved: ["executed"],
+    rejected: [],
+    executed: [],
+    expired: [],
+};
+function assertTransition(from, to) {
+    if (!ALLOWED_TRANSITIONS[from].includes(to)) {
+        throw new Error(`illegal proposal transition ${from} → ${to} (allowed from ${from}: ` +
+            `[${ALLOWED_TRANSITIONS[from].join(", ") || "none — terminal"}])`);
+    }
+}
+function toRecord(r) {
+    return {
+        id: r.id,
+        route: r.route,
+        kind: r.kind,
+        trigger: r.trigger,
+        triggerHash: r.trigger_hash,
+        evidence: r.evidence,
+        status: r.status,
+        createdAt: r.created_at,
+        updatedAt: r.updated_at,
+        expiresAt: r.expires_at,
+        approvedBy: r.approved_by ?? null,
+        decidedAt: r.decided_at ?? null,
+    };
+}
+function createProposalsClient(config) {
+    const fetchFn = config.fetchFn ?? fetch;
+    const base = config.supabaseUrl.replace(/\/$/, "");
+    async function request(path, init) {
+        const response = await fetchFn(`${base}/rest/v1/${path}`, {
+            ...init,
+            headers: {
+                "content-type": "application/json",
+                apikey: config.serviceRoleKey,
+                authorization: `Bearer ${config.serviceRoleKey}`,
+                ...(init.headers ?? {}),
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`proposals ${init.method ?? "GET"} ${path} → ${response.status} ` +
+                `${await response.text().catch(() => "")}`);
+        }
+        return response;
+    }
+    return {
+        async submitDrafts(drafts) {
+            if (drafts.length === 0)
+                return 0;
+            // Dedupe on the REAL unique index. 00013 made it tenant-first
+            // `(org_id, route, trigger_hash)` and DROPPED the old `(route, trigger_hash)`
+            // index — so the on_conflict target is ALWAYS the composite, in both lanes:
+            //  - hosted cron: org_id is stamped below;
+            //  - CLI/self-host: org_id is omitted and the row's house-org column DEFAULT
+            //    applies, and Postgres evaluates ON CONFLICT against the final row, so the
+            //    composite index still matches. Naming `(route, trigger_hash)` here — a
+            //    unique index that no longer exists — would 42P10 the CLI's own watch run.
+            const onConflict = "org_id,route,trigger_hash";
+            const response = await request(`proposals?on_conflict=${encodeURIComponent(onConflict)}`, {
+                method: "POST",
+                headers: { prefer: "resolution=ignore-duplicates,return=representation" },
+                body: JSON.stringify(drafts.map((d) => ({
+                    ...(config.orgId !== undefined ? { org_id: config.orgId } : {}),
+                    route: d.route,
+                    kind: d.kind,
+                    trigger: d.trigger,
+                    trigger_hash: d.triggerHash,
+                    status: "suggested",
+                    expires_at: d.expiresAt,
+                    // Analyst insights carry their summary as evidence at insert (E6
+                    // Chunk B). ignore-duplicates means a re-seen trigger_hash is a
+                    // no-op — an existing row's evidence is never clobbered.
+                    ...(d.evidence !== undefined ? { evidence: d.evidence } : {}),
+                }))),
+            });
+            const inserted = (await response.json().catch(() => []));
+            return Array.isArray(inserted) ? inserted.length : 0;
+        },
+        async list(orgId, status) {
+            const filter = status !== undefined ? `&status=eq.${status}` : "";
+            const scope = orgId !== null ? `&org_id=eq.${encodeURIComponent(orgId)}` : "";
+            const response = await request(`proposals?select=*${filter}${scope}&order=created_at.desc`, {
+                method: "GET",
+            });
+            return (await response.json()).map(toRecord);
+        },
+        async get(id) {
+            const response = await request(`proposals?select=*&id=eq.${encodeURIComponent(id)}`, {
+                method: "GET",
+            });
+            const rows = (await response.json());
+            return rows.length > 0 ? toRecord(rows[0]) : null;
+        },
+        async attachEvidence(id, evidence) {
+            // Status-scoped, like setStatus/decide: a terminal proposal matches zero
+            // rows, so attaching evidence can never flip an executed/rejected proposal
+            // back to `evidenced` (which would make it re-executable — a double-swap /
+            // audit-corruption path an oracle-act caller could otherwise reach on their
+            // own org's rows). org_id predicate is defense-in-depth on the scoped path.
+            const orgPredicate = config.orgId !== undefined ? `&org_id=eq.${encodeURIComponent(config.orgId)}` : "";
+            const response = await request(`proposals?id=eq.${encodeURIComponent(id)}` +
+                `&status=in.${encodeURIComponent("(suggested,evidenced)")}${orgPredicate}`, {
+                method: "PATCH",
+                headers: { prefer: "return=representation" },
+                body: JSON.stringify({
+                    status: "evidenced",
+                    evidence,
+                    updated_at: new Date().toISOString(),
+                }),
+            });
+            const rows = (await response.json().catch(() => []));
+            return Array.isArray(rows) && rows.length > 0;
+        },
+        async setStatus(id, from, to) {
+            assertTransition(from, to);
+            // Status-scoped PATCH: a concurrent transition means zero rows match —
+            // never a blind overwrite.
+            await request(`proposals?id=eq.${encodeURIComponent(id)}&status=eq.${from}`, {
+                method: "PATCH",
+                body: JSON.stringify({ status: to, updated_at: new Date().toISOString() }),
+            });
+        },
+        async orgOf(id) {
+            const response = await request(`proposals?select=org_id&id=eq.${encodeURIComponent(id)}`, {
+                method: "GET",
+            });
+            const rows = (await response.json());
+            return rows.length > 0 && typeof rows[0].org_id === "string" ? rows[0].org_id : null;
+        },
+        async decide(id, from, to, decidedBy, decidedByUserId, orgId) {
+            assertTransition(from, to);
+            const now = new Date().toISOString();
+            // Status-scoped, and asks for the row back so we can tell "decided" from
+            // "someone else already decided" rather than assuming success.
+            // org_id in the WHERE clause is defense in depth, not the primary check.
+            // The caller authorizes against this row's org before we get here; this
+            // makes a bypass of THAT check unable to cross a tenant boundary anyway,
+            // because the row simply will not match. A service-role write with no
+            // tenant predicate is how an authorization bug becomes a data breach.
+            const orgPredicate = orgId === undefined ? "" : `&org_id=eq.${encodeURIComponent(orgId)}`;
+            const response = await request(`proposals?id=eq.${encodeURIComponent(id)}&status=eq.${from}${orgPredicate}`, {
+                method: "PATCH",
+                headers: { prefer: "return=representation" },
+                body: JSON.stringify({
+                    status: to,
+                    approved_by: decidedBy,
+                    // P6 WS1 identity. `approved_by` stays the operator-TYPED display
+                    // name; `decided_by` is the verified identity. They are separate
+                    // columns on purpose — merging them would make the pre-identity
+                    // rows indistinguishable from the identity-bound ones, and half
+                    // the corpus would silently look more trustworthy than it is.
+                    // Undefined (self-host, no auth server) leaves the column null,
+                    // which is the honest record rather than a guess.
+                    ...(decidedByUserId !== undefined && decidedByUserId !== null
+                        ? { decided_by: decidedByUserId }
+                        : {}),
+                    decided_at: now,
+                    updated_at: now,
+                }),
+            });
+            const rows = (await response.json().catch(() => []));
+            return Array.isArray(rows) && rows.length > 0;
+        },
+        async expireOverdue(now) {
+            const cutoff = now.toISOString();
+            // Org-scoped when this client carries a tenant — one org's cron never
+            // sweeps another's rows (the sweep is idempotent, but touching a foreign
+            // tenant's proposals is the confused-deputy shape we refuse on principle).
+            const orgPredicate = config.orgId !== undefined ? `&org_id=eq.${encodeURIComponent(config.orgId)}` : "";
+            await request(`proposals?status=in.${encodeURIComponent("(suggested,evidenced)")}` +
+                `&expires_at=lt.${encodeURIComponent(cutoff)}${orgPredicate}`, {
+                method: "PATCH",
+                body: JSON.stringify({ status: "expired", updated_at: cutoff }),
+            });
+        },
+    };
+}

package/dist/watch/run-record.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Scheduled-job self-reporting — Phase 6.
+ *
+ * A4 gave the watch cron durable state. It did not give anyone a way to tell
+ * whether the cron RAN. `control_state` sat empty for a week and the three
+ * candidate explanations — never scheduled, running and failing, or running
+ * and finding nothing — were indistinguishable from outside. The only
+ * evidence lived in Render's log viewer, behind an API key that grants access
+ * to every workspace and every environment variable in the account.
+ *
+ * A job whose only proof of life is a vendor's log viewer is a job you cannot
+ * operate, and reaching for that key to read a log is a poor trade: it is the
+ * broadest possible credential borrowed for the narrowest possible question.
+ *
+ * So the job answers the question itself. One row, upserted each cycle, in the
+ * store we already own. "Did it run, when, and what did it do" becomes a
+ * SELECT — no vendor credential involved.
+ *
+ * Three properties matter more than the shape of the record:
+ *
+ * 1. **It records failures.** A report that only appears on success is
+ *    indistinguishable from no report, which is precisely the ambiguity that
+ *    made A4 unverifiable.
+ * 2. **It never throws.** Observability that can fail the thing it observes is
+ *    worse than none.
+ * 3. **It is a separate key from the state.** A run report must never be able
+ *    to corrupt the pricing snapshot it reports on.
+ */
+import { scrubSecrets } from "../tenancy/scrub";
+/** Key under which the last run report lives in `control_state`. */
+export declare const WATCH_RUN_KEY = "watch:last-run";
+export interface WatchRunRecord {
+    readonly outcome: "ok" | "failed";
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    /** True when this cycle had no previous state and only established a baseline. */
+    readonly seeded?: boolean;
+    readonly events?: number;
+    readonly drafts?: number;
+    readonly inserted?: number;
+    /** Which store backed this run — the A4 regression is a file-backed cron. */
+    readonly stateStore?: string;
+    readonly error?: string;
+}
+export interface RunRecordConfig {
+    readonly supabaseUrl: string;
+    readonly serviceRoleKey: string;
+    readonly fetchFn?: typeof fetch;
+}
+/**
+ * Re-exported from the shared scrubber (C2's leak gate). This module owned the
+ * original copy; WS3 promoted it to `tenancy/scrub.ts` and widened its prefix
+ * set to the BYOK provider families, so error text stored here is scrubbed by
+ * the same gate the vault and telemetry boundaries use.
+ */
+export { scrubSecrets };
+/**
+ * Write the run report. Best-effort by design — see property 2 above.
+ *
+ * Silent when no control plane is configured: a self-hosted rig with no
+ * Supabase has nowhere to write and nothing to prove to us.
+ */
+export declare function recordWatchRun(record: WatchRunRecord, config: RunRecordConfig): Promise<void>;
+//# sourceMappingURL=run-record.d.ts.map

package/dist/watch/run-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-record.d.ts","sourceRoot":"","sources":["../../src/watch/run-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,oEAAoE;AACpE,eAAO,MAAM,aAAa,mBAAmB,CAAC;AAE9C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,QAAQ,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,IAAI,CAAC,CA4Bf"}

package/dist/watch/run-record.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Scheduled-job self-reporting — Phase 6.
+ *
+ * A4 gave the watch cron durable state. It did not give anyone a way to tell
+ * whether the cron RAN. `control_state` sat empty for a week and the three
+ * candidate explanations — never scheduled, running and failing, or running
+ * and finding nothing — were indistinguishable from outside. The only
+ * evidence lived in Render's log viewer, behind an API key that grants access
+ * to every workspace and every environment variable in the account.
+ *
+ * A job whose only proof of life is a vendor's log viewer is a job you cannot
+ * operate, and reaching for that key to read a log is a poor trade: it is the
+ * broadest possible credential borrowed for the narrowest possible question.
+ *
+ * So the job answers the question itself. One row, upserted each cycle, in the
+ * store we already own. "Did it run, when, and what did it do" becomes a
+ * SELECT — no vendor credential involved.
+ *
+ * Three properties matter more than the shape of the record:
+ *
+ * 1. **It records failures.** A report that only appears on success is
+ *    indistinguishable from no report, which is precisely the ambiguity that
+ *    made A4 unverifiable.
+ * 2. **It never throws.** Observability that can fail the thing it observes is
+ *    worse than none.
+ * 3. **It is a separate key from the state.** A run report must never be able
+ *    to corrupt the pricing snapshot it reports on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scrubSecrets = exports.WATCH_RUN_KEY = void 0;
+exports.recordWatchRun = recordWatchRun;
+const scrub_1 = require("../tenancy/scrub");
+Object.defineProperty(exports, "scrubSecrets", { enumerable: true, get: function () { return scrub_1.scrubSecrets; } });
+/** Key under which the last run report lives in `control_state`. */
+exports.WATCH_RUN_KEY = "watch:last-run";
+/**
+ * Write the run report. Best-effort by design — see property 2 above.
+ *
+ * Silent when no control plane is configured: a self-hosted rig with no
+ * Supabase has nowhere to write and nothing to prove to us.
+ */
+async function recordWatchRun(record, config) {
+    const { supabaseUrl, serviceRoleKey } = config;
+    if (supabaseUrl === "" || serviceRoleKey === "")
+        return;
+    const fetchFn = config.fetchFn ?? fetch;
+    const safe = record.error === undefined ? record : { ...record, error: (0, scrub_1.scrubSecrets)(record.error) };
+    try {
+        const response = await fetchFn(`${supabaseUrl.replace(/\/$/, "")}/rest/v1/control_state?on_conflict=key`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                apikey: serviceRoleKey,
+                authorization: `Bearer ${serviceRoleKey}`,
+                prefer: "resolution=merge-duplicates,return=minimal",
+            },
+            body: JSON.stringify([
+                { key: exports.WATCH_RUN_KEY, value: safe, updated_at: new Date().toISOString() },
+            ]),
+        });
+        if (!response.ok)
+            warnReportFailed(`${response.status} ${await response.text().catch(() => "")}`);
+    }
+    catch (err) {
+        warnReportFailed(err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * Non-fatal, but never silent — A-C6.3, 2026-08-05.
+ *
+ * Property 2 above says this must not fail the cycle it observes, and that is
+ * still true. But the first version swallowed the outcome entirely, which
+ * recreated the very ambiguity this module exists to end one level up: a
+ * report that never lands looks exactly like a report that lands fine, and
+ * `watch:last-run` being absent would again have three explanations and no way
+ * to tell them apart.
+ *
+ * So: the cycle still succeeds, and the operator still finds out. The warning
+ * names the key so a reader who greps the cron log for it lands here.
+ */
+function warnReportFailed(detail) {
+    console.warn(`[modelrig watch] could not write the ${exports.WATCH_RUN_KEY} self-report (${(0, scrub_1.scrubSecrets)(detail)}). ` +
+        "The cycle itself is unaffected — but until this succeeds, `control_state` cannot tell you " +
+        "whether this job ran, so fall back to watch:pricing-universe.updated_at.");
+}

package/dist/watch/run-reported.d.ts

@@ -0,0 +1,20 @@
+/**
+ * One watch cycle, with a run report — Phase 6.
+ *
+ * Extracted from the CLI rather than written inline, for two reasons. The
+ * obvious one: `cli.ts` crossed the package's 700-LOC invariant and the test
+ * suite said so. The better one: reporting-on-failure is the half that
+ * matters, and a `catch` branch buried in a CLI command is a branch nobody
+ * exercises. Here it has a test.
+ *
+ * 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 Render's log viewer, behind an API key that grants the whole
+ * account. Now the job answers for itself, and answering costs no vendor
+ * credential.
+ */
+import { type RunRecordConfig } from "./run-record";
+import type { WatchCycleOptions, WatchCycleResult } from "./run";
+export declare function runWatchCycleReported(opts: WatchCycleOptions, report: RunRecordConfig, now?: () => string): Promise<WatchCycleResult>;
+//# sourceMappingURL=run-reported.d.ts.map

package/dist/watch/run-reported.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-reported.d.ts","sourceRoot":"","sources":["../../src/watch/run-reported.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAEjE,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,eAAe,EACvB,GAAG,GAAE,MAAM,MAAuC,GACjD,OAAO,CAAC,gBAAgB,CAAC,CAsC3B"}

package/dist/watch/run-reported.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * One watch cycle, with a run report — Phase 6.
+ *
+ * Extracted from the CLI rather than written inline, for two reasons. The
+ * obvious one: `cli.ts` crossed the package's 700-LOC invariant and the test
+ * suite said so. The better one: reporting-on-failure is the half that
+ * matters, and a `catch` branch buried in a CLI command is a branch nobody
+ * exercises. Here it has a test.
+ *
+ * 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 Render's log viewer, behind an API key that grants the whole
+ * account. Now the job answers for itself, and answering costs no vendor
+ * credential.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWatchCycleReported = runWatchCycleReported;
+const run_record_1 = require("./run-record");
+const run_1 = require("./run");
+async function runWatchCycleReported(opts, report, now = () => new Date().toISOString()) {
+    const startedAt = now();
+    const stateStore = opts.store?.description ?? "local file";
+    let result;
+    try {
+        result = await (0, run_1.runWatchCycle)(opts);
+    }
+    catch (err) {
+        // Report BEFORE rethrowing. A crashed cycle that leaves no trace is the
+        // exact state this module exists to end, and rethrowing still fails the
+        // cron so the platform's own alerting is unaffected.
+        await (0, run_record_1.recordWatchRun)({
+            outcome: "failed",
+            startedAt,
+            finishedAt: now(),
+            stateStore,
+            error: err instanceof Error ? err.message : String(err),
+        }, report);
+        throw err;
+    }
+    await (0, run_record_1.recordWatchRun)({
+        outcome: "ok",
+        startedAt,
+        finishedAt: now(),
+        seeded: result.seeded,
+        events: result.events,
+        drafts: result.drafts,
+        inserted: result.inserted,
+        stateStore,
+    }, report);
+    return result;
+}

package/dist/watch/run.d.ts

@@ -0,0 +1,73 @@
+/**
+ * One watch cycle — Phase 4 WS1 (`modelrig watch run`, cron-able):
+ *   1. diff the pricing universe against last-seen state (or take injected
+ *      fixture events — the test/demo path),
+ *   2. evaluate events into proposal drafts (pure),
+ *   3. sweep overdue proposals to expired,
+ *   4. submit drafts (idempotent on (route, trigger_hash)),
+ *   5. save state.
+ * The cycle itself spends $0 — paid evidence runs happen only through
+ * `bakeoff --from-proposal`, under the monthly watch budget.
+ */
+import type { RouteEconomics, WatchEvent } from "./evaluate";
+import type { ProposalsClient } from "./proposals";
+import type { PriceUniverse } from "./state";
+import type { WatchStateStore } from "./state-store";
+import type { CacheStatsRollup } from "../savings/cache-stats";
+import type { CachePredictionDrift, ReconcileOptions } from "../savings/cache-reconcile";
+import type { TelemetryRow } from "../types/telemetry";
+export interface WatchCycleOptions {
+    readonly routes: readonly RouteEconomics[];
+    /** Local-file state path — the self-host fallback. Ignored when `store`
+     * is supplied. One of `store` or `statePath` is required. */
+    readonly statePath?: string;
+    /** Durable state store (addendum A4). On an ephemeral cron container this
+     * MUST be the control-plane store: a file-backed one re-seeds every run,
+     * so no price move can ever fire an event. */
+    readonly store?: WatchStateStore;
+    readonly universe: PriceUniverse;
+    readonly client: ProposalsClient;
+    readonly thresholdPct: number;
+    /** Fixture events (acceptance criterion 2's injected path) — when set,
+     * the state diff is skipped and state is NOT advanced. */
+    readonly injectedEvents?: readonly WatchEvent[];
+    readonly now?: Date;
+}
+export interface WatchCycleResult {
+    readonly seeded: boolean;
+    readonly events: number;
+    readonly drafts: number;
+    readonly inserted: number;
+}
+export declare function runWatchCycle(opts: WatchCycleOptions): Promise<WatchCycleResult>;
+/**
+ * Predicted cache-read tokens for one (route, candidate) — the ledger/simulator
+ * estimate that a reconciliation cycle checks against observed ground truth.
+ * Keyed by (route, provider, model) to join to a rollup.
+ */
+export interface CacheReadPrediction {
+    readonly route: string;
+    readonly provider: string;
+    readonly model: string;
+    readonly predictedReadTokens: number;
+}
+export interface CacheReconciliationResult {
+    readonly rollups: readonly CacheStatsRollup[];
+    readonly drift: readonly CachePredictionDrift[];
+}
+/**
+ * The cache half of a watch cycle (cache-aware-routing spec §5.2, step 6):
+ * ROLL UP production cache stats from telemetry rows ONCE, then RECONCILE the
+ * ledger/simulator predictions against the observed reads, emitting
+ * `cache_prediction_drift` events (G-4 pattern). Pure over its inputs — the
+ * caller (a cron/CLI) supplies the window's rows and the predictions from the
+ * derived ledger/simulator. Deliberately SEPARATE from `runWatchCycle`: the
+ * price-move loop is untouched and byte-identical; this is an additive,
+ * independently-testable cache concern that a cron runs alongside it.
+ */
+export declare function runCacheReconciliation(rows: readonly TelemetryRow[], predictions: readonly CacheReadPrediction[], opts: {
+    now: number;
+    windowDays?: number;
+    reconcile?: ReconcileOptions;
+}): CacheReconciliationResult;
+//# sourceMappingURL=run.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/watch/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,KAAK,EACV,oBAAoB,EAEpB,gBAAgB,EACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C;iEAC6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;kDAE8C;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;8DAC0D;IAC1D,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAChD,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiCtF;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,WAAW,EAAE,SAAS,mBAAmB,EAAE,EAC3C,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,gBAAgB,CAAA;CAAE,GACvE,yBAAyB,CAyB3B"}

package/dist/watch/run.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * One watch cycle — Phase 4 WS1 (`modelrig watch run`, cron-able):
+ *   1. diff the pricing universe against last-seen state (or take injected
+ *      fixture events — the test/demo path),
+ *   2. evaluate events into proposal drafts (pure),
+ *   3. sweep overdue proposals to expired,
+ *   4. submit drafts (idempotent on (route, trigger_hash)),
+ *   5. save state.
+ * The cycle itself spends $0 — paid evidence runs happen only through
+ * `bakeoff --from-proposal`, under the monthly watch budget.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWatchCycle = runWatchCycle;
+exports.runCacheReconciliation = runCacheReconciliation;
+const evaluate_1 = require("./evaluate");
+const state_1 = require("./state");
+const state_store_1 = require("./state-store");
+const cache_stats_1 = require("../savings/cache-stats");
+const cache_reconcile_1 = require("../savings/cache-reconcile");
+async function runWatchCycle(opts) {
+    const now = opts.now ?? new Date();
+    const store = opts.store ??
+        (opts.statePath !== undefined
+            ? (0, state_store_1.createFileWatchStateStore)(opts.statePath)
+            : (() => {
+                throw new Error("runWatchCycle needs either a state store or a statePath");
+            })());
+    let events;
+    let seeded = false;
+    if (opts.injectedEvents !== undefined) {
+        events = opts.injectedEvents;
+    }
+    else {
+        const previous = await store.load();
+        seeded = previous === null;
+        events = (0, state_1.computeWatchEvents)(opts.universe, previous);
+    }
+    const drafts = (0, evaluate_1.evaluateEvents)(opts.routes, events, { thresholdPct: opts.thresholdPct });
+    // Expiry sweep first so a re-fired trigger never races its own stale row.
+    await opts.client.expireOverdue(now);
+    const inserted = drafts.length > 0 ? await opts.client.submitDrafts(drafts) : 0;
+    if (opts.injectedEvents === undefined) {
+        await store.save({ ...opts.universe });
+    }
+    return { seeded, events: events.length, drafts: drafts.length, inserted };
+}
+/**
+ * The cache half of a watch cycle (cache-aware-routing spec §5.2, step 6):
+ * ROLL UP production cache stats from telemetry rows ONCE, then RECONCILE the
+ * ledger/simulator predictions against the observed reads, emitting
+ * `cache_prediction_drift` events (G-4 pattern). Pure over its inputs — the
+ * caller (a cron/CLI) supplies the window's rows and the predictions from the
+ * derived ledger/simulator. Deliberately SEPARATE from `runWatchCycle`: the
+ * price-move loop is untouched and byte-identical; this is an additive,
+ * independently-testable cache concern that a cron runs alongside it.
+ */
+function runCacheReconciliation(rows, predictions, opts) {
+    const rollups = (0, cache_stats_1.rollupCacheStats)(rows, {
+        now: opts.now,
+        ...(opts.windowDays !== undefined ? { windowDays: opts.windowDays } : {}),
+    });
+    // Join predictions to their rollup (observed ground truth) by candidate key.
+    const byKey = new Map();
+    for (const r of rollups)
+        byKey.set(`${r.route}\n${r.provider}\n${r.model}`, r);
+    const samples = [];
+    for (const p of predictions) {
+        const rollup = byKey.get(`${p.route}\n${p.provider}\n${p.model}`);
+        if (rollup === undefined)
+            continue; // no observed traffic → nothing to reconcile
+        samples.push({
+            route: p.route,
+            provider: p.provider,
+            model: p.model,
+            predictedReadTokens: p.predictedReadTokens,
+            observedReadTokens: rollup.tokensCached,
+            windowInputTokens: rollup.tokensIn,
+            sampleN: rollup.sampleN,
+        });
+    }
+    return { rollups, drift: (0, cache_reconcile_1.reconcileCacheDrift)(samples, opts.reconcile) };
+}

package/dist/watch/state-store.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Watch-state persistence — Phase 5 addendum A4.
+ *
+ * The watch loop's pricing snapshot has to survive between runs, and the
+ * runs happen in an EPHEMERAL cron container. A local file cannot do that:
+ * every run reads nothing, re-seeds, and reports zero events — the cron was
+ * live and structurally incapable of ever firing a proposal.
+ *
+ * Two implementations behind one interface:
+ *  - control plane (default when Supabase is configured): a keyed row in
+ *    `control_state`. Survives the container.
+ *  - local file (the self-host / no-Supabase fallback): the Phase 4
+ *    behavior, kept because a single-machine user should not need a
+ *    control plane to run a watch cycle.
+ *
+ * A store that cannot load is NOT treated as "no previous state". Seeding on
+ * a transient read failure would re-baseline the universe and silently
+ * swallow every price move since the last successful run, which is exactly
+ * the bug this file exists to fix — so a failed read throws.
+ */
+import type { PriceUniverse } from "./state";
+/** Key under which the pricing universe lives in `control_state`. */
+export declare const WATCH_STATE_KEY = "watch:pricing-universe";
+export interface WatchStateStore {
+    /** Previous snapshot, or null when genuinely none has been stored yet. */
+    load(): Promise<PriceUniverse | null>;
+    save(universe: PriceUniverse): Promise<void>;
+    /** For the operator-facing log line: where this state actually lives. */
+    readonly description: string;
+}
+export declare function createFileWatchStateStore(path: string): WatchStateStore;
+export interface ControlPlaneStateConfig {
+    readonly supabaseUrl: string;
+    readonly serviceRoleKey: string;
+    readonly key?: string;
+    readonly fetchFn?: typeof fetch;
+}
+export declare function createControlPlaneWatchStateStore(config: ControlPlaneStateConfig): WatchStateStore;
+/** Pick the durable store when a control plane exists, else the local file. */
+export declare function createWatchStateStore(opts: {
+    readonly filePath: string;
+    readonly export?: {
+        readonly supabaseUrl: string;
+        readonly serviceRoleKey: string;
+    } | undefined;
+    readonly fetchFn?: typeof fetch;
+}): WatchStateStore;
+//# sourceMappingURL=state-store.d.ts.map

package/dist/watch/state-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../../src/watch/state-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,qEAAqE;AACrE,eAAO,MAAM,eAAe,2BAA2B,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,IAAI,IAAI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAQvE;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,uBAAuB,GAC9B,eAAe,CA+CjB;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAChG,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC,GAAG,eAAe,CAOlB"}