modelrig 0.0.1 → 0.1.0

package/dist/telemetry/store.js

@@ -0,0 +1,332 @@
+"use strict";
+/**
+ * SQLite telemetry store — spec §5, plan §2. Package-owned storage; zero
+ * InferWealth Supabase involvement. Schema created idempotently on open;
+ * PRAGMA user_version tracks migrations (v2: fingerprint_cell, Phase 2;
+ * v3: captures table + served_variant/repaired_by, Phase 3).
+ *
+ * PRIVACY (Phase 3 WS4): the `captures` table is created here but NEVER read
+ * here — capture access lives exclusively behind telemetry/capture.ts's
+ * separate handle. ExportableTelemetryStore MUST NOT gain capture accessors;
+ * the export-isolation tests are the tripwire.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openTelemetryStore = openTelemetryStore;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS inferences (
+  id                TEXT PRIMARY KEY,
+  ts                TEXT NOT NULL,
+  route             TEXT NOT NULL,
+  route_version     INTEGER NOT NULL,
+  provider          TEXT NOT NULL,
+  model             TEXT NOT NULL,
+  requested_tier    TEXT NOT NULL,
+  served_tier       TEXT NOT NULL,
+  tokens_in         INTEGER NOT NULL,
+  tokens_out        INTEGER NOT NULL,
+  tokens_cached     INTEGER NOT NULL,
+  cost_estimate_usd REAL NOT NULL,
+  latency_ms        INTEGER NOT NULL,
+  ttfb_ms           INTEGER,
+  failure_class     TEXT,
+  attempts_json     TEXT NOT NULL,
+  tags_json         TEXT NOT NULL,
+  fingerprint_cell  TEXT,
+  served_variant    TEXT,
+  repaired_by       TEXT,
+  pricing_missing   INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_inferences_route_ts ON inferences (route, ts);
+
+CREATE TABLE IF NOT EXISTS captures (
+  inference_id   TEXT PRIMARY KEY,
+  ts             TEXT NOT NULL,
+  route          TEXT NOT NULL,
+  route_version  INTEGER NOT NULL,
+  variables_json TEXT NOT NULL,
+  output_text    TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_captures_route_ts ON captures (route, ts);
+
+CREATE TABLE IF NOT EXISTS envelopes (
+  envelope_key TEXT PRIMARY KEY,
+  budget_usd   REAL NOT NULL,
+  spent_usd    REAL NOT NULL DEFAULT 0,
+  status       TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open', 'exhausted'))
+);
+
+CREATE TABLE IF NOT EXISTS export_state (
+  source_id  TEXT PRIMARY KEY,
+  last_rowid INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS feedback (
+  id           TEXT PRIMARY KEY,
+  ts           TEXT NOT NULL,
+  inference_id TEXT,
+  episode_key  TEXT,
+  verdict      TEXT NOT NULL CHECK (verdict IN ('up', 'down')),
+  score        REAL,
+  note         TEXT,
+  source       TEXT NOT NULL,
+  -- v7 (Phase 6 WS2): the verdict's own tenant and author. NULL org_id means
+  -- "whatever org this exporter is", which is the right answer for every
+  -- self-hosted rig; a non-null one is a verdict recorded THROUGH a server on
+  -- behalf of another org, and the exporter must not overwrite it (QA-P6-010).
+  org_id       TEXT,
+  created_by   TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_feedback_inference ON feedback (inference_id);
+CREATE INDEX IF NOT EXISTS idx_feedback_episode ON feedback (episode_key);
+`;
+function toFeedbackRow(r) {
+    return {
+        id: r.id,
+        ts: r.ts,
+        inferenceId: r.inference_id,
+        episodeKey: r.episode_key,
+        verdict: r.verdict,
+        score: r.score,
+        note: r.note,
+        source: r.source,
+        // `?? null` rather than a bare read: a v6 database returns `undefined`
+        // for a column that did not exist when its rows were written, and
+        // `undefined` would serialize to a MISSING key on the wire rather than an
+        // explicit null — which reads to the server as "no opinion" instead of
+        // "no org", a distinction that matters exactly once and expensively.
+        orgId: r.org_id ?? null,
+        createdBy: r.created_by ?? null,
+    };
+}
+function toTelemetryRow(r) {
+    return {
+        id: r.id,
+        ts: r.ts,
+        route: r.route,
+        routeVersion: r.route_version,
+        provider: r.provider,
+        model: r.model,
+        requestedTier: r.requested_tier,
+        servedTier: r.served_tier,
+        tokensIn: r.tokens_in,
+        tokensOut: r.tokens_out,
+        tokensCached: r.tokens_cached,
+        costEstimateUsd: r.cost_estimate_usd,
+        latencyMs: r.latency_ms,
+        ttfbMs: r.ttfb_ms,
+        failureClass: r.failure_class,
+        attemptsJson: r.attempts_json,
+        tagsJson: r.tags_json,
+        fingerprintCell: r.fingerprint_cell,
+        servedVariant: r.served_variant,
+        repairedBy: r.repaired_by,
+        pricingMissing: r.pricing_missing !== 0,
+    };
+}
+function toEnvelopeRow(r) {
+    return {
+        envelopeKey: r.envelope_key,
+        budgetUsd: r.budget_usd,
+        spentUsd: r.spent_usd,
+        status: r.status,
+    };
+}
+function openTelemetryStore(dbPath) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(dbPath), { recursive: true });
+    const db = new better_sqlite3_1.default(dbPath);
+    db.pragma("journal_mode = WAL");
+    db.exec(SCHEMA_SQL);
+    // Migrations, idempotent on every open. Fresh databases get the full v2
+    // schema from SCHEMA_SQL above; v1 databases (tables pre-existing, so the
+    // CREATEs were no-ops) gain the fingerprint_cell column additively —
+    // existing rows are untouched and read back with fingerprint_cell = NULL.
+    if (db.pragma("user_version", { simple: true }) < 2) {
+        const columns = db.prepare("PRAGMA table_info(inferences)").all();
+        if (!columns.some((c) => c.name === "fingerprint_cell")) {
+            db.exec("ALTER TABLE inferences ADD COLUMN fingerprint_cell TEXT");
+        }
+        db.pragma("user_version = 2");
+    }
+    // v3 (Phase 3): captures table (from SCHEMA_SQL above — a no-op CREATE on
+    // fresh databases) + the variant/repair columns, additive and nullable.
+    if (db.pragma("user_version", { simple: true }) < 3) {
+        const columns = db.prepare("PRAGMA table_info(inferences)").all();
+        if (!columns.some((c) => c.name === "served_variant")) {
+            db.exec("ALTER TABLE inferences ADD COLUMN served_variant TEXT");
+        }
+        if (!columns.some((c) => c.name === "repaired_by")) {
+            db.exec("ALTER TABLE inferences ADD COLUMN repaired_by TEXT");
+        }
+        db.pragma("user_version = 3");
+    }
+    // v4 (addendum A1): pricing_missing flag — additive; old rows read false.
+    if (db.pragma("user_version", { simple: true }) < 4) {
+        const columns = db.prepare("PRAGMA table_info(inferences)").all();
+        if (!columns.some((c) => c.name === "pricing_missing")) {
+            db.exec("ALTER TABLE inferences ADD COLUMN pricing_missing INTEGER NOT NULL DEFAULT 0");
+        }
+        db.pragma("user_version = 4");
+    }
+    // v5 (Phase 4 WS2): feedback table — purely additive; SCHEMA_SQL's
+    // CREATE IF NOT EXISTS handles fresh AND migrating databases identically,
+    // so the bump only stamps the version.
+    if (db.pragma("user_version", { simple: true }) < 5) {
+        db.pragma("user_version = 5");
+    }
+    // v6 (Phase 4 WS3): ttfb_ms — additive, nullable; old rows read null.
+    if (db.pragma("user_version", { simple: true }) < 6) {
+        const columns = db.prepare("PRAGMA table_info(inferences)").all();
+        if (!columns.some((c) => c.name === "ttfb_ms")) {
+            db.exec("ALTER TABLE inferences ADD COLUMN ttfb_ms INTEGER");
+        }
+        db.pragma("user_version = 6");
+    }
+    // v7 (Phase 6 WS2): feedback.org_id + feedback.created_by — additive,
+    // nullable. Old verdicts read null on both, which is TRUE of them: they were
+    // recorded before either concept existed, and backfilling a guess into an
+    // unrecomputable record is exactly what 00017 refused to do.
+    if (db.pragma("user_version", { simple: true }) < 7) {
+        const columns = db.prepare("PRAGMA table_info(feedback)").all();
+        if (!columns.some((c) => c.name === "org_id")) {
+            db.exec("ALTER TABLE feedback ADD COLUMN org_id TEXT");
+        }
+        if (!columns.some((c) => c.name === "created_by")) {
+            db.exec("ALTER TABLE feedback ADD COLUMN created_by TEXT");
+        }
+        db.pragma("user_version = 7");
+    }
+    const insertInference = db.prepare(`
+    INSERT INTO inferences (
+      id, ts, route, route_version, provider, model, requested_tier, served_tier,
+      tokens_in, tokens_out, tokens_cached, cost_estimate_usd, latency_ms, ttfb_ms,
+      failure_class, attempts_json, tags_json, fingerprint_cell, served_variant, repaired_by, pricing_missing
+    ) VALUES (
+      @id, @ts, @route, @route_version, @provider, @model, @requested_tier, @served_tier,
+      @tokens_in, @tokens_out, @tokens_cached, @cost_estimate_usd, @latency_ms, @ttfb_ms,
+      @failure_class, @attempts_json, @tags_json, @fingerprint_cell, @served_variant, @repaired_by, @pricing_missing
+    )
+  `);
+    const selectByTag = db.prepare(`
+    SELECT * FROM inferences
+    WHERE json_extract(tags_json, '$.' || ?) = ?
+    ORDER BY ts, rowid
+  `);
+    const selectEnvelope = db.prepare("SELECT * FROM envelopes WHERE envelope_key = ?");
+    const insertEnvelope = db.prepare(`
+    INSERT INTO envelopes (envelope_key, budget_usd, spent_usd, status)
+    VALUES (?, ?, 0, 'open')
+    ON CONFLICT (envelope_key) DO NOTHING
+  `);
+    const insertFeedback = db.prepare(`
+    INSERT INTO feedback (
+      id, ts, inference_id, episode_key, verdict, score, note, source, org_id, created_by
+    )
+    VALUES (
+      @id, @ts, @inference_id, @episode_key, @verdict, @score, @note, @source, @org_id, @created_by
+    )
+  `);
+    const accrueEnvelope = db.prepare(`
+    UPDATE envelopes
+    SET spent_usd = spent_usd + ?,
+        status = CASE WHEN spent_usd + ? >= budget_usd THEN 'exhausted' ELSE status END
+    WHERE envelope_key = ?
+  `);
+    return {
+        record(row) {
+            insertInference.run({
+                id: row.id,
+                ts: row.ts,
+                route: row.route,
+                route_version: row.routeVersion,
+                provider: row.provider,
+                model: row.model,
+                requested_tier: row.requestedTier,
+                served_tier: row.servedTier,
+                tokens_in: row.tokensIn,
+                tokens_out: row.tokensOut,
+                tokens_cached: row.tokensCached,
+                cost_estimate_usd: row.costEstimateUsd,
+                latency_ms: row.latencyMs,
+                ttfb_ms: row.ttfbMs,
+                failure_class: row.failureClass,
+                attempts_json: row.attemptsJson,
+                tags_json: row.tagsJson,
+                fingerprint_cell: row.fingerprintCell,
+                served_variant: row.servedVariant,
+                repaired_by: row.repairedBy,
+                pricing_missing: row.pricingMissing ? 1 : 0,
+            });
+        },
+        recordFeedback(row) {
+            insertFeedback.run({
+                id: row.id,
+                ts: row.ts,
+                inference_id: row.inferenceId,
+                episode_key: row.episodeKey,
+                verdict: row.verdict,
+                score: row.score,
+                note: row.note,
+                source: row.source,
+                org_id: row.orgId,
+                created_by: row.createdBy,
+            });
+        },
+        readFeedbackAfter(afterRowid, limit) {
+            const rows = db
+                .prepare("SELECT rowid AS __rowid, * FROM feedback WHERE rowid > ? ORDER BY rowid LIMIT ?")
+                .all(afterRowid, limit);
+            return rows.map((r) => ({ rowid: r.__rowid, row: toFeedbackRow(r) }));
+        },
+        listFeedback(limit) {
+            const rows = db
+                .prepare("SELECT * FROM feedback ORDER BY ts DESC, rowid DESC LIMIT ?")
+                .all(limit);
+            return rows.map(toFeedbackRow);
+        },
+        queryByTag(tag, value) {
+            return selectByTag.all(tag, value).map(toTelemetryRow);
+        },
+        getEnvelope(key) {
+            const row = selectEnvelope.get(key);
+            return row ? toEnvelopeRow(row) : null;
+        },
+        openEnvelope(key, budgetUsd) {
+            insertEnvelope.run(key, budgetUsd);
+            return toEnvelopeRow(selectEnvelope.get(key));
+        },
+        accrue(key, usd) {
+            const result = accrueEnvelope.run(usd, usd, key);
+            if (result.changes === 0) {
+                throw new Error(`accrue on unopened envelope "${key}" — call openEnvelope first`);
+            }
+            return toEnvelopeRow(selectEnvelope.get(key));
+        },
+        readInferencesAfter(afterRowid, limit) {
+            const rows = db
+                .prepare("SELECT rowid AS __rowid, * FROM inferences WHERE rowid > ? ORDER BY rowid LIMIT ?")
+                .all(afterRowid, limit);
+            return rows.map((r) => ({ rowid: r.__rowid, row: toTelemetryRow(r) }));
+        },
+        listEnvelopes() {
+            const rows = db.prepare("SELECT * FROM envelopes ORDER BY envelope_key").all();
+            return rows.map(toEnvelopeRow);
+        },
+        getExportWatermark(sourceId) {
+            const row = db.prepare("SELECT last_rowid FROM export_state WHERE source_id = ?").get(sourceId);
+            return row?.last_rowid ?? 0;
+        },
+        setExportWatermark(sourceId, lastRowid) {
+            db.prepare(`INSERT INTO export_state (source_id, last_rowid) VALUES (?, ?)
+         ON CONFLICT (source_id) DO UPDATE SET last_rowid = excluded.last_rowid`).run(sourceId, lastRowid);
+        },
+        close() {
+            db.close();
+        },
+    };
+}

package/dist/telemetry/supabase-exporter.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Async batch exporter: SQLite telemetry → ModelRig Supabase project.
+ * Spec §5 (cloud sink) + §6 criteria 8–9. Fire-and-forget from the run loop:
+ * the inference path NEVER blocks on, or fails because of, this sink.
+ * At-least-once delivery with idempotent ids; unexported rows queue locally in
+ * SQLite (the inferences table itself, behind a rowid watermark) and flush on
+ * recovery; watermark bookkeeping per source instance.
+ *
+ * Transport is raw PostgREST over fetch (dependency-light, service-role key).
+ */
+import type { RigManifest } from "../routes/manifest";
+import type { ServeabilityWarning } from "../routes/serveability";
+import type { ExportableTelemetryStore } from "./store";
+export interface ExportedRouteMirror {
+    readonly route: string;
+    readonly version: number;
+    readonly candidates: ReadonlyArray<{
+        readonly provider: string;
+        readonly model: string;
+    }>;
+    /** Capture opt-in FLAG (Phase 3 WS4) — status only; capture content never
+     * has a cloud surface. */
+    readonly capture?: boolean;
+}
+export interface ExporterConfig {
+    readonly supabaseUrl: string;
+    /** Service-role key — server-side only; never reaches the console. */
+    readonly serviceRoleKey: string;
+    readonly sourceId: string;
+    /**
+     * Tenant for every row this exporter writes (Phase 6 WS1). Defaults to the
+     * house org, which is the right answer for a self-hosted control plane —
+     * there is exactly one org there and everything belongs to it.
+     *
+     * This is DIRECT mode only. In api mode the server resolves org and project
+     * from the `rig_sk_` key and stamps them itself: a client that could choose
+     * its own tenant would not be a tenant boundary (T3).
+     */
+    readonly orgId?: string;
+    /** Finer scope inside the org. Null is legitimate — not every rig has one. */
+    readonly projectId?: string | null;
+    readonly batchSize?: number;
+    readonly intervalMs?: number;
+    /** Loaded route bundles, mirrored to the `routes` table for the console. */
+    readonly routes?: readonly ExportedRouteMirror[];
+    /** Rig manifest, mirrored to the `rig_manifests` table for the console
+     * (dimension NAMES only — tag values never leave the telemetry rows). */
+    readonly manifest?: RigManifest | null;
+    /** Inert-candidate warnings for THIS deployment (F1) — mirrored onto the
+     * manifest row so console /setup can say "2 candidates inert here, set
+     * XAI_API_KEY" instead of the fact living only in a boot log. Names only:
+     * route, provider, model, env var. */
+    readonly serveability?: readonly ServeabilityWarning[];
+    /** Injectable for tests; defaults to global fetch. */
+    readonly fetchFn?: typeof fetch;
+}
+export interface Exporter {
+    start(): void;
+    /** Flush pending rows now (used by tests and process-exit hooks). */
+    flush(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function createSupabaseExporter(store: ExportableTelemetryStore, config: ExporterConfig): Exporter;
+//# sourceMappingURL=supabase-exporter.d.ts.map

package/dist/telemetry/supabase-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supabase-exporter.d.ts","sourceRoot":"","sources":["../../src/telemetry/supabase-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAIlE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1F;8BAC0B;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD;6EACyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC;;;0CAGsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACvD,sDAAsD;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,qEAAqE;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAiFD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,wBAAwB,EAC/B,MAAM,EAAE,cAAc,GACrB,QAAQ,CA4KV"}

package/dist/telemetry/supabase-exporter.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Async batch exporter: SQLite telemetry → ModelRig Supabase project.
+ * Spec §5 (cloud sink) + §6 criteria 8–9. Fire-and-forget from the run loop:
+ * the inference path NEVER blocks on, or fails because of, this sink.
+ * At-least-once delivery with idempotent ids; unexported rows queue locally in
+ * SQLite (the inferences table itself, behind a rowid watermark) and flush on
+ * recovery; watermark bookkeeping per source instance.
+ *
+ * Transport is raw PostgREST over fetch (dependency-light, service-role key).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSupabaseExporter = createSupabaseExporter;
+const constants_1 = require("../tenancy/constants");
+const DEFAULT_BATCH_SIZE = 200;
+const DEFAULT_INTERVAL_MS = 10000;
+/** After a sink failure, skip this many intervals, doubling per consecutive
+ * failure (simple exponential backoff, capped). */
+const BACKOFF_MAX_SKIPS = 32;
+function toRemote(row, tenancy) {
+    return {
+        ...tenancy,
+        id: row.id,
+        ts: row.ts,
+        route: row.route,
+        route_version: row.routeVersion,
+        provider: row.provider,
+        model: row.model,
+        requested_tier: row.requestedTier,
+        served_tier: row.servedTier,
+        tokens_in: row.tokensIn,
+        tokens_out: row.tokensOut,
+        tokens_cached: row.tokensCached,
+        cost_estimate_usd: row.costEstimateUsd,
+        latency_ms: row.latencyMs,
+        ttfb_ms: row.ttfbMs,
+        failure_class: row.failureClass,
+        attempts: JSON.parse(row.attemptsJson),
+        tags: JSON.parse(row.tagsJson),
+        fingerprint_cell: row.fingerprintCell,
+        served_variant: row.servedVariant,
+        repaired_by: row.repairedBy,
+        pricing_missing: row.pricingMissing,
+    };
+}
+function feedbackToRemote(row, tenancy) {
+    return {
+        org_id: tenancy.org_id,
+        project_id: tenancy.project_id,
+        id: row.id,
+        ts: row.ts,
+        inference_id: row.inferenceId,
+        episode_key: row.episodeKey,
+        verdict: row.verdict,
+        score: row.score,
+        note: row.note,
+        source: row.source,
+    };
+}
+function createSupabaseExporter(store, config) {
+    const batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
+    const intervalMs = config.intervalMs ?? DEFAULT_INTERVAL_MS;
+    const fetchFn = config.fetchFn ?? fetch;
+    const base = config.supabaseUrl.replace(/\/$/, "");
+    const tenancy = {
+        org_id: config.orgId ?? constants_1.HOUSE_ORG_ID,
+        project_id: config.projectId ?? null,
+        source_id: config.sourceId,
+    };
+    let timer = null;
+    let flushing = false;
+    let skipsRemaining = 0;
+    let consecutiveFailures = 0;
+    let routesMirrored = false;
+    let manifestMirrored = false;
+    async function post(table, body, upsert) {
+        const response = await fetchFn(`${base}/rest/v1/${table}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                apikey: config.serviceRoleKey,
+                authorization: `Bearer ${config.serviceRoleKey}`,
+                prefer: upsert
+                    ? "resolution=merge-duplicates,return=minimal"
+                    : "resolution=ignore-duplicates,return=minimal",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new Error(`sink POST ${table} → ${response.status} ${await response.text().catch(() => "")}`);
+        }
+    }
+    async function flushOnce() {
+        // Routes mirror first (idempotent upsert; retried until it succeeds once).
+        if (!routesMirrored && config.routes !== undefined && config.routes.length > 0) {
+            await post("routes", config.routes.map((r) => ({
+                org_id: tenancy.org_id,
+                route: r.route,
+                version: r.version,
+                candidates: r.candidates,
+                capture: r.capture ?? false,
+                updated_at: new Date().toISOString(),
+            })), true);
+            routesMirrored = true;
+        }
+        // Manifest mirror (idempotent upsert, once per process — like routes).
+        if (!manifestMirrored && config.manifest !== undefined && config.manifest !== null) {
+            await post("rig_manifests", [
+                {
+                    org_id: tenancy.org_id,
+                    source_id: config.sourceId,
+                    name: config.manifest.name,
+                    dimensions: config.manifest.dimensions,
+                    contribution: config.manifest.contribution,
+                    // F1: names only — route, provider/model, and the env var to set.
+                    serveability: (config.serveability ?? []).map((w) => ({
+                        route: w.route,
+                        inert: w.inert.map((c) => ({ provider: c.provider, model: c.model })),
+                        serveable_count: w.serveableCount,
+                        fix_hint: w.fixHint,
+                    })),
+                    updated_at: new Date().toISOString(),
+                },
+            ], true);
+            manifestMirrored = true;
+        }
+        // Inferences past the watermark, in batches. Watermark advances ONLY
+        // after a confirmed write (at-least-once; remote id conflicts ignored).
+        for (;;) {
+            const watermark = store.getExportWatermark(config.sourceId);
+            const pending = store.readInferencesAfter(watermark, batchSize);
+            if (pending.length === 0)
+                break;
+            await post("inferences", pending.map(({ row }) => toRemote(row, tenancy)), false);
+            store.setExportWatermark(config.sourceId, pending[pending.length - 1].rowid);
+            await post("export_watermarks", [{ org_id: tenancy.org_id, source_id: config.sourceId, last_exported_ts: new Date().toISOString() }], true);
+            if (pending.length < batchSize)
+                break;
+        }
+        // Feedback mirror (Phase 4 WS2): same at-least-once watermark dance as
+        // inferences, behind its own export_state key so the two streams never
+        // block each other.
+        const feedbackSource = `${config.sourceId}:feedback`;
+        for (;;) {
+            const watermark = store.getExportWatermark(feedbackSource);
+            const pending = store.readFeedbackAfter(watermark, batchSize);
+            if (pending.length === 0)
+                break;
+            await post("feedback", pending.map(({ row }) => feedbackToRemote(row, tenancy)), false);
+            store.setExportWatermark(feedbackSource, pending[pending.length - 1].rowid);
+            if (pending.length < batchSize)
+                break;
+        }
+        // Envelopes: small table, full upsert each flush.
+        const envelopes = store.listEnvelopes();
+        if (envelopes.length > 0) {
+            await post("envelopes", envelopes.map((e) => ({
+                org_id: tenancy.org_id,
+                envelope_key: e.envelopeKey,
+                budget_usd: e.budgetUsd,
+                spent_usd: e.spentUsd,
+                status: e.status,
+                exported_at: new Date().toISOString(),
+            })), true);
+        }
+    }
+    async function guardedFlush() {
+        if (flushing)
+            return;
+        flushing = true;
+        try {
+            await flushOnce();
+            consecutiveFailures = 0;
+        }
+        catch (err) {
+            // Swallow-and-log, ALWAYS — sink failures must never reach the run loop.
+            consecutiveFailures += 1;
+            skipsRemaining = Math.min(2 ** consecutiveFailures, BACKOFF_MAX_SKIPS);
+            console.warn(`[modelrig exporter] sink flush failed (attempt ${consecutiveFailures}, backing off ` +
+                `${skipsRemaining} intervals): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            flushing = false;
+        }
+    }
+    return {
+        start() {
+            if (timer !== null)
+                return;
+            timer = setInterval(() => {
+                if (skipsRemaining > 0) {
+                    skipsRemaining -= 1;
+                    return;
+                }
+                void guardedFlush();
+            }, intervalMs);
+            // Never keep the process alive for telemetry export.
+            timer.unref?.();
+        },
+        async flush() {
+            await guardedFlush();
+        },
+        async stop() {
+            if (timer !== null) {
+                clearInterval(timer);
+                timer = null;
+            }
+            await guardedFlush();
+        },
+    };
+}

package/dist/tenancy/api-key-format.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The `rig_sk_` key FORMAT — Phase 6 WS2.
+ *
+ * Shared knowledge, deliberately: the SDK builds the header that presents a
+ * key, modelrig-server resolves one, and the oracle decides whether the value
+ * it was handed is a key at all. Three packages agreeing on a prefix by
+ * copying a string literal is how N1's "one name per concept" fails in
+ * practice, so the string lives here and they all import it.
+ *
+ * What is NOT here is MINTING. Generating a secret and writing its hash is the
+ * control plane's job; an SDK that could do it would imply a client could
+ * issue itself a credential, which is the shape of the thing this scheme
+ * exists to prevent. `mintApiKey` lives in modelrig-server.
+ */
+/**
+ * The one place this prefix is spelled. Grep-visible on purpose: the
+ * guardrails C2 rule keys off it, and so does the exporter's sink selection.
+ */
+export declare const API_KEY_PREFIX = "rig_sk_";
+/** 32 bytes = 256 bits, as base64url. The minting side uses this to generate;
+ * this side uses its ENCODED length to recognise. See 00020's header for why
+ * that number carries the argument that a plain sha-256 at rest is sound. */
+export declare const API_KEY_SECRET_BYTES = 32;
+/** base64url length of API_KEY_SECRET_BYTES — the minimum a real key's body has. */
+export declare const API_KEY_BODY_MIN_LENGTH = 43;
+/**
+ * The granted authorities. Mirrors migration 00020's CHECK constraint — a
+ * test pins that the two agree, because a scope that exists here and not
+ * there is a key that cannot be written, and one that exists there and not
+ * here is an authority nothing enforces.
+ */
+export declare const API_KEY_SCOPES: readonly ["ingest", "query", "feedback", "decision", "oracle-act"];
+export type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
+/** sha256 of the WHOLE presented string, prefix included — so a caller cannot
+ * strip the prefix and land on a different row. */
+export declare function hashApiKeySecret(secret: string): string;
+/**
+ * Cheap shape check, used to decide which credential branch a bearer token
+ * takes before any I/O happens.
+ *
+ * The minimum body length matters: without it the bare string `rig_sk_` would
+ * take the api-key branch and cost a database round trip per garbage request,
+ * which is a free amplification primitive on an unauthenticated surface.
+ */
+export declare function looksLikeApiKey(presented: string): boolean;
+/**
+ * What a key may be called in a log line, an error, or a boot banner.
+ *
+ * Returns the placeholder form for a non-key so that a caller who reaches for
+ * this with the wrong variable prints nothing useful rather than printing the
+ * whole thing. C2's leak-gate is the belt; this is the braces.
+ */
+export declare function redactApiKey(presented: string): string;
+/**
+ * Narrow an untrusted scope list to the known set (T7: a jsonb/array column
+ * is not proof of shape — narrow at the boundary).
+ *
+ * Unknown entries are DROPPED, not rejected: a row written by a future
+ * migration with a scope this build predates should still authorize the
+ * scopes this build understands, rather than failing closed on everything.
+ * Returns declaration order so two equal grant sets compare equal.
+ */
+export declare function parseScopes(raw: unknown): ApiKeyScope[];
+/** An empty grant set authorizes nothing — stated as code so it cannot be
+ * accidentally re-derived as "no scopes means unrestricted". */
+export declare function hasScope(granted: readonly ApiKeyScope[], required: ApiKeyScope): boolean;
+//# sourceMappingURL=api-key-format.d.ts.map

package/dist/tenancy/api-key-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-format.d.ts","sourceRoot":"","sources":["../../src/tenancy/api-key-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;GAGG;AACH,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC;;6EAE6E;AAC7E,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,oEAAqE,CAAC;AAEjG,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D;mDACmD;AACnD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAI1D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,EAAE,CAIvD;AAED;gEACgE;AAChE,wBAAgB,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,CAExF"}