modelrig 0.1.0 → 0.2.0

package/dist/telemetry/exporter-setup.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Build-and-start the telemetry exporter from resolved config. Extracted from
+ * index.ts (the SDK entrypoint) so that file stays under the LOC cap while
+ * Phase 2 adds the settings resolver + boot banner beside it — the exporter
+ * wiring is mechanical and has one caller, so it lives here rather than inline.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startTelemetryExporter = startTelemetryExporter;
+const node_os_1 = require("node:os");
+const exporter_1 = require("./exporter");
+const sinks_1 = require("./sinks");
+/**
+ * Construct the sink for the configured mode, wire the exporter, and start its
+ * flush loop. Returns the running exporter (the caller stops it on close()).
+ */
+function startTelemetryExporter(telemetry, exportConfig, extras) {
+    const sourceId = exportConfig.sourceId ?? (0, node_os_1.hostname)();
+    const sink = (0, sinks_1.buildTelemetrySink)(exportConfig, sourceId);
+    const exporter = (0, exporter_1.createTelemetryExporter)(telemetry, {
+        sink,
+        sourceId,
+        ...(exportConfig.batchSize !== undefined ? { batchSize: exportConfig.batchSize } : {}),
+        ...(exportConfig.intervalMs !== undefined ? { intervalMs: exportConfig.intervalMs } : {}),
+        routes: extras.routes,
+        manifest: extras.manifest,
+        serveability: extras.serveability,
+        artifacts: extras.artifactsEnabled,
+        ...(extras.artifactStore !== null ? { artifactStore: extras.artifactStore } : {}),
+        ...(extras.onArtifactsFlushed !== undefined ? { onArtifactsFlushed: extras.onArtifactsFlushed } : {}),
+    });
+    exporter.start();
+    return exporter;
+}

package/dist/telemetry/exporter.d.ts

@@ -17,8 +17,13 @@
  * holds the one mapper both of them write rows through.
  */
 import type { RigManifest } from "../routes/manifest";
+import type { ResolvedRouteBundle } from "../routes/resolved-bundle";
+import type { RouteBundle } from "../types/route";
 import type { ServeabilityWarning } from "../routes/serveability";
+import type { ConfigFailedState } from "../types/config-teaching";
+import type { IngestBatch } from "./ingest-protocol";
 import type { TelemetrySink } from "./sinks";
