modelrig 0.0.1 → 0.1.0

package/dist/types/provider.d.ts

@@ -0,0 +1,79 @@
+/**
+ * ProviderAdapter contract + the candidate-set invariant's type machinery.
+ * Spec §4. The invariant is structural: AdapterRequest carries a CandidateRef,
+ * and CandidateRef is a branded type constructible ONLY in run/resolve.ts.
+ */
+import type { RigFailure } from "./failures";
+export type ProviderId = "gemini" | "openai" | "deepseek" | "anthropic" | "grok" | "deepinfra" | "fireworks";
+export type CapabilityFlag = "structured_native" | "json_mode" | "grounded_native" | "context_cache_explicit" | "prompt_cache_key" | "prefix_cache_implicit" | "tier_flex" | "trace_visible";
+/** The canonical flag enumeration — the single list every static capability
+ * materialization iterates (index.ts, template validation, tests). */
+export declare const ALL_CAPABILITY_FLAGS: readonly CapabilityFlag[];
+declare const candidateBrand: unique symbol;
+/**
+ * A (provider, model) pair validated against a route's candidate list.
+ * DO NOT construct outside run/resolve.ts — no `as CandidateRef` anywhere
+ * (CI greps for it; see candidate-set-invariant.test.ts).
+ */
+export interface CandidateRef {
+    readonly provider: ProviderId;
+    readonly model: string;
+    readonly [candidateBrand]: true;
+}
+export type ServiceTier = "standard" | "flex" | "priority";
+export interface AdapterRequest {
+    readonly candidate: CandidateRef;
+    readonly systemPrompt: string;
+    readonly userPrompt: string;
+    /** JSON Schema for native structured output; null => prompt/json_mode path. */
+    readonly outputSchema: object | null;
+    readonly requestedTier: ServiceTier;
+    readonly timeoutMs: number;
+    /** Provider-neutral cache directive; adapters map to native mechanisms. */
+    readonly cache?: {
+        key: string;
+        ttlSeconds?: number;
+    };
+    /**
+     * Provider-native web-grounding directive (set by the run loop when the
+     * route requires "grounded"). BUILDER ADDITION pending architect sign-off:
+     * the scaffold's gemini adapter notes grounding is "driven by a
+     * cache/grounding directive on AdapterRequest", but the scaffolded type
+     * carried only `cache` — this optional field fills that gap additively.
+     */
+    readonly grounding?: boolean;
+    readonly maxOutputTokens?: number;
+}
+export interface AdapterUsage {
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly tokensCached: number;
+    readonly servedTier: ServiceTier;
+    /** Time to first body byte, ms (Phase 4 WS3 — headers lie on inference
+     * servers; TTFB is the honest slowness signal). Streaming adapters stamp
+     * first-chunk arrival; non-streaming calls equal total latency (the first
+     * byte genuinely arrives with the body). Optional: absent on failures
+     * where nothing arrived. */
+    readonly ttfbMs?: number;
+}
+export type AdapterResult = {
+    readonly ok: true;
+    readonly text: string;
+    readonly usage: AdapterUsage;
+}
+/** F1 (C1 finding, closed Phase 3 step 0): failures that still BILLED
+ * tokens (refusals, truncations, post-stream rejections) carry `usage` so
+ * envelopes, telemetry, and bake-off cost math see the spend. Absent when
+ * the provider billed nothing (transport errors, pre-dispatch rejections). */
+ | {
+    readonly ok: false;
+    readonly failure: RigFailure;
+    readonly usage?: AdapterUsage;
+};
+export interface ProviderAdapter {
+    readonly id: ProviderId;
+    supports(feature: CapabilityFlag, model: string): boolean;
+    call(req: AdapterRequest): Promise<AdapterResult>;
+}
+export {};
+//# sourceMappingURL=provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/types/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,WAAW,GACX,MAAM,GAGN,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,MAAM,cAAc,GACtB,mBAAmB,GACnB,WAAW,GACX,iBAAiB,GACjB,wBAAwB,GACxB,kBAAkB,GAClB,uBAAuB,GACvB,WAAW,GACX,eAAe,CAAC;AAEpB;sEACsE;AACtE,eAAO,MAAM,oBAAoB,EAAE,SAAS,cAAc,EASzD,CAAC;AAEF,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;CACjC;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;IACjC;;;;gCAI4B;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;CAAE;AAC5E;;;8EAG8E;GAC5E;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAA;CAAE,CAAC;AAExF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1D,IAAI,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACnD"}

