modelrig 0.0.1 → 0.2.0

package/dist/telemetry/exporter-setup.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+import type { RigManifest } from "../routes/manifest";
+import type { ServeabilityWarning } from "../routes/serveability";
+import type { ApiExportConfig, DirectExportConfig } from "../config";
+import type { Exporter, ExportedRouteMirror } from "./exporter";
+import type { ArtifactStore } from "./artifact-store";
+import type { ExportableTelemetryStore } from "./store";
+export interface ExporterSetupExtras {
+    readonly routes: readonly ExportedRouteMirror[];
+    readonly manifest: RigManifest | null;
+    readonly serveability: readonly ServeabilityWarning[];
+    /** v2 wire + runs/steps/artifact streams only when the namespace is enabled. */
+    readonly artifactsEnabled: boolean;
+    readonly artifactStore: ArtifactStore | null;
+    /** E4 chunk 0: retry 404'd content after a confirmed artifacts flush. */
+    readonly onArtifactsFlushed?: () => Promise<void>;
+}
+/**
+ * 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()).
+ */
+export declare function startTelemetryExporter(telemetry: ExportableTelemetryStore, exportConfig: ApiExportConfig | DirectExportConfig, extras: ExporterSetupExtras): Exporter;
+//# sourceMappingURL=exporter-setup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exporter-setup.d.ts","sourceRoot":"","sources":["../../src/telemetry/exporter-setup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAErE,OAAO,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEhE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACtD,gFAAgF;IAChF,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7C,yEAAyE;IACzE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,wBAAwB,EACnC,YAAY,EAAE,eAAe,GAAG,kBAAkB,EAClD,MAAM,EAAE,mBAAmB,GAC1B,QAAQ,CAiBV"}

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

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+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;
+    readonly version: number;
+    readonly candidates: ReadonlyArray<{
+        readonly provider: string;
+        readonly model: string;
+    }>;
+    /** 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;
+    readonly sourceId: string;
+    readonly batchSize?: number;
+    readonly intervalMs?: number;
+    /** Loaded route bundles, mirrored to the `routes` table for the console. */
+    readonly routes?: readonly ExportedRouteMirror[];
+    /** Rig manifest, mirrored to the `rig_manifests` table for the console
+     * (dimension NAMES only — tag values never leave the telemetry rows). */
+    readonly manifest?: RigManifest | null;
+    /** Inert-candidate warnings for THIS deployment (F1) — mirrored onto the
+     * manifest row so console /setup can say "2 candidates inert here, set
+     * 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
+     * banner — WS1's lesson was that a mode nobody can observe gets asked
+     * about instead of answered. */
+    readonly mode: "direct" | "api";
+    start(): void;
+    /** 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

@@ -0,0 +1 @@
+{"version":3,"file":"exporter.d.ts","sourceRoot":"","sources":["../../src/telemetry/exporter.ts"],"names":[],"mappings":"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"}