modelrig 0.0.1 → 0.2.0

package/dist/telemetry/exporter.js

@@ -0,0 +1,510 @@
+"use strict";
+/**
+ * Async batch exporter: SQLite telemetry → wherever this rig's telemetry goes.
+ * 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.
+ *
+ * ── ONE LOOP, TWO TRANSPORTS (Phase 6 WS2) ───────────────────────────────
+ * Everything below is transport-agnostic. Batching, watermarks, backoff,
+ * once-per-process mirrors — all of it runs identically whether the batch
+ * leaves as a service-role PostgREST write (self-host) or as a `rig_sk_`-
+ * authenticated POST to api.modelrig.ai (hosted). That is not a tidiness
+ * preference: telemetry-ingestion-boundary.md §4 makes it a requirement, so
+ * that moving between self-host and hosted is a config change rather than a
+ * data-model change. `sinks.ts` holds the two transports; `ingest-protocol.ts`
+ * holds the one mapper both of them write rows through.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INTERVAL_MS = void 0;
+exports.buildExportedRouteMirrors = buildExportedRouteMirrors;
+exports.createTelemetryExporter = createTelemetryExporter;
+exports.buildLoadErrorBatch = buildLoadErrorBatch;
+const resolved_bundle_1 = require("../routes/resolved-bundle");
+const ingest_protocol_1 = require("./ingest-protocol");
+const sinks_1 = require("./sinks");
+/**
+ * Build the `routes` mirror payload from loaded bundles (Phase D, spec §13).
+ * Each `b` is ALREADY file-resolved — the loader inlined the schema + prompt
+ * files at createRig() and FAILED THERE (teaching RouteConfigError) if one was
+ * missing, so nothing unresolved reaches here and the gateway never needs the
+ * customer's filesystem (§13.1 rule 6). Lives here rather than in index.ts to
+ * keep that file under the LOC cap.
+ */
+function buildExportedRouteMirrors(bundles) {
+    return bundles.map((b) => {
+        const bundle = (0, resolved_bundle_1.resolveRouteBundle)(b);
+        return {
+            route: b.route,
+            version: b.version,
+            candidates: b.candidates.map((c) => ({ provider: c.provider, model: c.model })),
+            capture: b.capture,
+            bundle,
+            bundleSha: (0, resolved_bundle_1.hashResolvedBundle)(bundle),
+        };
+    });
+}
+const DEFAULT_BATCH_SIZE = 200;
+/** The flush cadence. Exported so the settings resolver (§1.5) can beat on the
+ * SAME interval — "refreshes on the exporter interval" without a second knob. */
+exports.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;
+/**
+ * Consecutive DETERMINISTIC failures on the SAME stuck batch before the
+ * exporter gives up and skips past it (E2 hardening Phase 2, spec §2.3.3).
+ * Five failures with the global exponential backoff between them is a
+ * multi-minute self-heal window — long enough for a still-deploying migration
+ * that adds a missing column to land, short enough to bound the wedge. A
+ * TRANSIENT failure never counts toward this, so an outage of any length can
+ * never trip it.
+ */
+const POISON_SKIP_THRESHOLD = 5;
+function toWireInference(row) {
+    return {
+        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,
+        // Cache accounting (WS-A) — always emitted by a current SDK. Requires the
+        // `inferences` cache columns (migration 00049) to exist server-side; apply
+        // 00049 BEFORE deploying this build (migrate-first), else the insert 4xx's
+        // and the exporter's poison-skip drops the batch after its self-heal window.
+        tokens_cache_write: row.tokensCacheWrite ?? 0,
+        tokens_cache_write_1h: row.tokensCacheWrite1h ?? 0,
+        cache_key: row.cacheKey ?? null,
+        prefix_fingerprint: row.prefixFingerprint ?? null,
+    };
+}
+function toWireRun(row) {
+    return {
+        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,
+    };
+}
+function toWireStep(row) {
+    return {
+        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,
+    };
+}
+function toWireArtifact(row) {
+    return {
+        id: row.id,
+        run_id: row.runId,
+        step_key: row.stepKey,
+        attempt_no: row.attemptNo,
+        task: row.task,
+        name: row.name,
+        type: row.type,
+        version: row.version,
+        supersedes_artifact_id: row.supersedesArtifactId,
+        declared_schema: row.declaredSchema ?? null,
+        fingerprint_cell: row.fingerprintCell,
+        content_ref: row.contentRef,
+        content_hash: row.contentHash,
+        content_bytes: row.contentBytes,
+        data_classification: row.dataClassification,
+        expires_at: row.expiresAt,
+        // Per-row scrub findings (E4 chunk 0) — spread-iff-present so a null/absent
+        // scrub never widens the batch beyond what older servers accept.
+        ...(row.scrub !== undefined && row.scrub !== null ? { scrub: row.scrub } : {}),
+    };
+}
+function toWireEdge(row) {
+    return { from_artifact_id: row.fromArtifactId, to_artifact_id: row.toArtifactId, kind: row.kind };
+}
+function toWireEvalCase(row) {
+    return {
+        id: row.id,
+        task: row.task,
+        source_artifact_id: row.sourceArtifactId,
+        corrected_artifact_id: row.correctedArtifactId,
+        origin: row.origin,
+        note: row.note,
+        created_by: row.createdBy,
+    };
+}
+function toWireEvaluation(row) {
+    return {
+        id: row.id,
+        artifact_id: row.artifactId,
+        run_id: row.runId,
+        evaluator: row.evaluator,
+        evaluator_kind: row.evaluatorKind,
+        score: row.score,
+        passed: row.passed,
+        label: row.label,
+        explanation: row.explanation,
+        created_by: row.createdBy,
+    };
+}
+function toWireFeedback(row) {
+    return {
+        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,
+        created_by: row.createdBy,
+        // Present only when the verdict names its own org. Omitted (not null) so
+        // that `stampBatch` can fall back to the exporter's tenant without having
+        // to distinguish "no org" from "explicitly no org".
+        ...(row.orgId !== null ? { org_id: row.orgId } : {}),
+    };
+}
+function createTelemetryExporter(store, config) {
+    const batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
+    const intervalMs = config.intervalMs ?? exports.DEFAULT_INTERVAL_MS;
+    const { sink, sourceId } = config;
+    // The wire version this exporter announces (spec §1.3). v2 iff the artifact
+    // namespace is active; otherwise v1, byte-identical to before v2 existed.
+    const wireVersion = config.artifacts === true ? ingest_protocol_1.INGEST_PROTOCOL_VERSION : ingest_protocol_1.INGEST_PROTOCOL_VERSION_V1;
+    let timer = null;
+    let flushing = false;
+    let skipsRemaining = 0;
+    let consecutiveFailures = 0;
+    let routesMirrored = false;
+    let manifestMirrored = false;
+    // Poison-pill state (E2 hardening Phase 2). Per stream key, the deterministic
+    // failure count for the CURRENTLY-STUCK batch — which is identified by its
+    // watermark, since the read is always "rows after W, limit N", so an
+    // unadvanced watermark IS the same batch. Reset the instant the watermark
+    // moves (a success OR a skip). `poisonSkipped` is the cumulative, per-stream
+    // count of rows dropped this way — the never-silent surface `stats()` reads.
+    const poisonState = new Map();
+    const poisonSkipped = {};
+    /**
+     * The once-per-process mirrors, folded into whichever batch goes out first.
+     *
+     * They ride along rather than travelling alone because in api mode a batch
+     * is an HTTP request, and three requests where one would do is three times
+     * the chance of a partial flush.
+     */
+    function pendingHeader() {
+        const header = {};
+        if (!routesMirrored && config.routes !== undefined && config.routes.length > 0) {
+            header.routes = config.routes.map((r) => ({
+                route: r.route,
+                version: r.version,
+                candidates: r.candidates,
+                capture: r.capture ?? false,
+                // Phase D: carry the resolved bundle + hash when the caller built them
+                // (index.ts always does; a caller that doesn't stays metadata-only).
+                ...(r.bundle !== undefined ? { bundle: r.bundle, bundle_sha: r.bundleSha } : {}),
+            }));
+        }
+        if (!manifestMirrored && config.manifest !== undefined && config.manifest !== null) {
+            header.manifest = {
+                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,
+                })),
+                // Follow-up #2: the describeConfigFailure shape, or [] on a clean load
+                // (which clears a stale failure from a prior broken deploy).
+                load_errors: [...(config.loadErrors ?? [])],
+            };
+        }
+        return header;
+    }
+    /** Mark the mirrors delivered — called ONLY after a confirmed send, so a
+     * failed first batch re-sends them rather than silently losing them. */
+    function markHeaderDelivered(header) {
+        if (header.routes !== undefined)
+            routesMirrored = true;
+        if (header.manifest !== undefined)
+            manifestMirrored = true;
+    }
+    /**
+     * Send one batch for a stream, applying the poison-pill state machine
+     * (spec §2.3.3). Returns:
+     *   "sent"  the send succeeded — the caller advances the watermark and marks
+     *           the header delivered.
+     *   "skip"  a deterministic poison was skipped after K failures — the caller
+     *           advances the watermark PAST this batch without it ever landing
+     *           (the rows are counted + logged, never retried).
+     * THROWS the underlying error when the caller must abort this flush and let
+     * the global backoff apply: a transient failure (retry forever, never counted)
+     * OR a deterministic one still inside its self-heal window (failCount < K).
+     *
+     * A poison in one stream never blocks another: the skip breaks only its own
+     * stuck batch, and the caller then continues to the next batch and the next
+     * stream (spec §2.3.3).
+     */
+    async function sendOrPoison(stream, watermark, rowCount, batch) {
+        try {
+            await sink.send(batch);
+            // A success advances the watermark → this stream is unstuck; drop its
+            // failure record so a later, unrelated batch starts fresh.
+            poisonState.delete(stream);
+            return "sent";
+        }
+        catch (err) {
+            // Anything that is not a classified SinkSendError is treated as TRANSIENT
+            // — we never poison-skip (drop data) on an error we cannot reason about.
+            const retriable = err instanceof sinks_1.SinkSendError ? err.retriable : true;
+            if (retriable) {
+                // Transient: do NOT touch failCount. Rethrow so the existing global
+                // backoff owns it and the stream retries forever (at-least-once).
+                throw err;
+            }
+            // Deterministic. Count failures against THIS stuck batch (keyed by W); a
+            // watermark that no longer matches means a different batch, so reset.
+            const prior = poisonState.get(stream);
+            const failCount = (prior !== undefined && prior.watermark === watermark ? prior.failCount : 0) + 1;
+            if (failCount < POISON_SKIP_THRESHOLD) {
+                // Self-heal window: rethrow (retry next flush, with backoff). A
+                // still-deploying migration that adds the missing column lands here.
+                poisonState.set(stream, { watermark, failCount });
+                throw err;
+            }
+            // POISON. Advance past this batch WITHOUT sending, count it, log LOUDLY,
+            // reset — the stream (and every later stream) keeps flowing.
+            poisonState.delete(stream);
+            poisonSkipped[stream] = (poisonSkipped[stream] ?? 0) + rowCount;
+            const status = err instanceof sinks_1.SinkSendError ? err.status : undefined;
+            console.warn(`[modelrig exporter] POISON-SKIP: stream "${stream}" batch at watermark ${watermark} ` +
+                `(${rowCount} row(s), status ${status ?? "network"}) was rejected deterministically ` +
+                `${POISON_SKIP_THRESHOLD}× running — advancing the watermark PAST it WITHOUT writing. ` +
+                `These rows are dropped and will NOT be retried; investigate the rejection and backfill.`);
+            return "skip";
+        }
+    }
+    async function flushOnce() {
+        let header = pendingHeader();
+        /**
+         * Drain one watermarked stream to exhaustion, batch by batch, through the
+         * poison-pill state machine. Every stream (inferences, feedback, runs,
+         * steps, artifacts, edges, evals) is the SAME at-least-once dance behind its
+         * own export_state key — factored here so the watermark/header/poison
+         * bookkeeping lives in exactly one place and no stream can drift from
+         * another. A "skip" advances the watermark past a poison batch WITHOUT
+         * having sent it; a "sent" advances it and delivers the once-per-flush
+         * header. Reassigning the captured `header` is intentional: the header rides
+         * the first CONFIRMED send, so a skipped (unsent) batch leaves it for the
+         * next one.
+         */
+        async function drainStream(streamKey, read, toSection) {
+            for (;;) {
+                const watermark = store.getExportWatermark(streamKey);
+                const pending = read(watermark, batchSize);
+                if (pending.length === 0)
+                    break;
+                const outcome = await sendOrPoison(streamKey, watermark, pending.length, {
+                    v: wireVersion,
+                    source: sourceId,
+                    ...header,
+                    ...toSection(pending.map((p) => p.row)),
+                });
+                if (outcome === "sent") {
+                    markHeaderDelivered(header);
+                    header = {};
+                }
+                // Advance past this batch on BOTH a send and a poison-skip — a skip's
+                // whole purpose is to move the watermark past the batch that will never
+                // land, so the stream keeps flowing (spec §2.3.3).
+                store.setExportWatermark(streamKey, pending[pending.length - 1].rowid);
+                if (pending.length < batchSize)
+                    break;
+            }
+        }
+        // Inferences past the watermark. The watermark advances after a confirmed
+        // send (at-least-once; the sink's upsert makes the duplicate harmless) OR a
+        // poison-skip (the batch will never land). Inferences also carry watermarkAt.
+        await drainStream(sourceId, (w, n) => store.readInferencesAfter(w, n), (rows) => ({
+            inferences: rows.map((row) => toWireInference(row)),
+            watermarkAt: new Date().toISOString(),
+        }));
+        // Feedback, runs, steps, artifacts, edges, evals: the same dance, each
+        // behind its own export_state key so no stream ever blocks another — a
+        // poison in one is skipped past without touching the rest.
+        await drainStream(`${sourceId}:feedback`, (w, n) => store.readFeedbackAfter(w, n), (rows) => ({
+            feedback: rows.map((row) => toWireFeedback(row)),
+        }));
+        // Execution graph (Expansion E2 chunk A) — ONLY when the artifact namespace
+        // is active. When artifacts are off these streams never drain and no
+        // runs/steps section is ever built (byte-identical to before v2 existed).
+        if (config.artifacts === true) {
+            await drainStream(`${sourceId}:runs`, (w, n) => store.readRunsAfter(w, n), (rows) => ({
+                runs: rows.map((row) => toWireRun(row)),
+            }));
+            await drainStream(`${sourceId}:steps`, (w, n) => store.readStepsAfter(w, n), (rows) => ({
+                steps: rows.map((row) => toWireStep(row)),
+            }));
+            // Artifact metadata (chunk B): rows live in the SEPARATE artifact store;
+            // watermarks live in the main store's export_state, keyed `:artifacts` etc.
+            const artStore = config.artifactStore;
+            if (artStore !== undefined) {
+                await drainStream(`${sourceId}:artifacts`, (w, n) => artStore.readArtifactsAfter(w, n), (rows) => ({
+                    artifacts: rows.map((row) => toWireArtifact(row)),
+                }));
+                await drainStream(`${sourceId}:edges`, (w, n) => artStore.readEdgesAfter(w, n), (rows) => ({
+                    artifact_edges: rows.map((row) => toWireEdge(row)),
+                }));
+                await drainStream(`${sourceId}:evals`, (w, n) => artStore.readEvaluationsAfter(w, n), (rows) => ({
+                    artifact_evaluations: rows.map((row) => toWireEvaluation(row)),
+                }));
+                // Promoted eval cases (E4 chunk A) — same at-least-once dance behind its
+                // own watermark key.
+                await drainStream(`${sourceId}:eval_cases`, (w, n) => artStore.readEvalCasesAfter(w, n), (rows) => ({
+                    eval_cases: rows.map((row) => toWireEvalCase(row)),
+                }));
+                // Post-flush hook (E4 chunk 0, flag 2): the artifacts stream is now
+                // confirmed exported (every drainStream above returned without throwing),
+                // so any content upload that 404'd racing its own metadata can re-attempt
+                // — the row is durable. Reached ONLY on a clean artifact flush; a poison
+                // rethrow above skips it, so we never retry content while metadata export
+                // is failing. Never throws (its rejection would be swallowed anyway).
+                if (config.onArtifactsFlushed !== undefined) {
+                    await config.onArtifactsFlushed();
+                }
+            }
+        }
+        // Envelopes: small table, full upsert each flush (no watermark). This send
+        // also carries any header the streams above never got the chance to — a rig
+        // that has routes but has not run yet must still appear in the console.
+        // A deterministic failure here poison-skips too (keyed by a synthetic 0
+        // watermark, since there is no cursor to advance): after K it is counted +
+        // logged and this flush moves on, rather than wedging the header forever.
+        const envelopes = store.listEnvelopes();
+        if (envelopes.length > 0 || Object.keys(header).length > 0) {
+            const outcome = await sendOrPoison(`${sourceId}:envelopes`, 0, Math.max(envelopes.length, 1), {
+                v: wireVersion,
+                source: sourceId,
+                ...header,
+                ...(envelopes.length > 0
+                    ? {
+                        envelopes: envelopes.map((e) => ({
+                            envelope_key: e.envelopeKey,
+                            budget_usd: e.budgetUsd,
+                            spent_usd: e.spentUsd,
+                            status: e.status,
+                        })),
+                    }
+                    : {}),
+            });
+            if (outcome === "sent")
+                markHeaderDelivered(header);
+        }
+    }
+    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.mode} sink flush failed (attempt ${consecutiveFailures}, ` +
+                `backing off ${skipsRemaining} intervals): ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            flushing = false;
+        }
+    }
+    return {
+        mode: sink.mode,
+        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();
+        },
+        stats() {
+            // A COPY, so a reader can never mutate the exporter's live counters.
+            return { poisonSkipped: { ...poisonSkipped } };
+        },
+    };
+}
+/**
+ * The one-shot manifest batch that carries a load-time config failure to the
+ * console (follow-up #2), for the case `createRig` throws BEFORE the exporter
+ * loop exists (a route bundle that fails to load never reaches the loop).
+ *
+ * It is a manifest-only batch: no inferences, no watermark. The manifest carries
+ * whatever `rig.yaml` could still provide (name/dimensions/contribution — the
+ * routes failing to load does not stop rig.yaml loading) plus the load errors;
+ * `serveability` is `[]` because it cannot be computed without loaded routes.
+ * A caller sends it fire-and-forget through the same sink the run loop uses.
+ */
+function buildLoadErrorBatch(sourceId, manifest, loadErrors) {
+    return {
+        // A manifest-only batch carries no artifact sections — announce v1 so it is
+        // accepted by any server vintage, even one predating protocol v2.
+        v: ingest_protocol_1.INGEST_PROTOCOL_VERSION_V1,
+        source: sourceId,
+        manifest: {
+            name: manifest?.name ?? sourceId,
+            dimensions: manifest?.dimensions ?? [],
+            contribution: manifest?.contribution ?? false,
+            serveability: [],
+            load_errors: [...loadErrors],
+        },
+    };
+}

