modelrig 0.0.1 → 0.2.0

package/dist/telemetry/sinks.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * The two telemetry transports — Phase 6 WS2.
+ *
+ * telemetry-ingestion-boundary.md §2.4 names three modes. Two of them are
+ * sinks and live here; the third (local-only) is the absence of a sink.
+ *
+ *   direct   self-host + our own single-tenant deployments · their database
+ *   api      every hosted customer · their `rig_sk_` key only
+ *
+ * Both implement `TelemetrySink`, both are driven by the SAME exporter loop,
+ * and both produce their database rows through `stampBatch` — so the promise
+ * that "self-host ↔ hosted migration is a config change, not a data model
+ * change" is enforced by construction rather than by review.
+ *
+ * ── WHY THE API SINK GZIPS AND THE DIRECT ONE DOES NOT ───────────────────
+ * The api sink crosses the public internet with one batch per flush, and a
+ * batch is highly repetitive JSON. The direct sink talks to PostgREST, which
+ * would have to decompress it again on the way into the same database the
+ * caller already holds a service-role key for. Compression there would be
+ * 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;
+    return {
+        mode: "direct",
+        async send(batch) {
+            for (const write of (0, ingest_protocol_1.stampBatch)(batch, config.tenancy)) {
+                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) {
+                    // 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);
+                }
+            }
+        },
+    };
+}
+/** Below this, gzip costs more than it saves. */
+const GZIP_MIN_BYTES = 1024;
+function createApiSink(config) {
+    const url = config.ingestUrl.replace(/\/$/, "") + ingest_protocol_1.INGEST_PATH;
+    const fetchFn = config.fetchFn ?? fetch;
+    return {
+        mode: "api",
+        async send(batch) {
+            // 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;
+            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) {
+                // 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));
+                if (outcome !== null)
+                    config.onOutcome(outcome);
+            }
+        },
+    };
+}
+/**
+ * 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

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+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).
+ * Kept out of types/telemetry.ts on purpose: the public contract stays
+ * minimal; the exporter is wired against the concrete store.
+ */
+export interface ExportableTelemetryStore extends TelemetryStore {
+    /** Rows with rowid > afterRowid, oldest first, with their rowids. */
+    readInferencesAfter(afterRowid: number, limit: number): Array<{
+        rowid: number;
+        row: TelemetryRow;
+    }>;
+    /** Feedback rows past the watermark, oldest first (Phase 4 mirror). */
+    readFeedbackAfter(afterRowid: number, limit: number): Array<{
+        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

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