modelrig 0.0.1 → 0.2.0

package/dist/watch/evaluate.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROPOSAL_TTL_DAYS = void 0;
+exports.triggerHash = triggerHash;
+exports.evaluateEvents = evaluateEvents;
+exports.buildCacheContext = buildCacheContext;
+exports.explainCacheContext = explainCacheContext;
+const node_crypto_1 = require("node:crypto");
+const effective_rate_1 = require("../registry/effective-rate");
+exports.PROPOSAL_TTL_DAYS = 30;
+/** Reference token mix for blending input/output rates into one comparable
+ * number: 3 input tokens per output token — a conservative, route-agnostic
+ * default (schema-bound analysis routes run input-heavy). */
+const BLEND_IN = 3;
+const BLEND_OUT = 1;
+function blended(rates) {
+    return rates.inputUsdPerTok * BLEND_IN + rates.outputUsdPerTok * BLEND_OUT;
+}
+function triggerHash(route, trigger) {
+    return (0, node_crypto_1.createHash)("sha256").update(`${route}\n${JSON.stringify(trigger)}`).digest("hex").slice(0, 32);
+}
+function expiryStamp() {
+    return new Date(Date.now() + exports.PROPOSAL_TTL_DAYS * 24 * 3600 * 1000).toISOString();
+}
+function evaluateEvents(routes, events, config) {
+    const drafts = [];
+    for (const event of events) {
+        if (event.type === "price_change") {
+            const before = blended(event.old);
+            if (before <= 0)
+                continue; // nothing sane to compare against
+            const deltaPct = ((blended(event.new) - before) / before) * 100;
+            if (Math.abs(deltaPct) < config.thresholdPct)
+                continue;
+            const trigger = {
+                type: "price_change",
+                provider: event.provider,
+                model: event.model,
+                deltaPct,
+                oldRates: event.old,
+                newRates: event.new,
+            };
+            for (const route of routes) {
+                if (!route.candidates.some((c) => c.provider === event.provider && c.model === event.model)) {
+                    continue;
+                }
+                drafts.push({
+                    route: route.route,
+                    kind: "bakeoff",
+                    trigger,
+                    triggerHash: triggerHash(route.route, trigger),
+                    expiresAt: expiryStamp(),
+                });
+            }
+        }
+        else {
+            const trigger = {
+                type: "new_model",
+                provider: event.provider,
+                model: event.model,
+                pricing: event.pricing,
+            };
+            for (const route of routes) {
+                if (!route.candidates.some((c) => c.provider === event.provider))
+                    continue;
+                // A model the route already declares is not "new" for it.
+                if (route.candidates.some((c) => c.provider === event.provider && c.model === event.model)) {
+                    continue;
+                }
+                drafts.push({
+                    route: route.route,
+                    kind: "bakeoff",
+                    trigger,
+                    triggerHash: triggerHash(route.route, trigger),
+                    expiresAt: expiryStamp(),
+                });
+            }
+        }
+    }
+    return drafts;
+}
+const PER_MTOK = 1e6;
+/**
+ * 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.
+ */
+function buildCacheContext(input, config = effective_rate_1.DEFAULT_CACHE_HYSTERESIS) {
+    const incumbentEff = (0, effective_rate_1.effectiveInputRate)(input.observed, input.incumbentRates);
+    const challengerCold = input.challengerRates.input;
+    // Switch cost of leaving the warm incumbent for the cold challenger, and the
+    // per-call saving the incumbent's warmth is worth (spec §4.2–4.3).
+    const switch_cost_usd = (0, effective_rate_1.switchCostUsd)(input.incumbentPrefixTokens, input.challengerRates, input.incumbentRates);
+    const perCallSaving = (0, effective_rate_1.perCallCacheSavingsUsd)(input.incumbentPrefixTokens, input.observed.h, input.incumbentRates);
+    const cache_option_value_usd = (0, effective_rate_1.cacheOptionValueUsd)(input.remainingCalls, perCallSaving);
+    const breakeven_conformant_calls = (0, effective_rate_1.breakevenCalls)(switch_cost_usd, perCallSaving);
+    // The cache-adjusted per-call advantage of the challenger over the incumbent,
+    // on the cached prefix: (incumbent effective − challenger cold) per prefix
+    // token, times the prefix. Positive ⇒ the cold challenger is still cheaper.
+    const perCallAdvantageUsd = (incumbentEff - challengerCold) * input.incumbentPrefixTokens;
+    const totalAdvantageUsd = perCallAdvantageUsd * Math.max(input.remainingCalls, 0);
+    const verdict = (0, effective_rate_1.classifyCacheVerdict)({
+        hasCacheSignal: input.hasCacheSignal,
+        perCallAdvantageUsd,
+        totalAdvantageUsd,
+        windowSpendUsd: input.windowSpendUsd,
+    }, config);
+    return {
+        observed_hit_rate: input.observed.h,
+        observed_write_rate: input.observed.w,
+        window_days: input.windowDays,
+        incumbent_effective_in_per_mtok: incumbentEff * PER_MTOK,
+        challenger_cold_in_per_mtok: challengerCold * PER_MTOK,
+        switch_cost_usd,
+        cache_option_value_usd,
+        breakeven_conformant_calls,
+        verdict,
+    };
+}
+/**
+ * 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.
+ */
+function explainCacheContext(ctx, incumbentLabel, challengerLabel) {
+    const warmMtok = ctx.incumbent_effective_in_per_mtok.toFixed(2);
+    const coldMtok = ctx.challenger_cold_in_per_mtok.toFixed(2);
+    const hit = `${(ctx.observed_hit_rate * 100).toFixed(0)}%`;
+    const breakeven = Number.isFinite(ctx.breakeven_conformant_calls)
+        ? `breaks even after ${Math.ceil(ctx.breakeven_conformant_calls)} calls`
+        : "never breaks even";
+    return (`${incumbentLabel} is warm (${hit} hit rate, effective $${warmMtok}/Mtok in); ` +
+        `${challengerLabel} is nominally cheaper but cold ($${coldMtok}/Mtok in). ` +
+        `Switching costs $${ctx.switch_cost_usd.toFixed(4)} and ${breakeven}. ` +
+        `Verdict: ${ctx.verdict}.`);
+}

