modelrig 0.1.0 → 0.3.0

package/dist/telemetry/sinks.js

@@ -21,10 +21,39 @@
  * cost with no payer.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SinkSendError = void 0;
 exports.createDirectSink = createDirectSink;
 exports.createApiSink = createApiSink;
+exports.buildTelemetrySink = buildTelemetrySink;
 const node_zlib_1 = require("node:zlib");
 const ingest_protocol_1 = require("./ingest-protocol");
+const constants_1 = require("../tenancy/constants");
+/**
+ * A sink send failed — the typed error both transports throw (E2 hardening
+ * Phase 2, spec §2.3.1). It carries the HTTP status the sink observed (absent
+ * for a network-level throw) and a `retriable` verdict the exporter branches on:
+ *
+ *   retriable  network throw (no status) · any 5xx · a 429 (overload)
+ *              → the same batch may land next time; retry forever, never drop.
+ *   NOT        every other 4xx, including the server's deterministic 422
+ *              → the same bytes will be rejected identically forever; the
+ *                exporter poison-skips it after a bounded self-heal window.
+ *
+ * The message is leak-safe BY CONSTRUCTION — status + table only, NEVER the
+ * PostgREST/response body. An exporter's warnings are the likeliest place for a
+ * secret or a foreign row to reach someone else's log aggregator (C2's leak
+ * gate), so the body a failed write returns is logged nowhere.
+ */
+class SinkSendError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.name = "SinkSendError";
+        if (status !== undefined)
+            this.status = status;
+        this.retriable = status === undefined || status >= 500 || status === 429;
+    }
+}
+exports.SinkSendError = SinkSendError;
 function createDirectSink(config) {
     const base = config.supabaseUrl.replace(/\/$/, "");
     const fetchFn = config.fetchFn ?? fetch;
@@ -32,23 +61,35 @@ function createDirectSink(config) {
         mode: "direct",
         async send(batch) {
             for (const write of (0, ingest_protocol_1.stampBatch)(batch, config.tenancy)) {
-                const response = await fetchFn(
-                // S5: the upsert names a real unique constraint. A single-argument
-                // upsert targets the primary key and 23505s later.
-                `${base}/rest/v1/${write.table}?on_conflict=${encodeURIComponent(write.onConflict)}`, {
-                    method: "POST",
-                    headers: {
-                        "content-type": "application/json",
-                        apikey: config.serviceRoleKey,
-                        authorization: `Bearer ${config.serviceRoleKey}`,
-                        prefer: write.merge
-                            ? "resolution=merge-duplicates,return=minimal"
-                            : "resolution=ignore-duplicates,return=minimal",
-                    },
-                    body: JSON.stringify(write.rows),
-                });
+                let response;
+                try {
+                    response = await fetchFn(
+                    // S5: the upsert names a real unique constraint. A single-argument
+                    // upsert targets the primary key and 23505s later.
+                    `${base}/rest/v1/${write.table}?on_conflict=${encodeURIComponent(write.onConflict)}`, {
+                        method: "POST",
+                        headers: {
+                            "content-type": "application/json",
+                            apikey: config.serviceRoleKey,
+                            authorization: `Bearer ${config.serviceRoleKey}`,
+                            prefer: write.merge
+                                ? "resolution=merge-duplicates,return=minimal"
+                                : "resolution=ignore-duplicates,return=minimal",
+                        },
+                        body: JSON.stringify(write.rows),
+                    });
+                }
+                catch {
+                    // Network-level throw — no status, so TRANSIENT (the exporter retries
+                    // forever). The raw error can carry the control-plane host, so it is
+                    // NOT echoed (C2); the table + "network error" is the whole message.
+                    throw new SinkSendError(`sink POST ${write.table} → network error`, undefined);
+                }
                 if (!response.ok) {
-                    throw new Error(`sink POST ${write.table} → ${response.status} ${await response.text().catch(() => "")}`);
+                    // Status + table only — never the PostgREST body (it carries the
+                    // control-plane host and, on some failures, header fragments; C2).
+                    // The status is what the exporter classifies on (spec §2.3.1).
+                    throw new SinkSendError(`sink POST ${write.table} → ${response.status}`, response.status);
                 }
             }
         },
@@ -62,22 +103,37 @@ function createApiSink(config) {
     return {
         mode: "api",
         async send(batch) {
-            const json = JSON.stringify({ ...batch, v: ingest_protocol_1.INGEST_PROTOCOL_VERSION });
+            // Trust the version the EXPORTER set (spec §1.3): it announces v2 only
+            // when the artifact namespace is active, v1 otherwise. Overriding it here
+            // would force every batch to the max version and break the v1-byte-
+            // identical guarantee (and 422 v1 rigs against a strict old server).
+            const json = JSON.stringify(batch);
             const compress = Buffer.byteLength(json) >= GZIP_MIN_BYTES;
-            const response = await fetchFn(url, {
-                method: "POST",
-                headers: {
-                    "content-type": "application/json",
-                    authorization: `Bearer ${config.apiKey}`,
-                    ...(compress ? { "content-encoding": "gzip" } : {}),
-                },
-                body: compress ? (0, node_zlib_1.gzipSync)(json) : json,
-            });
+            let response;
+            try {
+                response = await fetchFn(url, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        authorization: `Bearer ${config.apiKey}`,
+                        ...(compress ? { "content-encoding": "gzip" } : {}),
+                    },
+                    body: compress ? (0, node_zlib_1.gzipSync)(json) : json,
+                });
+            }
+            catch {
+                // Network-level throw — no status ⇒ TRANSIENT (retry forever). The raw
+                // error can carry the endpoint host, so it is not echoed (C2).
+                throw new SinkSendError("ingest POST → network error", undefined);
+            }
             if (!response.ok) {
-                // The key itself never appears in the message — C2's leak gate covers
-                // failure text, and an exporter's warnings are the likeliest place for
-                // a secret to reach someone else's log aggregator.
-                throw new Error(`ingest POST → ${response.status} ${await response.text().catch(() => "")}`);
+                // Status only — never the response body. The key never appears in the
+                // message (C2's leak gate covers failure text), and an exporter's
+                // warnings are the likeliest place for a secret to reach someone else's
+                // log aggregator. The status is the exporter's transient-vs-poison
+                // signal: the server sends 422 for a deterministic control-plane
+                // rejection, 503 for a transient one (spec §2.2/§2.3.1).
+                throw new SinkSendError(`ingest POST → ${response.status}`, response.status);
             }
             if (config.onOutcome !== undefined) {
                 const outcome = (await response.json().catch(() => null));
@@ -87,3 +143,38 @@ function createApiSink(config) {
         },
     };
 }
+/**
+ * Build the telemetry transport for the configured export mode. One place, so
+ * the run-loop exporter and the load-error reporter build it the same way —
+ * telemetry-ingestion-boundary.md §4's "one loop, two transports". (Lived in
+ * index.ts until Phase D; moved here — its natural home — to keep that file
+ * under the LOC cap.)
+ */
+function buildTelemetrySink(exportConfig, sourceId) {
+    return exportConfig.mode === "api"
+        ? createApiSink({
+            ingestUrl: exportConfig.ingestUrl,
+            apiKey: exportConfig.apiKey,
+            // A batch the server partly refused comes back 200. Without this, a
+            // customer whose rows are being dropped would find out by noticing a
+            // gap in a chart weeks later.
+            onOutcome: (outcome) => {
+                const dropped = Object.values(outcome.dropped).reduce((a, b) => a + b, 0);
+                if (dropped === 0)
+                    return;
+                const reasons = Object.entries(outcome.reasons)
+                    .map(([reason, count]) => `${reason}×${count}`)
+                    .join(", ");
+                console.warn(`[modelrig exporter] ingest dropped ${dropped} row(s): ${reasons}`);
+            },
+        })
+        : createDirectSink({
+            supabaseUrl: exportConfig.supabaseUrl,
+            serviceRoleKey: exportConfig.serviceRoleKey,
+            tenancy: {
+                org_id: exportConfig.orgId ?? constants_1.HOUSE_ORG_ID,
+                project_id: exportConfig.projectId ?? null,
+                source_id: sourceId,
+            },
+        });
+}

package/dist/telemetry/store.d.ts

@@ -9,7 +9,8 @@
  * separate handle. ExportableTelemetryStore MUST NOT gain capture accessors;
  * the export-isolation tests are the tripwire.
  */
-import type { EnvelopeRow, FeedbackRow, TelemetryRow, TelemetryStore } from "../types/telemetry";
+import type { EnvelopeRow, FeedbackRow, RunRow, StepRow, TelemetryRow, TelemetryStore } from "../types/telemetry";
+import { type EndpointHealth } from "./health";
 /**
  * Superset of the TelemetryStore contract with the enumeration hooks the
  * Supabase exporter needs (rowid-watermarked reads + local export state).
@@ -27,12 +28,38 @@ export interface ExportableTelemetryStore extends TelemetryStore {
         rowid: number;
         row: FeedbackRow;
     }>;
+    /** Record a run (E2 chunk A) — run.start/run.end. Upsert: run.end overwrites
+     * the running projection with its terminal status/ended_at. */
+    recordRun(row: RunRow): void;
+    /** Record one step attempt (E2 chunk A) — a fact, insert-or-ignore on the PK. */
+    recordStep(row: StepRow): void;
+    /** Runs past the watermark, oldest first (E2 exporter stream). */
+    readRunsAfter(afterRowid: number, limit: number): Array<{
+        rowid: number;
+        row: RunRow;
+    }>;
+    /** Steps past the watermark, oldest first (E2 exporter stream). */
+    readStepsAfter(afterRowid: number, limit: number): Array<{
+        rowid: number;
+        row: StepRow;
+    }>;
+    /** The ground-truth inference id for a (run, step) — the LATEST attempt with a
+     * non-null inference_id, or null (E4 chunk A: bake-off rehydration resolves an
+     * eval case's source step to the inference that keys its captured input). */
+    getStepInferenceId(runId: string, stepKey: string): string | null;
     /** Newest-first local feedback read (console/dev inspection). */
     listFeedback(limit: number): FeedbackRow[];
     listEnvelopes(): EnvelopeRow[];
     /** Local exporter watermark (per source instance), 0 when unset. */
     getExportWatermark(sourceId: string): number;
     setExportWatermark(sourceId: string, lastRowid: number): void;
+    /**
+     * Observed-health aggregate (G-4) — per (provider, model) over the last
+     * `windowMinutes`: p50/p90/p99 latency + TTFB and recent error-rate, gated to
+     * `null` below `minN`. Advisory operational health for routing + the console;
+     * NEVER an input to RigIndex rank (spec §4.4).
+     */
+    readEndpointHealth(windowMinutes: number, minN: number): EndpointHealth[];
 }
 export declare function openTelemetryStore(dbPath: string): ExportableTelemetryStore;
 //# sourceMappingURL=store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/telemetry/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGjG;;;;;GAKG;AACH,MAAM,WAAW,wBAAyB,SAAQ,cAAc;IAC9D,qEAAqE;IACrE,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;IACpG,uEAAuE;IACvE,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IACjG,iEAAiE;IACjE,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IAC3C,aAAa,IAAI,WAAW,EAAE,CAAC;IAC/B,oEAAoE;IACpE,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7C,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/D;AAyKD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,wBAAwB,CAkN3E"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/telemetry/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,MAAM,EACN,OAAO,EACP,YAAY,EACZ,cAAc,EACf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAA2B,KAAK,cAAc,EAAuB,MAAM,UAAU,CAAC;AAE7F;;;;;GAKG;AACH,MAAM,WAAW,wBAAyB,SAAQ,cAAc;IAC9D,qEAAqE;IACrE,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;IACpG,uEAAuE;IACvE,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IACjG;mEAC+D;IAC/D,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iFAAiF;IACjF,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,kEAAkE;IAClE,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxF,mEAAmE;IACnE,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC1F;;iFAE6E;IAC7E,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClE,iEAAiE;IACjE,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IAC3C,aAAa,IAAI,WAAW,EAAE,CAAC;IAC/B,oEAAoE;IACpE,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7C,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9D;;;;;OAKG;IACH,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;CAC3E;AA6RD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,wBAAwB,CA8V3E"}

package/dist/telemetry/store.js

@@ -18,6 +18,7 @@ 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,
@@ -40,9 +41,18 @@ CREATE TABLE IF NOT EXISTS inferences (
   fingerprint_cell  TEXT,
   served_variant    TEXT,
   repaired_by       TEXT,
-  pricing_missing   INTEGER NOT NULL DEFAULT 0
+  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,
@@ -84,7 +94,77 @@ CREATE TABLE IF NOT EXISTS feedback (
 );
 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,
@@ -127,6 +207,12 @@ function toTelemetryRow(r) {
         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) {
@@ -201,15 +287,48 @@ function openTelemetryStore(dbPath) {
         }
         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
+      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
+      @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(`
@@ -236,6 +355,32 @@ function openTelemetryStore(dbPath) {
     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) {
@@ -261,6 +406,13 @@ function openTelemetryStore(dbPath) {
                 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) {
@@ -283,6 +435,57 @@ function openTelemetryStore(dbPath) {
                 .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 ?")
@@ -325,6 +528,18 @@ function openTelemetryStore(dbPath) {
             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

@@ -24,12 +24,22 @@ 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.
+ * 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"];
+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. */

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

@@ -1 +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"}
+{"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"}

package/dist/tenancy/api-key-format.js

@@ -33,12 +33,31 @@ exports.API_KEY_SECRET_BYTES = 32;
 /** base64url length of API_KEY_SECRET_BYTES — the minimum a real key's body has. */
 exports.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.
+ * 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.
  */
-exports.API_KEY_SCOPES = ["ingest", "query", "feedback", "decision", "oracle-act"];
+exports.API_KEY_SCOPES = [
+    "ingest",
+    "query",
+    "feedback",
+    "decision",
+    "oracle-act",
+    "artifact-write",
+    "artifact-read",
+    "task-settings",
+];
 /** sha256 of the WHOLE presented string, prefix included — so a caller cannot
  * strip the prefix and land on a different row. */
 function hashApiKeySecret(secret) {