package/dist/types/provider.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * ProviderAdapter contract + the candidate-set invariant's type machinery.
+ * Spec §4. The invariant is structural: AdapterRequest carries a CandidateRef,
+ * and CandidateRef is a branded type constructible ONLY in run/resolve.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_CAPABILITY_FLAGS = void 0;
+/** The canonical flag enumeration — the single list every static capability
+ * materialization iterates (index.ts, template validation, tests). */
+exports.ALL_CAPABILITY_FLAGS = [
+    "structured_native",
+    "json_mode",
+    "grounded_native",
+    "context_cache_explicit",
+    "prompt_cache_key",
+    "prefix_cache_implicit",
+    "tier_flex",
+    "trace_visible",
+];

package/dist/types/route.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Route bundle contract — spec §3. Loaded from modelrig/routes/*.yaml by
+ * routes/loader.ts; frozen after load.
+ */
+import type { FailureClass } from "./failures";
+import type { ProviderId, ServiceTier } from "./provider";
+export interface CandidateSpec {
+    readonly provider: ProviderId;
+    readonly model: string;
+}
+export type Requirement = "schema_conformant" | "grounded" | "zero_retention" | "trace_visible";
+export type Preference = "cost" | "latency";
+export interface RoutePolicy {
+    /** Per-class retry budgets — non-fungible. Missing class => 0 retries. */
+    readonly retries: Partial<Record<FailureClass, number>>;
+    readonly timeoutMs: number;
+    readonly tier: ServiceTier;
+    readonly json: "native" | "json_mode";
+}
+/** Repair rung config (Phase 3 WS2, ladder rung 4). */
+export interface RepairPolicy {
+    /** Total repair attempts on a schema-invalid output: attempt 1 re-asks the
+     * SAME model with the ajv error summary; attempt 2 (when maxRepairs ≥ 2 and
+     * repairModel is set) hands {invalid output, errors, schema} to the
+     * designated repair model. */
+    readonly maxRepairs: number;
+    /** Designated cheap repair model — must be one of the route's declared
+     * candidates (candidate-set invariant holds through repair). */
+    readonly repairModel?: CandidateSpec;
+}
+/** A named route variant (Phase 3 WS1, bundle format v2 — additive).
+ * Every field optional; an absent field inherits the route's base config. */
+export interface RouteVariant {
+    readonly name: string;
+    /** Candidate narrowing — MUST be a subset of the route's declared
+     * candidates (loader-enforced; the candidate-set invariant is unbreachable
+     * via variants). */
+    readonly candidates?: readonly CandidateSpec[];
+    /** Replaces the system template entirely (rendered with the same variables
+     * and capability conditionals). Mutually exclusive with promptAppend. */
+    readonly promptOverride?: string;
+    /** Appended to the rendered system prompt (after capability conditionals,
+     * before json coaching). */
+    readonly promptAppend?: string;
+    /** Reasoning scaffold (thinking directives; manual authoring this phase) —
+     * appended after promptAppend, before json coaching. */
+    readonly scaffold?: string;
+    /** JSON rung override for this variant. */
+    readonly json?: "native" | "json_mode";
+    readonly repair?: RepairPolicy;
+}
+export interface RouteBundle {
+    readonly route: string;
+    readonly version: number;
+    /** Resolved, parsed JSON Schema (null = unstructured route). */
+    readonly outputSchema: object | null;
+    readonly candidates: readonly CandidateSpec[];
+    readonly require: readonly Requirement[];
+    readonly prefer: readonly Preference[];
+    /** Raw template text with {{var}} and {{#if capability.X}} blocks. */
+    readonly systemTemplate: string;
+    readonly variables: readonly string[];
+    readonly policy: RoutePolicy;
+    /** Base-config repair rung (Phase 3 WS2) — variants may override. */
+    readonly repair?: RepairPolicy;
+    /** Named variants (Phase 3 WS1, bundle v2) — [] for v1 bundles. */
+    readonly variants: readonly RouteVariant[];
+    /** Local-only replay capture opt-in (Phase 3 WS4) — default false. */
+    readonly capture: boolean;
+    /** Grounding-inject search-query template (Phase 3 WS3) — rendered with
+     * the same variables as the system template; absent = the capped rendered
+     * prompt is used as the query (adequate only for short prompts). */
+    readonly groundingQuery?: string;
+    /** Schema-fingerprint cell key, computed at load from outputSchema
+     * (registry/fingerprint.ts); null for unstructured routes. */
+    readonly fingerprintCell: string | null;
+}
+export interface RunTags {
+    readonly run_id?: string;
+    readonly step?: string;
+    readonly [key: string]: string | undefined;
+}
+export interface RunOptions {
+    readonly input: Record<string, unknown>;
+    readonly tags: RunTags;
+    readonly budget?: {
+        readonly envelope: string;
+    };
+    /** Named variant to serve (Phase 3 WS1); omitted = the default variant
+     * (the route's base config). Unknown names are config errors. */
+    readonly variant?: string;
+}
+export interface RunMeta {
+    /** Telemetry row id of the serving attempt — the handle rig.feedback()
+     * takes (Phase 4 WS2). */
+    readonly inferenceId: string;
+    readonly route: string;
+    readonly routeVersion: number;
+    readonly provider: ProviderId;
+    readonly model: string;
+    readonly requestedTier: ServiceTier;
+    readonly servedTier: ServiceTier;
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly tokensCached: number;
+    readonly costEstimateUsd: number;
+    readonly latencyMs: number;
+    readonly validated: boolean;
+    readonly attemptsByClass: Partial<Record<FailureClass, number>>;
+    /** Variant that served this run — null = default variant (Phase 3 WS1). */
+    readonly servedVariant: string | null;
+    /** "provider/model" that repaired the output — null when unrepaired
+     * (Phase 3 WS2). */
+    readonly repairedBy: string | null;
+    /** Normalized url_citation annotations (Phase 3 WS3) — present when the
+     * grounding-inject rung served this run. */
+    readonly citations?: ReadonlyArray<{
+        readonly type: "url_citation";
+        readonly url: string;
+        readonly title?: string;
+    }>;
+}
+export interface RunResult {
+    readonly output: unknown;
+    readonly meta: RunMeta;
+}
+//# sourceMappingURL=route.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,UAAU,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAChG,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;AAE5C,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAC;CACvC;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B;;;kCAG8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;oEACgE;IAChE,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC;CACtC;AAED;6EAC6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;wBAEoB;IACpB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C;6EACyE;IACzE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;gCAC4B;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;4DACwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;wEAEoE;IACpE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;kEAC8D;IAC9D,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD;qEACiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,OAAO;IACtB;8BAC0B;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC;wBACoB;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;gDAC4C;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;QACjC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;QAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB"}