package/dist/watch/monitor.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Monitor v1 — conform-rate degradation → bake-off proposal (Expansion E4 chunk B).
+ *
+ * The watch loop reacts to PRICE moves; the Monitor reacts to QUALITY moves. It
+ * rolls up the deterministic-eval conform rate per (org, task) into a daily
+ * series, and when a recent window falls below the trailing baseline by a ruled
+ * margin — with enough evaluations on BOTH sides to trust the number — it emits
+ * ONE `proposals` row (kind='bakeoff') asking for a re-evaluation. It reuses the
+ * ENTIRE existing proposals machinery: same table, same kind, same
+ * (route, trigger_hash) idempotency, same human-approval gate. No new proposal
+ * kind, no auto-actuation — the swap gate is untouched (spec §3.2).
+ *
+ * ── MEASURED-ONLY DOCTRINE ────────────────────────────────────────────────
+ * A degradation is proposed only from DETERMINISTIC evaluations (evaluator_kind
+ * = 'deterministic' — no model-judge softness), and only when BOTH windows clear
+ * `MONITOR_MIN_N`. Below that the rate is too noisy to act on: two failures can
+ * swing a small sample past the margin, and the house rule is to refuse rather
+ * than propose on thin data.
+ */
+import type { ProposalDraft } from "./evaluate";
+/** The recent window whose conformance we judge. A week smooths daily noise
+ * while staying responsive to a regression that just landed. */
+export declare const MONITOR_WINDOW_DAYS = 7;
+/** The trailing baseline the window is compared against — the 28 days
+ * immediately BEFORE the window (non-overlapping). Four weeks is a stable
+ * reference that predates a week-old regression; it matches the proposal TTL
+ * cadence, so a baseline never silently includes an unresolved degradation. */
+export declare const MONITOR_BASELINE_DAYS = 28;
+/** The drop, in percentage POINTS of conform rate, that flags a degradation.
+ * Mirrors the watch loop's ±10% material-shift threshold — one house number for
+ * "materially worse" — so the two loops speak the same language. */
+export declare const MONITOR_MARGIN_PTS = 10;
+/** Minimum deterministic evaluations required in EACH window before the rate is
+ * trustworthy enough to propose on (measured-only). */
+export declare const MONITOR_MIN_N = 20;
+export interface MonitorConfig {
+    readonly windowDays: number;
+    readonly baselineDays: number;
+    readonly marginPts: number;
+    readonly minN: number;
+}
+export declare const DEFAULT_MONITOR_CONFIG: MonitorConfig;
+/** One day's deterministic-eval counts for a task. `conformN` ≤ `n`. */
+export interface ConformDay {
+    readonly date: string;
+    readonly n: number;
+    readonly conformN: number;
+}
+export interface TaskConformSeries {
+    readonly task: string;
+    readonly days: readonly ConformDay[];
+}
+/** A single deterministic evaluation row for the rollup (server read shape). */
+export interface EvalRollupRow {
+    readonly artifactId: string;
+    readonly passed: boolean | null;
+    readonly createdAt: string;
+}
+/**
+ * Roll deterministic-eval rows up into per-(task) daily conform counts. The
+ * task comes from `taskByArtifact` (the caller joins artifacts→task locally,
+ * since artifact_evaluations carries only artifact_id). Rows whose artifact has
+ * no known task, or whose `passed` is null (not a pass/fail eval), are dropped.
+ */
+export declare function rollupConformRate(rows: readonly EvalRollupRow[], taskByArtifact: ReadonlyMap<string, string>): TaskConformSeries[];
+/**
+ * The degradation rule (measured-only). For each task, compare the recent
+ * window to the trailing baseline; emit a bake-off draft when the drop clears
+ * the margin AND both windows clear min-n. Deterministic over `now` (passed in,
+ * never read from the clock) so the fixture test is reproducible. The
+ * trigger_hash keys on the task + both window bounds, so re-running the SAME
+ * day is a no-op (the (route, trigger_hash) unique index dedupes it).
+ */
+export declare function evaluateConformDegradation(series: readonly TaskConformSeries[], now: Date, config?: MonitorConfig): ProposalDraft[];
+/**
+ * The reads a Monitor cycle needs, injected so the orchestrator is testable
+ * without a database. BOTH must be scoped to ONE org (the rollup groups by task
+ * within that scope — cross-org tasks sharing a name must never merge): a
+ * hosted cron iterates orgs, a self-host has exactly one.
+ */
+export interface MonitorReads {
+    /** Deterministic artifact evaluations created at/after `sinceIso`. */
+    readonly recentDeterministicEvals: (sinceIso: string) => Promise<readonly EvalRollupRow[]>;
+    /** task for each of the given artifact ids (the rollup join — artifact_evaluations
+     * carries only artifact_id). Only the ids that actually have evals are asked
+     * for, so the read stays bounded regardless of total artifact count. */
+    readonly taskFor: (artifactIds: readonly string[]) => Promise<ReadonlyMap<string, string>>;
+}
+export interface MonitorCycleResult {
+    readonly series: TaskConformSeries[];
+    readonly drafts: ProposalDraft[];
+    /** How many proposals the control plane actually created (0 when duplicates). */
+    readonly inserted: number;
+}
+/**
+ * One Monitor cycle: read the recent deterministic evals + task map, roll up,
+ * apply the degradation rule, and submit any drafts through the EXISTING
+ * proposals client (idempotent on (route, trigger_hash)). Returns the series +
+ * drafts + inserted count so a caller/CLI can report without a second query.
+ * Never actuates — submitting a proposal is the whole of its authority (§3.2).
+ */
+export declare function runMonitorCycle(reads: MonitorReads, submitDrafts: (drafts: readonly ProposalDraft[]) => Promise<number>, now: Date, config?: MonitorConfig): Promise<MonitorCycleResult>;
+export interface MonitorReadsConfig {
+    readonly supabaseUrl: string;
+    readonly serviceRoleKey: string;
+    /** The org this cycle runs for — reads are org-scoped so tasks never merge
+     * across tenants. A hosted cron iterates orgs; a self-host has exactly one. */
+    readonly orgId: string;
+    readonly fetchFn?: typeof fetch;
+}
+/** PostgREST reads for a Monitor cycle (service role; mirrors the proposals
+ * client). Two org-scoped queries, joined in-SDK by `runMonitorCycle` — no DDL,
+ * no view (spec §3.1). `taskFor` batches ids ≤100 (T9 — PostgREST URLs fail
+ * silently around 8KB). */
+export declare function createMonitorReads(config: MonitorReadsConfig): MonitorReads;
+//# sourceMappingURL=monitor.d.ts.map

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

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