+import type { ArtifactStore } from "./artifact-store";
 import type { ExportableTelemetryStore } from "./store";
 export interface ExportedRouteMirror {
     readonly route: string;
@@ -30,7 +35,21 @@ export interface ExportedRouteMirror {
     /** Capture opt-in FLAG (Phase 3 WS4) — status only; capture content never
      * has a cloud surface. */
     readonly capture?: boolean;
+    /** Phase D (spec §13): the RESOLVED bundle (schema + prompt template inlined)
+     * the hosted gateway serves, and its content hash. Built by `index.ts` from
+     * the already-loaded (file-resolved) bundle via `resolveRouteBundle`. */
+    readonly bundle?: ResolvedRouteBundle;
+    readonly bundleSha?: string;
 }
+/**
+ * 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.
+ */
+export declare function buildExportedRouteMirrors(bundles: readonly RouteBundle[]): ExportedRouteMirror[];
 export interface ExporterConfig {
     /** Where batches go. `sinks.ts` builds one of these from config. */
     readonly sink: TelemetrySink;
@@ -47,6 +66,43 @@ export interface ExporterConfig {
      * XAI_API_KEY" instead of the fact living only in a boot log. Names only:
      * route, provider, model, env var. */
     readonly serveability?: readonly ServeabilityWarning[];
+    /** Load-time RouteConfigError diagnostics for THIS deployment (follow-up #2)
+     * — mirrored onto the manifest row so /setup's "Define your first route" step
+     * renders `failed` with what we looked for and found, instead of silence.
+     * Absent/empty means the load was clean, and sending `[]` clears a stale
+     * failure from a prior broken deploy. */
+    readonly loadErrors?: readonly ConfigFailedState[];
+    /**
+     * Artifact / execution-graph namespace active (Expansion E2). When true the
+     * exporter announces protocol v2 and ships the `runs`/`steps` streams; when
+     * false (the default) it announces v1 and ships nothing new — byte-identical
+     * to before v2 existed (spec §1.3/§1.4). The wire version is a property of the
+     * EXPORTER, not the batch: once artifacts are on, every batch is v2, so an old
+     * server 422s loudly rather than silently dropping artifact sections.
+     */
+    readonly artifacts?: boolean;
+    /** The local artifact-metadata buffer (chunk B). A SEPARATE handle from the
+     * telemetry store; present only when the namespace is enabled. Its rows ride
+     * the `:artifacts`/`:edges`/`:evals` watermark streams (watermarks live in the
+     * main store's export_state, rows are read from here). */
+    readonly artifactStore?: ArtifactStore;
+    /**
+     * Post-flush hook fired AFTER a confirmed export of the artifacts stream (E4
+     * chunk 0, flag 2). The artifact api wires this to `retryPendingContent`: a
+     * content upload that 404'd because it raced its own metadata export is now
+     * safe to re-attempt, because the metadata row just landed in the control
+     * plane. It runs only once the artifact drains have all returned (a throw in
+     * any of them aborts the flush before this, so "confirmed export" holds), and
+     * it must never throw — a rejection here is swallowed like any flush failure.
+     */
+    readonly onArtifactsFlushed?: () => Promise<void>;
+}
+/** Poison-pill counters (E2 hardening Phase 2, spec §2.3.5): per-stream row
+ * counts the exporter has SKIPPED past because the batch was rejected
+ * deterministically K times running. In-memory, per instance; empty `{}` on a
+ * healthy exporter. Mirrors the `IngestOutcome.reasons` map shape. */
+export interface ExporterStats {
+    readonly poisonSkipped: Readonly<Record<string, number>>;
 }
 export interface Exporter {
     /** Which lane this rig's telemetry is travelling in. Read by the boot
@@ -57,6 +113,25 @@ export interface Exporter {
     /** Flush pending rows now (used by tests and process-exit hooks). */
     flush(): Promise<void>;
     stop(): Promise<void>;
+    /** Poison batches this exporter has skipped past, per stream (additive; E2
+     * hardening Phase 2). The `/status` snapshot and any operator dashboard read
+     * it; a healthy exporter returns `{ poisonSkipped: {} }`. */
+    stats(): ExporterStats;
 }
+/** 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. */
+export declare const DEFAULT_INTERVAL_MS = 10000;
 export declare function createTelemetryExporter(store: ExportableTelemetryStore, config: ExporterConfig): Exporter;
+/**
+ * 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.
+ */
+export declare function buildLoadErrorBatch(sourceId: string, manifest: Pick<RigManifest, "name" | "dimensions" | "contribution"> | null, loadErrors: readonly ConfigFailedState[]): IngestBatch;
 //# sourceMappingURL=exporter.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"exporter.d.ts","sourceRoot":"","sources":["../../src/telemetry/exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAIlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1F;8BAC0B;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD;6EACyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC;;;0CAGsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACxD;AAED,MAAM,WAAW,QAAQ;IACvB;;oCAEgC;IAChC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAC;IAChC,KAAK,IAAI,IAAI,CAAC;IACd,qEAAqE;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAoDD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,wBAAwB,EAC/B,MAAM,EAAE,cAAc,GACrB,QAAQ,CAuKV"}
+{"version":3,"file":"exporter.d.ts","sourceRoot":"","sources":["../../src/telemetry/exporter.ts"],"names":[],"mappings":"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"}

package/dist/telemetry/exporter.js

@@ -18,13 +18,51 @@
  * 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;
-const DEFAULT_INTERVAL_MS = 10000;
+/** 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,
@@ -48,6 +86,92 @@ function toWireInference(row) {
         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) {
@@ -69,14 +193,25 @@ function toWireFeedback(row) {
 }
 function createTelemetryExporter(store, config) {
     const batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
-    const intervalMs = config.intervalMs ?? DEFAULT_INTERVAL_MS;
+    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.
      *
@@ -92,6 +227,9 @@ function createTelemetryExporter(store, config) {
                 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) {
@@ -106,6 +244,9 @@ function createTelemetryExporter(store, config) {
                     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;
@@ -118,56 +259,161 @@ function createTelemetryExporter(store, config) {
         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();
-        // Inferences past the watermark, in batches. The watermark advances ONLY
-        // after a confirmed send (at-least-once; the sink's upsert makes the
-        // duplicate harmless).
-        for (;;) {
-            const watermark = store.getExportWatermark(sourceId);
-            const pending = store.readInferencesAfter(watermark, batchSize);
-            if (pending.length === 0)
-                break;
-            await sink.send({
-                v: ingest_protocol_1.INGEST_PROTOCOL_VERSION,
-                source: sourceId,
-                ...header,
-                inferences: pending.map(({ row }) => toWireInference(row)),
-                watermarkAt: new Date().toISOString(),
-            });
-            markHeaderDelivered(header);
-            header = {};
-            store.setExportWatermark(sourceId, pending[pending.length - 1].rowid);
-            if (pending.length < batchSize)
-                break;
+        /**
+         * 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;
+            }
         }
-        // Feedback: same at-least-once watermark dance, behind its own export_state
-        // key so the two streams never block each other.
-        const feedbackSource = `${sourceId}:feedback`;
-        for (;;) {
-            const watermark = store.getExportWatermark(feedbackSource);
-            const pending = store.readFeedbackAfter(watermark, batchSize);
-            if (pending.length === 0)
-                break;
-            await sink.send({
-                v: ingest_protocol_1.INGEST_PROTOCOL_VERSION,
-                source: sourceId,
-                ...header,
-                feedback: pending.map(({ row }) => toWireFeedback(row)),
-            });
-            markHeaderDelivered(header);
-            header = {};
-            store.setExportWatermark(feedbackSource, 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. This send also carries
-        // any header the two loops above never got the chance to — a rig that has
-        // routes but has not run yet must still appear in the console.
+        // 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) {
-            await sink.send({
-                v: ingest_protocol_1.INGEST_PROTOCOL_VERSION,
+            const outcome = await sendOrPoison(`${sourceId}:envelopes`, 0, Math.max(envelopes.length, 1), {
+                v: wireVersion,
                 source: sourceId,
                 ...header,
                 ...(envelopes.length > 0
@@ -181,7 +427,8 @@ function createTelemetryExporter(store, config) {
                     }
                     : {}),
             });
-            markHeaderDelivered(header);
+            if (outcome === "sent")
+                markHeaderDelivered(header);
         }
     }
     async function guardedFlush() {
@@ -229,5 +476,35 @@ function createTelemetryExporter(store, config) {
             }
             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],
+        },
     };
 }