package/dist/telemetry/health.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Observed-health aggregation — G-4 (observed-health/spec.md §3.1, §4.1).
+ *
+ * One home for the per-endpoint latency/TTFB percentile + error-rate + min-n
+ * math, shared by the live store reader (store.ts `readEndpointHealth`) and the
+ * observed-layer rollup (registry/build-observed.ts). Keeping the math here —
+ * not in run.ts (at the 700-LOC cap) — is deliberate.
+ *
+ * THE RIGINDEX WALL (spec §4.4, load-bearing): this module feeds routing +
+ * console surfaces ONLY. It must NEVER be imported by registry/build-leaderboard.ts
+ * or the matrix/Bradley-Terry path — production telemetry never produces rank
+ * (eval-methodology-and-rigindex.md:19). The import-guard test
+ * (health-rigindex-wall.test.ts) is the tripwire; do not weaken it.
+ */
+import type { ProviderId } from "../types/provider";
+/** Spec §4.1 example: below 20 samples, percentiles/error-rate surface as null. */
+export declare const DEFAULT_HEALTH_MIN_N = 20;
+export interface HealthPercentiles {
+    readonly p50: number;
+    readonly p90: number;
+    readonly p99: number;
+}
+/**
+ * Per-endpoint observed health over a rolling window. Percentiles + errorRate
+ * are `null` under the min-n gate (thin data must not read as a confident zero);
+ * `sampleN` is always reported so the surface can say "n too low", not "healthy".
+ */
+export interface EndpointHealth {
+    readonly provider: ProviderId;
+    readonly model: string;
+    readonly windowStart: string;
+    readonly sampleN: number;
+    readonly latencyMs: HealthPercentiles | null;
+    readonly ttfbMs: HealthPercentiles | null;
+    readonly errorRate: number | null;
+}
+/**
+ * The minimal row shape the aggregation needs. Both the local SQLite store and
+ * the hosted rollup can project their rows onto this, so the math is identical
+ * on both lanes (spec §3.1).
+ */
+export interface HealthInputRow {
+    readonly provider: string;
+    readonly model: string;
+    readonly ts: string;
+    readonly latency_ms: number;
+    readonly ttfb_ms: number | null;
+    readonly failure_class: string | null;
+}
+/**
+ * Nearest-rank percentile over a pre-sorted ascending array. Matches the
+ * convention already used by build-observed.ts so the two lanes agree.
+ */
+export declare function percentile(sorted: readonly number[], p: number): number | null;
+/**
+ * p50/p90/p99 over a set of values, dropping non-positive samples (a zero or
+ * negative latency/TTFB is a non-measurement, not a fast call). `null` when no
+ * positive sample remains.
+ */
+export declare function computePercentiles(values: readonly number[]): HealthPercentiles | null;
+export interface HealthWindowOptions {
+    readonly windowMinutes: number;
+    readonly minN: number;
+    /** Reference "now" in epoch ms — injected for deterministic windowing/tests. */
+    readonly now: number;
+}
+/**
+ * Aggregate windowed telemetry rows into per-(provider, model) health.
+ *
+ * Window: rows whose ts is within [now - windowMinutes, now]. Rows with an
+ * unparseable ts are dropped, never thrown on. Output is sorted by provider then
+ * model for deterministic rollups. Below `minN`, percentiles + errorRate are
+ * `null` (min-n gate) while `sampleN` is still reported.
+ */
+export declare function aggregateEndpointHealth(rows: readonly HealthInputRow[], opts: HealthWindowOptions): EndpointHealth[];
+//# sourceMappingURL=health.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/telemetry/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,mFAAmF;AACnF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,iBAAiB,GAAG,IAAI,CAStF;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,cAAc,EAAE,EAC/B,IAAI,EAAE,mBAAmB,GACxB,cAAc,EAAE,CAoClB"}