package/dist/types/route.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Route bundle contract — spec §3. Loaded from modelrig/routes/*.yaml by
+ * routes/loader.ts; frozen after load.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/telemetry.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Telemetry contracts — spec §5. SQLite-backed in Phase 1 (telemetry/store.ts);
+ * the interface exists so Phase 6 can add a remote control-plane sink.
+ */
+import type { FailureClass } from "./failures";
+import type { RunTags } from "./route";
+export interface TelemetryRow {
+    readonly id: string;
+    readonly ts: string;
+    readonly route: string;
+    readonly routeVersion: number;
+    readonly provider: string;
+    readonly model: string;
+    readonly requestedTier: string;
+    readonly servedTier: string;
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly tokensCached: number;
+    readonly costEstimateUsd: number;
+    readonly latencyMs: number;
+    /** Time to first body byte, ms (Phase 4 WS3) — null when nothing arrived
+     * or for rows recorded before the v6 migration. */
+    readonly ttfbMs: number | null;
+    readonly failureClass: FailureClass | null;
+    readonly attemptsJson: string;
+    readonly tagsJson: string;
+    /** Schema-fingerprint cell key (registry/fingerprint.ts) — null for
+     * unstructured routes and rows recorded before the v2 migration. */
+    readonly fingerprintCell: string | null;
+    /** True when this attempt's model had no pricing entry (addendum A1):
+     * cost_estimate_usd stays 0 (no invented dollars) and any active envelope
+     * was charged the conservative unpriced rate instead. */
+    readonly pricingMissing: boolean;
+    /** Variant name this attempt served (Phase 3 WS1) — null = default variant
+     * and rows recorded before the v3 migration. */
+    readonly servedVariant: string | null;
+    /** "provider/model" of the repair model that produced this row's output
+     * (Phase 3 WS2) — null for unrepaired attempts. */
+    readonly repairedBy: string | null;
+}
+export interface EnvelopeRow {
+    readonly envelopeKey: string;
+    readonly budgetUsd: number;
+    readonly spentUsd: number;
+    readonly status: "open" | "exhausted";
+}
+/** One rig.feedback() judgment (Phase 4 WS2) — attached to a single
+ * inference OR an episode (= run-level key), or both. Local SQLite is the
+ * write path; the exporter mirrors (dual-store symmetry with inferences). */
+export interface FeedbackRow {
+    readonly id: string;
+    readonly ts: string;
+    readonly inferenceId: string | null;
+    readonly episodeKey: string | null;
+    readonly verdict: "up" | "down";
+    readonly score: number | null;
+    readonly note: string | null;
+    readonly source: string;
+    /**
+     * The org this verdict belongs to — Phase 6 WS2, and the reason this field
+     * exists at all.
+     *
+     * A verdict recorded through OUR hosted server belongs to the org of the
+     * person who recorded it, and one SQLite store serves every org that reaches
+     * that server. Without a per-row org the exporter stamps its OWN, which
+     * files a customer's judgment into somebody else's corpus — unrecomputable
+     * evidence, silently wrong. WS1 shipped a 409 refusal rather than misfile;
+     * this column is what replaces the refusal with routing (QA-P6-010).
+     *
+     * NULL is the ordinary case and means "whatever org this exporter is": a
+     * self-hosted rig has exactly one, and `rig.feedback()` from application
+     * code has no notion of orgs at all.
+     */
+    readonly orgId: string | null;
+    /** Authenticated user who recorded it (00017's `feedback.created_by`), or
+     * null for an SDK-recorded verdict — which is a fact about the row, not
+     * missing data, and is never backfilled. */
+    readonly createdBy: string | null;
+}
+export interface TelemetryStore {
+    record(row: TelemetryRow): void;
+    recordFeedback(row: FeedbackRow): void;
+    queryByTag(tag: keyof RunTags & string, value: string): TelemetryRow[];
+    getEnvelope(key: string): EnvelopeRow | null;
+    accrue(key: string, usd: number): EnvelopeRow;
+    openEnvelope(key: string, budgetUsd: number): EnvelopeRow;
+    close(): void;
+}
+//# sourceMappingURL=telemetry.d.ts.map

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

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

package/dist/types/telemetry.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Telemetry contracts — spec §5. SQLite-backed in Phase 1 (telemetry/store.ts);
+ * the interface exists so Phase 6 can add a remote control-plane sink.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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,66 @@
+/**
+ * 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.
+ */
+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;
+}
+/** Trigger payload persisted on the proposal row (jsonb). */
+export interface ProposalTrigger {
+    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;
+}
+export interface ProposalDraft {
+    readonly route: string;
+    readonly kind: "bakeoff";
+    readonly trigger: ProposalTrigger;
+    readonly triggerHash: string;
+    readonly expiresAt: string;
+}
+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[];
+//# 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":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,MAAM,UAAU,GAClB;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;CACrC,CAAC;AAEN,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,WAAW,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAYpC,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAE3E;AAMD,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,MAAM,EAAE,WAAW,GAClB,aAAa,EAAE,CAoDjB"}

package/dist/watch/evaluate.js

@@ -0,0 +1,94 @@
+"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;
+const node_crypto_1 = require("node:crypto");
+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;
+}

package/dist/watch/proposals.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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, 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: "bakeoff" | "swap";
+    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;
+    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 PATCH. */
+    attachEvidence(id: string, evidence: Record<string, unknown>): Promise<void>;
+    /** 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