package/dist/watch/monitor.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * Monitor v1 — conform-rate degradation → bake-off proposal (Expansion E4 chunk B).
+ *
+ * The watch loop reacts to PRICE moves; the Monitor reacts to QUALITY moves. It
+ * rolls up the deterministic-eval conform rate per (org, task) into a daily
+ * series, and when a recent window falls below the trailing baseline by a ruled
+ * margin — with enough evaluations on BOTH sides to trust the number — it emits
+ * ONE `proposals` row (kind='bakeoff') asking for a re-evaluation. It reuses the
+ * ENTIRE existing proposals machinery: same table, same kind, same
+ * (route, trigger_hash) idempotency, same human-approval gate. No new proposal
+ * kind, no auto-actuation — the swap gate is untouched (spec §3.2).
+ *
+ * ── MEASURED-ONLY DOCTRINE ────────────────────────────────────────────────
+ * A degradation is proposed only from DETERMINISTIC evaluations (evaluator_kind
+ * = 'deterministic' — no model-judge softness), and only when BOTH windows clear
+ * `MONITOR_MIN_N`. Below that the rate is too noisy to act on: two failures can
+ * swing a small sample past the margin, and the house rule is to refuse rather
+ * than propose on thin data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MONITOR_CONFIG = exports.MONITOR_MIN_N = exports.MONITOR_MARGIN_PTS = exports.MONITOR_BASELINE_DAYS = exports.MONITOR_WINDOW_DAYS = void 0;
+exports.rollupConformRate = rollupConformRate;
+exports.evaluateConformDegradation = evaluateConformDegradation;
+exports.runMonitorCycle = runMonitorCycle;
+exports.createMonitorReads = createMonitorReads;
+const evaluate_1 = require("./evaluate");
+/** The recent window whose conformance we judge. A week smooths daily noise
+ * while staying responsive to a regression that just landed. */
+exports.MONITOR_WINDOW_DAYS = 7;
+/** The trailing baseline the window is compared against — the 28 days
+ * immediately BEFORE the window (non-overlapping). Four weeks is a stable
+ * reference that predates a week-old regression; it matches the proposal TTL
+ * cadence, so a baseline never silently includes an unresolved degradation. */
+exports.MONITOR_BASELINE_DAYS = 28;
+/** The drop, in percentage POINTS of conform rate, that flags a degradation.
+ * Mirrors the watch loop's ±10% material-shift threshold — one house number for
+ * "materially worse" — so the two loops speak the same language. */
+exports.MONITOR_MARGIN_PTS = 10;
+/** Minimum deterministic evaluations required in EACH window before the rate is
+ * trustworthy enough to propose on (measured-only). */
+exports.MONITOR_MIN_N = 20;
+exports.DEFAULT_MONITOR_CONFIG = {
+    windowDays: exports.MONITOR_WINDOW_DAYS,
+    baselineDays: exports.MONITOR_BASELINE_DAYS,
+    marginPts: exports.MONITOR_MARGIN_PTS,
+    minN: exports.MONITOR_MIN_N,
+};
+/** ISO day (YYYY-MM-DD) of a timestamp. */
+function dayOf(iso) {
+    return iso.slice(0, 10);
+}
+/** N days before `d`, as a YYYY-MM-DD day string. */
+function dayMinus(d, days) {
+    return new Date(d.getTime() - days * 86400000).toISOString().slice(0, 10);
+}
+/**
+ * Roll deterministic-eval rows up into per-(task) daily conform counts. The
+ * task comes from `taskByArtifact` (the caller joins artifacts→task locally,
+ * since artifact_evaluations carries only artifact_id). Rows whose artifact has
+ * no known task, or whose `passed` is null (not a pass/fail eval), are dropped.
+ */
+function rollupConformRate(rows, taskByArtifact) {
+    // task → day → {n, conformN}
+    const byTask = new Map();
+    for (const r of rows) {
+        if (r.passed === null)
+            continue;
+        const task = taskByArtifact.get(r.artifactId);
+        if (task === undefined)
+            continue;
+        const day = dayOf(r.createdAt);
+        let days = byTask.get(task);
+        if (days === undefined) {
+            days = new Map();
+            byTask.set(task, days);
+        }
+        const cell = days.get(day) ?? { n: 0, conformN: 0 };
+        cell.n += 1;
+        if (r.passed)
+            cell.conformN += 1;
+        days.set(day, cell);
+    }
+    return [...byTask.entries()]
+        .map(([task, days]) => ({
+        task,
+        days: [...days.entries()]
+            .map(([date, c]) => ({ date, n: c.n, conformN: c.conformN }))
+            .sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0)),
+    }))
+        .sort((a, b) => (a.task < b.task ? -1 : a.task > b.task ? 1 : 0));
+}
+/** Aggregate the days whose date is in [from, to) into one window. */
+function windowOf(days, from, to) {
+    let n = 0;
+    let conformN = 0;
+    for (const d of days) {
+        if (d.date >= from && d.date < to) {
+            n += d.n;
+            conformN += d.conformN;
+        }
+    }
+    return { from, to, n, conformRate: n > 0 ? conformN / n : 0 };
+}
+/**
+ * The degradation rule (measured-only). For each task, compare the recent
+ * window to the trailing baseline; emit a bake-off draft when the drop clears
+ * the margin AND both windows clear min-n. Deterministic over `now` (passed in,
+ * never read from the clock) so the fixture test is reproducible. The
+ * trigger_hash keys on the task + both window bounds, so re-running the SAME
+ * day is a no-op (the (route, trigger_hash) unique index dedupes it).
+ */
+function evaluateConformDegradation(series, now, config = exports.DEFAULT_MONITOR_CONFIG) {
+    const windowFrom = dayMinus(now, config.windowDays);
+    const windowTo = dayMinus(now, 0);
+    const baselineFrom = dayMinus(now, config.windowDays + config.baselineDays);
+    const baselineTo = windowFrom;
+    const expiresAt = new Date(now.getTime() + evaluate_1.PROPOSAL_TTL_DAYS * 86400000).toISOString();
+    const drafts = [];
+    for (const s of series) {
+        const window = windowOf(s.days, windowFrom, windowTo);
+        const baseline = windowOf(s.days, baselineFrom, baselineTo);
+        if (window.n < config.minN || baseline.n < config.minN)
+            continue; // thin data → refuse
+        const dropPts = (baseline.conformRate - window.conformRate) * 100;
+        if (dropPts < config.marginPts)
+            continue; // not materially worse
+        const trigger = {
+            type: "conform_degradation",
+            task: s.task,
+            window,
+            baseline,
+            dropPts,
+            marginPts: config.marginPts,
+            minN: config.minN,
+        };
+        drafts.push({
+            route: s.task,
+            kind: "bakeoff",
+            trigger,
+            triggerHash: (0, evaluate_1.triggerHash)(s.task, trigger),
+            expiresAt,
+        });
+    }
+    return drafts;
+}
+/**
+ * One Monitor cycle: read the recent deterministic evals + task map, roll up,
+ * apply the degradation rule, and submit any drafts through the EXISTING
+ * proposals client (idempotent on (route, trigger_hash)). Returns the series +
+ * drafts + inserted count so a caller/CLI can report without a second query.
+ * Never actuates — submitting a proposal is the whole of its authority (§3.2).
+ */
+async function runMonitorCycle(reads, submitDrafts, now, config = exports.DEFAULT_MONITOR_CONFIG) {
+    const sinceMs = now.getTime() - (config.windowDays + config.baselineDays) * 86400000;
+    const sinceIso = new Date(sinceMs).toISOString();
+    const rows = await reads.recentDeterministicEvals(sinceIso);
+    const ids = [...new Set(rows.map((r) => r.artifactId))];
+    const tasks = ids.length > 0 ? await reads.taskFor(ids) : new Map();
+    const series = rollupConformRate(rows, tasks);
+    const drafts = evaluateConformDegradation(series, now, config);
+    const inserted = drafts.length > 0 ? await submitDrafts(drafts) : 0;
+    return { series, drafts, inserted };
+}
+/** PostgREST reads for a Monitor cycle (service role; mirrors the proposals
+ * client). Two org-scoped queries, joined in-SDK by `runMonitorCycle` — no DDL,
+ * no view (spec §3.1). `taskFor` batches ids ≤100 (T9 — PostgREST URLs fail
+ * silently around 8KB). */
+function createMonitorReads(config) {
+    const base = config.supabaseUrl.replace(/\/$/, "");
+    const fetchFn = config.fetchFn ?? fetch;
+    const org = encodeURIComponent(config.orgId);
+    async function get(path) {
+        const res = await fetchFn(`${base}/rest/v1/${path}`, {
+            headers: { apikey: config.serviceRoleKey, authorization: `Bearer ${config.serviceRoleKey}` },
+        });
+        if (!res.ok)
+            throw new Error(`monitor read ${path} → ${res.status} ${await res.text().catch(() => "")}`);
+        return (await res.json().catch(() => []));
+    }
+    return {
+        async recentDeterministicEvals(sinceIso) {
+            const rows = await get(`artifact_evaluations?select=artifact_id,passed,created_at&org_id=eq.${org}` +
+                `&evaluator_kind=eq.deterministic&created_at=gte.${encodeURIComponent(sinceIso)}`);
+            return rows.map((r) => ({ artifactId: r.artifact_id, passed: r.passed, createdAt: r.created_at }));
+        },
+        async taskFor(artifactIds) {
+            const out = new Map();
+            for (let i = 0; i < artifactIds.length; i += 100) {
+                const batch = artifactIds.slice(i, i + 100).map(encodeURIComponent).join(",");
+                const rows = await get(`artifacts?select=id,task&org_id=eq.${org}&id=in.(${batch})`);
+                for (const r of rows)
+                    if (r.task !== null)
+                        out.set(r.id, r.task);
+            }
+            return out;
+        },
+    };
+}