package/dist/telemetry/health.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Observed-health aggregation — G-4 (observed-health/spec.md §3.1, §4.1).
+ *
+ * One home for the per-endpoint latency/TTFB percentile + error-rate + min-n
+ * math, shared by the live store reader (store.ts `readEndpointHealth`) and the
+ * observed-layer rollup (registry/build-observed.ts). Keeping the math here —
+ * not in run.ts (at the 700-LOC cap) — is deliberate.
+ *
+ * THE RIGINDEX WALL (spec §4.4, load-bearing): this module feeds routing +
+ * console surfaces ONLY. It must NEVER be imported by registry/build-leaderboard.ts
+ * or the matrix/Bradley-Terry path — production telemetry never produces rank
+ * (eval-methodology-and-rigindex.md:19). The import-guard test
+ * (health-rigindex-wall.test.ts) is the tripwire; do not weaken it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_HEALTH_MIN_N = void 0;
+exports.percentile = percentile;
+exports.computePercentiles = computePercentiles;
+exports.aggregateEndpointHealth = aggregateEndpointHealth;
+/** Spec §4.1 example: below 20 samples, percentiles/error-rate surface as null. */
+exports.DEFAULT_HEALTH_MIN_N = 20;
+/**
+ * Nearest-rank percentile over a pre-sorted ascending array. Matches the
+ * convention already used by build-observed.ts so the two lanes agree.
+ */
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return null;
+    const index = Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length));
+    return sorted[index];
+}
+/**
+ * p50/p90/p99 over a set of values, dropping non-positive samples (a zero or
+ * negative latency/TTFB is a non-measurement, not a fast call). `null` when no
+ * positive sample remains.
+ */
+function computePercentiles(values) {
+    const sorted = values.filter((v) => v > 0).sort((a, b) => a - b);
+    if (sorted.length === 0)
+        return null;
+    return {
+        // percentile() only returns null for an empty array, ruled out above.
+        p50: percentile(sorted, 50),
+        p90: percentile(sorted, 90),
+        p99: percentile(sorted, 99),
+    };
+}
+// Grouping-key separator: neither a ProviderId nor a model id contains a pipe,
+// so the split back into (provider, model) is unambiguous.
+const KEY_SEP = "|";
+/**
+ * Aggregate windowed telemetry rows into per-(provider, model) health.
+ *
+ * Window: rows whose ts is within [now - windowMinutes, now]. Rows with an
+ * unparseable ts are dropped, never thrown on. Output is sorted by provider then
+ * model for deterministic rollups. Below `minN`, percentiles + errorRate are
+ * `null` (min-n gate) while `sampleN` is still reported.
+ */
+function aggregateEndpointHealth(rows, opts) {
+    const windowStartMs = opts.now - opts.windowMinutes * 60000;
+    const windowStart = new Date(windowStartMs).toISOString();
+    const byEndpoint = new Map();
+    for (const row of rows) {
+        const t = Date.parse(row.ts);
+        if (Number.isNaN(t) || t < windowStartMs || t > opts.now)
+            continue;
+        const key = `${row.provider}${KEY_SEP}${row.model}`;
+        const list = byEndpoint.get(key) ?? [];
+        list.push(row);
+        byEndpoint.set(key, list);
+    }
+    const out = [];
+    for (const [key, group] of byEndpoint) {
+        const [provider, model] = key.split(KEY_SEP);
+        const sampleN = group.length;
+        const gated = sampleN < opts.minN;
+        const errorCount = group.filter((r) => r.failure_class !== null).length;
+        out.push({
+            provider: provider,
+            model,
+            windowStart,
+            sampleN,
+            latencyMs: gated ? null : computePercentiles(group.map((r) => r.latency_ms)),
+            ttfbMs: gated
+                ? null
+                : computePercentiles(group.map((r) => r.ttfb_ms).filter((t) => t !== null)),
+            errorRate: gated ? null : errorCount / sampleN,
+        });
+    }
+    return out.sort((a, b) => a.provider === b.provider ? a.model.localeCompare(b.model) : a.provider.localeCompare(b.provider));
+}