modelrig 0.0.1 → 0.2.0

package/dist/telemetry/store.js

@@ -0,0 +1,547 @@
+"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 health_1 = require("./health");
+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,
+  -- v10 (WS-A cache accounting): cache-write buckets + cache-key/prefix
+  -- substrate. Fresh here; v9-and-earlier gain them via the ALTER ladder below.
+  tokens_cache_write    INTEGER NOT NULL DEFAULT 0,
+  tokens_cache_write_1h INTEGER NOT NULL DEFAULT 0,
+  cache_key             TEXT,
+  prefix_fingerprint    TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_inferences_route_ts ON inferences (route, ts);
+-- v8 (G-4 observed-health): per-endpoint windowed aggregation filters by
+-- (provider, model, ts). Index-only; no data change.
+CREATE INDEX IF NOT EXISTS idx_inferences_provider_model_ts ON inferences (provider, model, 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);
+
+-- v9 (Expansion E2 chunk A): the execution graph's local buffer.
+--
+-- runs is a PROJECTION (PK on id): run.start inserts a running row and run.end
+-- UPDATEs it to a terminal status in place -- a run is genuinely mutable
+-- (start -> end). A rowid watermark cannot re-export an updated row (UPDATE does
+-- not move rowid), so the exporter waters off export_seq, a monotonic counter
+-- bumped on EVERY write (insert or update). run.end bumps it, so the terminal
+-- state re-exports; and because there is one row per id, a batch never carries
+-- the same (org_id,id) twice -- which a merge=true upsert (DO UPDATE) would
+-- reject with "cannot affect row a second time". The server merge collapses
+-- the two exports into the one mutable row.
+CREATE TABLE IF NOT EXISTS runs (
+  id               TEXT PRIMARY KEY,
+  pipeline         TEXT NOT NULL,
+  pipeline_version TEXT,
+  environment      TEXT,
+  episode_key      TEXT,
+  started_at       TEXT NOT NULL,
+  ended_at         TEXT,
+  status           TEXT NOT NULL CHECK (status IN ('running','succeeded','failed','abandoned')),
+  export_seq       INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_runs_export_seq ON runs (export_seq);
+
+-- steps are FACTS -- one row per attempt. The composite PK makes a re-emit a
+-- harmless INSERT-OR-IGNORE (server is merge=false too). rowid still exists (not
+-- WITHOUT ROWID), so the watermark read works identically to the other streams.
+CREATE TABLE IF NOT EXISTS steps (
+  run_id        TEXT NOT NULL,
+  step_key      TEXT NOT NULL,
+  attempt_no    INTEGER NOT NULL,
+  task          TEXT,
+  provenance    TEXT NOT NULL CHECK (provenance IN ('ground-truth','attested')),
+  inference_id  TEXT,
+  span_trace_id TEXT,
+  span_id       TEXT,
+  started_at    TEXT NOT NULL,
+  ended_at      TEXT,
+  failure_class TEXT,
+  PRIMARY KEY (run_id, step_key, attempt_no)
+);
+CREATE INDEX IF NOT EXISTS idx_steps_run ON steps (run_id);
+`;
+function toRunRow(r) {
+    return {
+        id: r.id,
+        pipeline: r.pipeline,
+        pipelineVersion: r.pipeline_version,
+        environment: r.environment,
+        episodeKey: r.episode_key,
+        startedAt: r.started_at,
+        endedAt: r.ended_at,
+        status: r.status,
+    };
+}
+function toStepRow(r) {
+    return {
+        runId: r.run_id,
+        stepKey: r.step_key,
+        attemptNo: r.attempt_no,
+        task: r.task,
+        provenance: r.provenance,
+        inferenceId: r.inference_id,
+        spanTraceId: r.span_trace_id,
+        spanId: r.span_id,
+        startedAt: r.started_at,
+        endedAt: r.ended_at,
+        failureClass: r.failure_class,
+    };
+}
+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,
+        // `?? 0` / `?? null`: a v9-or-earlier database returns undefined for a v10
+        // ALTER column, and those rows genuinely predate cache accounting (WS-A).
+        tokensCacheWrite: r.tokens_cache_write ?? 0,
+        tokensCacheWrite1h: r.tokens_cache_write_1h ?? 0,
+        cacheKey: r.cache_key ?? null,
+        prefixFingerprint: r.prefix_fingerprint ?? null,
+    };
+}
+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");
+    }
+    // v8 (G-4 observed-health): idx_inferences_provider_model_ts — index-only, no
+    // data change. SCHEMA_SQL's CREATE INDEX IF NOT EXISTS handles fresh AND
+    // migrating databases identically (it ran above), so the bump only stamps the
+    // version. Kept explicit rather than folded into v5's bare-stamp branch so the
+    // migration ladder reads one rung per schema epoch.
+    if (db.pragma("user_version", { simple: true }) < 8) {
+        db.exec("CREATE INDEX IF NOT EXISTS idx_inferences_provider_model_ts ON inferences (provider, model, ts)");
+        db.pragma("user_version = 8");
+    }
+    // v9 (Expansion E2 chunk A): runs + steps local outbox. Purely additive —
+    // SCHEMA_SQL's CREATE TABLE IF NOT EXISTS handles fresh AND migrating
+    // databases identically (it ran above), so the bump only stamps the version.
+    // A rig that never enables the artifact namespace simply never writes to them.
+    if (db.pragma("user_version", { simple: true }) < 9) {
+        db.pragma("user_version = 9");
+    }
+    // v10 (WS-A cache accounting): cache-write buckets + cache-key/prefix
+    // substrate. Additive; old rows read 0 / null (true of them — recorded before
+    // caching was accounted). Same ALTER pattern as v2–v6, folded over a list.
+    if (db.pragma("user_version", { simple: true }) < 10) {
+        const cols = db.prepare("PRAGMA table_info(inferences)").all();
+        const add = (name, ddl) => {
+            if (!cols.some((c) => c.name === name))
+                db.exec(`ALTER TABLE inferences ADD COLUMN ${ddl}`);
+        };
+        add("tokens_cache_write", "tokens_cache_write INTEGER NOT NULL DEFAULT 0");
+        add("tokens_cache_write_1h", "tokens_cache_write_1h INTEGER NOT NULL DEFAULT 0");
+        add("cache_key", "cache_key TEXT");
+        add("prefix_fingerprint", "prefix_fingerprint TEXT");
+        db.pragma("user_version = 10");
+    }
+    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,
+      tokens_cache_write, tokens_cache_write_1h, cache_key, prefix_fingerprint
+    ) 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,
+      @tokens_cache_write, @tokens_cache_write_1h, @cache_key, @prefix_fingerprint
+    )
+  `);
+    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 = ?
+  `);
+    // Upsert the run projection and bump export_seq on every write, so run.end's
+    // terminal state re-exports past the `:runs` watermark. better-sqlite3 is
+    // synchronous, so the MAX(export_seq)+1 read is race-free.
+    const nextRunSeq = db.prepare("SELECT COALESCE(MAX(export_seq), 0) + 1 AS n FROM runs");
+    const upsertRun = db.prepare(`
+    INSERT INTO runs (id, pipeline, pipeline_version, environment, episode_key, started_at, ended_at, status, export_seq)
+    VALUES (@id, @pipeline, @pipeline_version, @environment, @episode_key, @started_at, @ended_at, @status, @export_seq)
+    ON CONFLICT (id) DO UPDATE SET
+      pipeline = excluded.pipeline,
+      pipeline_version = excluded.pipeline_version,
+      environment = excluded.environment,
+      episode_key = excluded.episode_key,
+      started_at = excluded.started_at,
+      ended_at = excluded.ended_at,
+      status = excluded.status,
+      export_seq = excluded.export_seq
+  `);
+    const insertStep = db.prepare(`
+    INSERT OR IGNORE INTO steps (
+      run_id, step_key, attempt_no, task, provenance, inference_id, span_trace_id, span_id,
+      started_at, ended_at, failure_class
+    ) VALUES (
+      @run_id, @step_key, @attempt_no, @task, @provenance, @inference_id, @span_trace_id, @span_id,
+      @started_at, @ended_at, @failure_class
+    )
+  `);
+    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,
+                // `?? 0` / `?? null`: the fields are optional on TelemetryRow, and
+                // better-sqlite3 rejects an `undefined` bound param — a row that omits
+                // them is a zero-write / no-key row (fail-closed default).
+                tokens_cache_write: row.tokensCacheWrite ?? 0,
+                tokens_cache_write_1h: row.tokensCacheWrite1h ?? 0,
+                cache_key: row.cacheKey ?? null,
+                prefix_fingerprint: row.prefixFingerprint ?? null,
+            });
+        },
+        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) }));
+        },
+        recordRun(row) {
+            const seq = nextRunSeq.get().n;
+            upsertRun.run({
+                id: row.id,
+                pipeline: row.pipeline,
+                pipeline_version: row.pipelineVersion,
+                environment: row.environment,
+                episode_key: row.episodeKey,
+                started_at: row.startedAt,
+                ended_at: row.endedAt,
+                status: row.status,
+                export_seq: seq,
+            });
+        },
+        recordStep(row) {
+            insertStep.run({
+                run_id: row.runId,
+                step_key: row.stepKey,
+                attempt_no: row.attemptNo,
+                task: row.task,
+                provenance: row.provenance,
+                inference_id: row.inferenceId,
+                span_trace_id: row.spanTraceId,
+                span_id: row.spanId,
+                started_at: row.startedAt,
+                ended_at: row.endedAt,
+                failure_class: row.failureClass,
+            });
+        },
+        readRunsAfter(afterSeq, limit) {
+            // Watermark is export_seq (bumped on every write), NOT rowid — a run.end
+            // UPDATE keeps the rowid but advances export_seq, so its terminal state
+            // re-exports. The exporter treats the returned handle opaquely.
+            const rows = db
+                .prepare("SELECT export_seq AS __seq, * FROM runs WHERE export_seq > ? ORDER BY export_seq LIMIT ?")
+                .all(afterSeq, limit);
+            return rows.map((r) => ({ rowid: r.__seq, row: toRunRow(r) }));
+        },
+        readStepsAfter(afterRowid, limit) {
+            const rows = db
+                .prepare("SELECT rowid AS __rowid, * FROM steps WHERE rowid > ? ORDER BY rowid LIMIT ?")
+                .all(afterRowid, limit);
+            return rows.map((r) => ({ rowid: r.__rowid, row: toStepRow(r) }));
+        },
+        getStepInferenceId(runId, stepKey) {
+            const r = db
+                .prepare("SELECT inference_id FROM steps WHERE run_id = ? AND step_key = ? AND inference_id IS NOT NULL " +
+                "ORDER BY attempt_no DESC LIMIT 1")
+                .get(runId, stepKey);
+            return r === undefined ? null : r.inference_id;
+        },
+        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);
+        },
+        readEndpointHealth(windowMinutes, minN) {
+            // Capture `now` once so the SQL prefilter and the in-memory window agree.
+            // ts is ISO-8601 UTC (…Z), so lexical >= is chronological >= — the prefilter
+            // is exact, and aggregateEndpointHealth re-checks the window defensively.
+            const now = Date.now();
+            const windowStartIso = new Date(now - windowMinutes * 60000).toISOString();
+            const rows = db
+                .prepare(`SELECT provider, model, ts, latency_ms, ttfb_ms, failure_class
+             FROM inferences WHERE ts >= ?`)
+                .all(windowStartIso);
+            return (0, health_1.aggregateEndpointHealth)(rows, { windowMinutes, minN, now });
+        },
+        close() {
+            db.close();
+        },
+    };
+}

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

@@ -0,0 +1,77 @@
+/**
+ * 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 (widened
+ * by 00033 for content custody) — 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.
+ *
+ * `artifact-write`/`artifact-read` (E2-C, 00033): request a content upload grant
+ * / mint a content download URL. Both are ordinary (non-elevated) machine
+ * grants — they move an org's own artifact bytes, they do not spend money or
+ * approve swaps (contrast decision/oracle-act, gated to admin/owner minters).
+ *
+ * `task-settings` (settings-plane, 00043): PATCH a task's governance settings
+ * (capture / artifacts / content / scrub). Held by a coding agent flipping
+ * settings for the user. READING settings needs no scope — any org-scoped key
+ * may read, since settings ride the already-readable task row.
+ */
+export declare const API_KEY_SCOPES: readonly ["ingest", "query", "feedback", "decision", "oracle-act", "artifact-write", "artifact-read", "task-settings"];
+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;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,wHASjB,CAAC;AAEX,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"}