package/dist/watch/proposals.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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).
+ */
+import type { ProposalDraft, ProposalKind, ProposalTrigger } from "./evaluate";
+export type ProposalStatus = "suggested" | "evidenced" | "approved" | "rejected" | "executed" | "expired";
+export declare function assertTransition(from: ProposalStatus, to: ProposalStatus): void;
+export interface ProposalRecord {
+    readonly id: string;
+    readonly route: string;
+    readonly kind: ProposalKind;
+    readonly trigger: ProposalTrigger;
+    readonly triggerHash: string;
+    readonly evidence: Record<string, unknown> | null;
+    readonly status: ProposalStatus;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly expiresAt: string;
+    /** Who approved or rejected (A1.2). Null while undecided. */
+    readonly approvedBy: string | null;
+    /** When the decision was recorded — NOT when a swap executed. */
+    readonly decidedAt: string | null;
+}
+export interface ProposalsClientConfig {
+    readonly supabaseUrl: string;
+    readonly serviceRoleKey: string;
+    /**
+     * The tenant this client writes for. When set (the multi-tenant hosted cron —
+     * managed-loop §2), `submitDrafts` STAMPS every row with this org and dedupes
+     * against the real `(org_id, route, trigger_hash)` unique index, and
+     * `expireOverdue` sweeps only THIS org's rows. When omitted (the CLI /
+     * self-host lane) behaviour is unchanged: `org_id` falls to its house-org
+     * column default and one deployment sweeps its own single tenant. Omitting it
+     * on a hosted cron would file every org's proposals under the house org — the
+     * whole reason this field exists. Reads keyed by id (`get`/`orgOf`/`decide`)
+     * are org-agnostic and unaffected; `list` already takes its org as a param.
+     */
+    readonly orgId?: string;
+    readonly fetchFn?: typeof fetch;
+}
+export interface ProposalsClient {
+    /** Insert drafts; duplicates on (route, trigger_hash) are silent no-ops.
+     * Returns how many rows the control plane actually created. */
+    submitDrafts(drafts: readonly ProposalDraft[]): Promise<number>;
+    /**
+     * List proposals for ONE org, or across all of them.
+     *
+     * `orgId` is required and `null` is the explicit "every org" case, used by
+     * the CLI and by self-host deployments where there is exactly one. An
+     * OPTIONAL parameter would have been the same code with a worse failure
+     * mode: the unscoped read this replaces was unscoped because nobody passed
+     * anything, and an omitted argument reads as an oversight while an explicit
+     * null reads as a decision (C6 review ruling §7.2).
+     */
+    list(orgId: string | null, status?: ProposalStatus): Promise<ProposalRecord[]>;
+    get(id: string): Promise<ProposalRecord | null>;
+    /** Bake-off evidence + the suggested→evidenced flip, one status-scoped PATCH.
+     * Only a proposal still OPEN to evidence (suggested, or evidenced being
+     * re-run) matches — a terminal proposal (approved/executed/rejected/expired)
+     * matches zero rows, so evidence can never resurrect it. Returns false when
+     * nothing matched (already moved on), like `decide`. */
+    attachEvidence(id: string, evidence: Record<string, unknown>): Promise<boolean>;
+    /** Validated status change (assertTransition is the caller's guard for
+     * reads-before-writes; the PATCH is still status-scoped server-side). */
+    setStatus(id: string, from: ProposalStatus, to: ProposalStatus): Promise<void>;
+    /** A HUMAN decision on a proposal — addendum A1.2. Records who decided and
+     * when alongside the status flip, in one status-scoped PATCH.
+     *
+     * Approving is NOT executing: this writes a decision, never a swap_event.
+     * The swap still happens at a CLI (`modelrig swap execute --approve`) and
+     * the YAML it emits is still applied by git. Returns false when the row had
+     * already moved on (a concurrent decision), so the caller can say so
+     * instead of reporting a success that did not happen. */
+    /** The org that owns this proposal — the tenant a write must be authorized against. */
+    orgOf(id: string): Promise<string | null>;
+    decide(id: string, from: ProposalStatus, to: "approved" | "rejected", decidedBy: string, decidedByUserId?: string | null, orgId?: string): Promise<boolean>;
+    /** One sweep: overdue suggested/evidenced → expired. */
+    expireOverdue(now: Date): Promise<void>;
+}
+export declare function createProposalsClient(config: ProposalsClientConfig): ProposalsClient;
+//# sourceMappingURL=proposals.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"proposals.d.ts","sourceRoot":"","sources":["../../src/watch/proposals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE/E,MAAM,MAAM,cAAc,GACtB,WAAW,GACX,WAAW,GACX,UAAU,GACV,UAAU,GACV,UAAU,GACV,SAAS,CAAC;AAWd,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAO/E;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAkCD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B;mEAC+D;IAC/D,YAAY,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE;;;;;;;;;OASG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAC/E,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAChD;;;;4DAIwD;IACxD,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChF;6EACyE;IACzE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E;;;;;;;6DAOyD;IACzD,uFAAuF;IACvF,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1C,MAAM,CACJ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,cAAc,EACpB,EAAE,EAAE,UAAU,GAAG,UAAU,EAC3B,SAAS,EAAE,MAAM,EACjB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,EAC/B,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,wDAAwD;IACxD,aAAa,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAuLpF"}