modelrig 0.1.0 → 0.2.0

package/dist/telemetry/otel-normalize.js

@@ -0,0 +1,530 @@
+"use strict";
+/**
+ * OTLP-in v0 normalizer — Expansion E3-Harvest (spec §3). PURE: no I/O, no env,
+ * no imports from the exporter/sinks/server. The INBOUND sibling of `otel-map.ts`
+ * (which is the OUTBOUND our-rows → OTLP mapper). Foreign OTLP spans in →
+ * `runs` + attested `steps` out.
+ *
+ * ── SCOPE (spec §3.1): identity, structure, timing, status, model/provider,
+ * usage ONLY. ZERO content extraction — prompts/completions/messages in foreign
+ * spans are never read, never stored, never passed to the envelope. Retention-
+ * free default; content custody arrives with E2-C. This deletes ~60% of
+ * Langfuse's problem surface deliberately.
+ *
+ * ── VINTAGE HANDLING is pure NAME-UNION, not versioned dispatch (learnings
+ * §1.1, their proven approach), with our two divergences (spec §3.3):
+ *   (1) namespaced attributes outrank bare ones — `gen_ai.*`/`llm.*` are checked
+ *       BEFORE a bare `model`;
+ *   (2) provider IS normalized (Langfuse never reads provider on ingest), because
+ *       `model_key = provider/model` feeds our registry/priors/leaderboard —
+ *       recorded honestly, ending at "unknown", never guessed.
+ *
+ * The usage de-double-counting and the agent-span aggregate skip are adopted
+ * from OtelIngestionProcessor's generic extractor (learnings §1.2, read for
+ * pattern per §5.3 — implemented fresh here, no bodies copied).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOtlpTraces = normalizeOtlpTraces;
+exports.looksLikeLogsPayload = looksLikeLogsPayload;
+const node_crypto_1 = require("node:crypto");
+// ── value coercion (learnings §1.2, ported fresh) ────────────────────────────
+/** OTLP AnyValue → plain JS. Numeric strings coerce EXCEPT NaN/±Infinity which
+ * stay as their string form (invalid JSON must never enter the envelope). int64
+ * arrives as number | decimal-string | protobuf Long `{high,low}`. Unparseable
+ * → undefined, never NaN. */
+function coerceAnyValue(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v.stringValue === "string")
+        return v.stringValue;
+    if (v.boolValue !== undefined)
+        return v.boolValue;
+    if (v.doubleValue !== undefined) {
+        if (typeof v.doubleValue === "string") {
+            const parsed = Number(v.doubleValue);
+            return Number.isFinite(parsed) ? parsed : v.doubleValue;
+        }
+        return v.doubleValue;
+    }
+    if (v.intValue !== undefined)
+        return coerceIntValue(v.intValue);
+    if (isRecord(v.arrayValue) && Array.isArray(v.arrayValue.values)) {
+        return v.arrayValue.values.map(coerceAnyValue);
+    }
+    // kvlistValue / bytesValue are content-adjacent shapes — not read in v0.
+    return undefined;
+}
+function coerceIntValue(intValue) {
+    if (typeof intValue === "number")
+        return intValue;
+    if (typeof intValue === "string") {
+        const parsed = Number(intValue);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    if (isRecord(intValue)) {
+        const high = intValue.high;
+        const low = intValue.low;
+        if (high === 0)
+            return typeof low === "number" ? low : undefined;
+        if (high === -1 && low === -1)
+            return -1;
+        if (typeof high === "number" && typeof low === "number") {
+            return high * 2 ** 32 + low;
+        }
+    }
+    return undefined;
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Prototype-safe own-property check (the modelrig package targets < es2022, so
+ * `Object.hasOwn` is unavailable). Same contract: a key literally named
+ * "__proto__"/"toString" is NOT matched via the prototype chain. */
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+/** Flatten a span's KeyValue attributes into a `name → value` map. Content-only
+ * shapes (kvlist/bytes) yield undefined and are dropped. */
+function attrMap(attributes) {
+    // null-proto object (langfuse's flattened-key discipline): a key literally
+    // named "__proto__"/"constructor" becomes a normal own property instead of
+    // touching the prototype — no pollution, and hasOwn stays total.
+    const map = Object.create(null);
+    const keys = [];
+    for (const kv of attributes ?? []) {
+        if (typeof kv?.key !== "string")
+            continue;
+        const value = coerceAnyValue(kv.value);
+        if (value === undefined)
+            continue;
+        map[kv.key] = value;
+        keys.push(kv.key);
+    }
+    return { map, keys };
+}
+/** First present + string-coercible attribute across a priority chain. */
+function firstAttr(map, chain) {
+    for (const key of chain) {
+        if (hasOwn(map, key)) {
+            const v = map[key];
+            if (typeof v === "string" && v !== "")
+                return v;
+            if (typeof v === "number" || typeof v === "boolean")
+                return String(v);
+        }
+    }
+    return undefined;
+}
+// ── id coercion (spec §3.2: hex string | base64 | byte array | {high,low}) ───
+const HEX_RE = /^[0-9a-fA-F]+$/;
+/** Coerce an OTLP trace/span id to lowercase hex of `byteLen` bytes, or null. */
+function toHexId(v, byteLen) {
+    const hexLen = byteLen * 2;
+    if (typeof v === "string") {
+        if (v === "")
+            return null;
+        if (HEX_RE.test(v) && v.length === hexLen)
+            return v.toLowerCase();
+        // OTLP/JSON uses hex, but a protobuf-shaped emitter may base64 the bytes.
+        if (/^[A-Za-z0-9+/]+={0,2}$/.test(v)) {
+            try {
+                const hex = Buffer.from(v, "base64").toString("hex");
+                if (hex.length === hexLen && !/^0+$/.test(hex))
+                    return hex;
+            }
+            catch {
+                /* fallthrough */
+            }
+        }
+        // A hex string of the wrong length is not a valid id.
+        return null;
+    }
+    if (Array.isArray(v)) {
+        if (v.length !== byteLen || v.some((b) => typeof b !== "number"))
+            return null;
+        const hex = v.map((b) => (b & 0xff).toString(16).padStart(2, "0")).join("");
+        return /^0+$/.test(hex) ? null : hex;
+    }
+    return null;
+}
+// ── timestamp coercion (learnings §1.2 / spec §3.3) ──────────────────────────
+/** nanos (decimal string | number | protobuf {high,low}) → epoch ms, or null. */
+function nanoToMs(v) {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v / 1e6 : null;
+    if (typeof v === "string") {
+        if (!/^\d+$/.test(v))
+            return null;
+        try {
+            return Number(BigInt(v) / 1000000n);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (isRecord(v) && typeof v.high === "number" && typeof v.low === "number") {
+        const nanos = BigInt(v.high) * 2n ** 32n + BigInt(v.low >>> 0);
+        return Number(nanos / 1000000n);
+    }
+    return null;
+}
+// ── priority chains (spec §3.3, learnings §1.3) ──────────────────────────────
+// Namespaced FIRST (our divergence), bare `model` LAST. Langfuse's own
+// langfuse.observation.* keys are their namespace — dropped here.
+const MODEL_CHAIN = [
+    "gen_ai.response.model",
+    "ai.model.id",
+    "gen_ai.request.model",
+    "llm.response.model",
+    "llm.model_name",
+    "model",
+];
+/** Provider chain (spec §3.3): honest, ending at "unknown", NEVER guessed. Note
+ * scope names (Vercel "ai", OpenLLMetry) imply nothing about the provider, so
+ * there is deliberately no scope→provider guess. */
+const PROVIDER_CHAIN = [
+    "gen_ai.provider.name",
+    "gen_ai.system", // deprecated
+    "ai.model.provider",
+];
+// Episode chain (spec §3.3). ⚠ ARCHITECT FLAG (P2 — do not silently change the
+// frozen spec): `runs` has an index on (org_id, episode_key). The LIVE ModelRig
+// DB has it NON-unique (`idx_runs_org_episode`), so mapping a trace-spanning
+// `gen_ai.conversation.id` to episode_key is safe there. But the migration 00029
+// FILE declares it UNIQUE (`uq_runs_org_episode`); a fresh env built from files
+// would then 23505 when two attested traces (each its own run) share one
+// conversation id — breaking the whole batch. Either the file must drop UNIQUE,
+// or attested runs must not populate episode_key. Left spec-compliant pending
+// the architect's ruling; flagged in verification.md.
+const EPISODE_CHAIN = ["modelrig.run.id", "gen_ai.conversation.id"];
+const ENVIRONMENT_CHAIN = ["deployment.environment.name", "deployment.environment"];
+const PIPELINE_RESOURCE_CHAIN = ["service.name"];
+/** AI-SDK agent spans whose aggregate usage duplicates their child model span
+ * (learnings §1.2 — skip model/usage/cost entirely). */
+const AGENT_OPERATIONS = new Set(["invoke_agent", "agent_step"]);
+// ── usage extraction + de-double-counting (learnings §1.2, ported fresh) ─────
+function extractUsage(map) {
+    const raw = {};
+    for (const key of Object.keys(map)) {
+        if ((key.startsWith("gen_ai.usage.") && key !== "gen_ai.usage.cost") ||
+            key.startsWith("llm.token_count.")) {
+            const stripped = key.replace("gen_ai.usage.", "").replace("llm.token_count.", "");
+            const value = Number(map[key]);
+            if (!Number.isNaN(value))
+                raw[stripped] = value;
+        }
+    }
+    if (Object.keys(raw).length === 0)
+        return undefined;
+    const inputTokens = raw["prompt_tokens"] ?? raw["input_tokens"] ?? raw["prompt"];
+    const outputTokens = raw["completion_tokens"] ?? raw["output_tokens"] ?? raw["completion"];
+    const totalTokens = raw["total_tokens"] ?? raw["total"];
+    const cacheReadTokens = raw["cache_read.input_tokens"] ??
+        raw["cache_read_input_tokens"] ??
+        raw["cache_read_tokens"] ??
+        raw["details.cache_read_tokens"] ??
+        raw["details.cache_read_input_tokens"] ??
+        raw["prompt_details.cache_read"] ??
+        raw["input_cached_tokens"];
+    const cacheCreationTokens = raw["cache_creation.input_tokens"] ??
+        raw["cache_creation_input_tokens"] ??
+        raw["cache_write_tokens"] ??
+        raw["details.cache_write_tokens"] ??
+        raw["details.cache_creation_input_tokens"] ??
+        raw["prompt_details.cache_write"] ??
+        raw["input_cache_creation"];
+    const outputReasoningTokens = raw["reasoning.output_tokens"] ?? raw["completion_details.reasoning"];
+    const outputAudioTokens = raw["completion_details.audio"];
+    // Buckets that were consumed by the alias resolution above are not re-emitted
+    // under their raw names; everything else passes through (details.* flattened).
+    const consumed = new Set([
+        "prompt_tokens", "input_tokens", "prompt",
+        "completion_tokens", "output_tokens", "completion",
+        "total_tokens", "total",
+        "cache_read.input_tokens", "cache_read_input_tokens", "cache_read_tokens",
+        "details.cache_read_tokens", "details.cache_read_input_tokens",
+        "prompt_details.cache_read", "input_cached_tokens",
+        "cache_creation.input_tokens", "cache_creation_input_tokens", "cache_write_tokens",
+        "details.cache_write_tokens", "details.cache_creation_input_tokens",
+        "prompt_details.cache_write", "input_cache_creation",
+        "reasoning.output_tokens", "completion_details.reasoning", "completion_details.audio",
+    ]);
+    const usage = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (consumed.has(key))
+            continue;
+        usage[key.startsWith("details.") ? key.replace("details.", "") : key] = value;
+    }
+    // De-double-counting (adopted verbatim): input −= cache buckets; output −=
+    // reasoning + audio; floored at 0. Cached/reasoning tokens are INCLUDED in the
+    // provider's prompt/completion totals, so subtracting yields the billable net.
+    if (inputTokens !== undefined) {
+        usage.input = Math.max(inputTokens - (cacheReadTokens ?? 0) - (cacheCreationTokens ?? 0), 0);
+    }
+    if (outputTokens !== undefined) {
+        usage.output = Math.max(outputTokens - (outputReasoningTokens ?? 0) - (outputAudioTokens ?? 0), 0);
+    }
+    if (totalTokens !== undefined)
+        usage.total = totalTokens;
+    if (cacheReadTokens !== undefined)
+        usage.input_cached_tokens = cacheReadTokens;
+    if (cacheCreationTokens !== undefined)
+        usage.input_cache_creation = cacheCreationTokens;
+    if (outputReasoningTokens !== undefined)
+        usage.output_reasoning_tokens = outputReasoningTokens;
+    if (outputAudioTokens !== undefined)
+        usage.output_audio_tokens = outputAudioTokens;
+    return usage;
+}
+// ── classification registry (spec §3.3: priority-ordered) ────────────────────
+// openinference.span.kind → gen_ai.operation.name → tool-attr presence →
+// model-presence fallback → "span".
+function classify(map) {
+    const openinference = firstAttr(map, ["openinference.span.kind"]);
+    if (openinference !== undefined)
+        return openinference.toLowerCase();
+    const operation = firstAttr(map, ["gen_ai.operation.name"]);
+    if (operation !== undefined)
+        return operation;
+    // Genuine tool signals only. `traceloop.entity.name` is NOT one — OpenLLMetry
+    // stamps it on every span (workflow/task/tool/llm alike), so treating it as a
+    // tool marker would misclassify chat spans.
+    if (hasOwn(map, "gen_ai.tool.name") || hasOwn(map, "tool.name")) {
+        return "execute_tool";
+    }
+    if (firstAttr(map, MODEL_CHAIN) !== undefined)
+        return "chat";
+    return "span";
+}
+// ── structure helpers ────────────────────────────────────────────────────────
+const WS_RE = /\s+/g;
+/** span name → step_key: trimmed, whitespace-collapsed, length-capped, never
+ * empty (the step PK forbids it). */
+function toStepKey(name) {
+    const raw = typeof name === "string" ? name.trim().replace(WS_RE, " ") : "";
+    if (raw === "")
+        return "span";
+    return raw.slice(0, 200);
+}
+/** 32-hex trace id → canonical UUID string (runs.id is uuid; 16 bytes ≡ a UUID).
+ * A trace id that is not 16 bytes gets a deterministic UUID derived from it. */
+function traceIdToRunUuid(traceHex) {
+    const hex = traceHex.length === 32 ? traceHex : (0, node_crypto_1.createHash)("sha256").update(traceHex).digest("hex").slice(0, 32);
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+function bump(drops, reason, by = 1) {
+    drops[reason] = (drops[reason] ?? 0) + by;
+}
+/** Resolve a span's start/end. One edge missing → copy the other; both missing
+ * → `now`. Each fallback counted (spec §3.3). */
+function resolveTiming(span, nowMs, drops) {
+    const startNano = span.startTimeUnixNano ?? span.start_time_unix_nano;
+    const endNano = span.endTimeUnixNano ?? span.end_time_unix_nano;
+    let startMs = nanoToMs(startNano);
+    let endMs = nanoToMs(endNano);
+    if (startMs === null && endMs === null) {
+        bump(drops, "ts_both_missing");
+        startMs = nowMs;
+        endMs = nowMs;
+    }
+    else if (startMs === null) {
+        bump(drops, "ts_copied_edge");
+        startMs = endMs;
+    }
+    else if (endMs === null) {
+        bump(drops, "ts_copied_edge");
+        endMs = startMs;
+    }
+    return {
+        startedAt: new Date(startMs).toISOString(),
+        endedAt: endMs === null ? null : new Date(endMs).toISOString(),
+        startMs,
+    };
+}
+// ── the normalizer ───────────────────────────────────────────────────────────
+/**
+ * Normalize a decoded OTLP `TracesData` structure into runs + attested steps.
+ * Total and defensive: a malformed span is dropped-and-counted, never thrown.
+ * `nowMs` is injected so callers/tests are deterministic (default Date.now()).
+ */
+function normalizeOtlpTraces(data, nowMs = Date.now()) {
+    const drops = {};
+    const scopeNames = new Set();
+    const steps = [];
+    let spanCount = 0;
+    const resourceSpans = readResourceSpans(data);
+    const runs = new Map();
+    for (const rs of resourceSpans) {
+        const resourceAttrs = attrMap(rs.resource?.attributes).map;
+        const scopeSpansList = rs.scopeSpans ?? rs.scope_spans ?? [];
+        for (const ss of scopeSpansList) {
+            const scopeName = typeof ss.scope?.name === "string" ? ss.scope.name : "";
+            const scopeVersion = typeof ss.scope?.version === "string" ? ss.scope.version : null;
+            if (scopeName !== "")
+                scopeNames.add(scopeName);
+            for (const span of ss.spans ?? []) {
+                spanCount += 1;
+                const traceHex = toHexId(span.traceId ?? span.trace_id, 16);
+                const spanHex = toHexId(span.spanId ?? span.span_id, 8);
+                // A span with no usable identity is exactly the logs-exporter symptom;
+                // it cannot become an attested step (the steps CHECK needs span_id).
+                if (traceHex === null || spanHex === null) {
+                    bump(drops, "bad_otlp_span");
+                    continue;
+                }
+                const { map, keys } = attrMap(span.attributes);
+                const timing = resolveTiming(span, nowMs, drops);
+                const runId = traceIdToRunUuid(traceHex);
+                // ── envelope (identity/structure/usage ONLY; NO content) ──
+                const operation = classify(map);
+                const isAgentAggregate = AGENT_OPERATIONS.has(operation);
+                const model = isAgentAggregate ? null : (firstAttr(map, MODEL_CHAIN) ?? null);
+                const provider = isAgentAggregate
+                    ? "unknown"
+                    : (firstAttr(map, PROVIDER_CHAIN) ?? "unknown");
+                const usage = isAgentAggregate ? undefined : extractUsage(map);
+                const envelope = {
+                    model,
+                    provider,
+                    operation,
+                    ...(usage !== undefined ? { usage } : {}),
+                    scope: { name: scopeName, version: scopeVersion },
+                };
+                // Count attributes we did not map into structure/identity/usage — honest
+                // in v0 where there is no metadata store to pass them into (spec §3.3).
+                countUnmapped(keys, map, drops);
+                const statusCode = coerceIntValue(span.status?.code);
+                const failureClass = statusCode === 2 ? "attested_error" : null;
+                const step = {
+                    run_id: runId,
+                    step_key: toStepKey(span.name),
+                    attempt_no: 1, // assigned per (trace, step_key) below
+                    task: null,
+                    provenance: "attested",
+                    inference_id: null,
+                    span_trace_id: traceHex,
+                    span_id: spanHex,
+                    started_at: timing.startedAt,
+                    ended_at: timing.endedAt,
+                    failure_class: failureClass,
+                    attested: envelope,
+                };
+                // ── run correlate (upserted shallow, merge=true — idempotent) ──
+                const acc = runs.get(runId);
+                const endMs = timing.endedAt !== null ? Date.parse(timing.endedAt) : timing.startMs;
+                const episodeKey = firstAttr(map, EPISODE_CHAIN) ?? null;
+                if (acc === undefined) {
+                    runs.set(runId, {
+                        runId,
+                        traceHex,
+                        pipeline: firstAttr(resourceAttrs, PIPELINE_RESOURCE_CHAIN) ?? (scopeName !== "" ? scopeName : "otlp"),
+                        environment: firstAttr(resourceAttrs, ENVIRONMENT_CHAIN) ?? null,
+                        episodeKey,
+                        minStartMs: timing.startMs,
+                        maxEndMs: endMs,
+                        anyError: failureClass !== null,
+                        pending: [{ step, stepKey: step.step_key, startMs: timing.startMs }],
+                    });
+                }
+                else {
+                    acc.minStartMs = Math.min(acc.minStartMs, timing.startMs);
+                    acc.maxEndMs = Math.max(acc.maxEndMs, endMs);
+                    acc.anyError = acc.anyError || failureClass !== null;
+                    if (acc.episodeKey === null && episodeKey !== null)
+                        acc.episodeKey = episodeKey;
+                    acc.pending.push({ step, stepKey: step.step_key, startMs: timing.startMs });
+                }
+            }
+        }
+    }
+    const runRows = [];
+    for (const acc of runs.values()) {
+        runRows.push({
+            id: acc.runId,
+            pipeline: acc.pipeline,
+            pipeline_version: null,
+            environment: acc.environment,
+            episode_key: acc.episodeKey,
+            started_at: new Date(acc.minStartMs).toISOString(),
+            ended_at: new Date(acc.maxEndMs).toISOString(),
+            // The trace has completed (we only see finished spans); status is honest.
+            status: acc.anyError ? "failed" : "succeeded",
+        });
+        // Assign attempt_no per (run, step_key): repeated same-named spans become
+        // attempts in start-time (then span-id) order — deterministic within a
+        // trace. v0 limitation: a trace split across batches is not deduped (no
+        // seen-store); one trace = one batch is the common, correct case.
+        const perKey = new Map();
+        for (const p of acc.pending) {
+            const list = perKey.get(p.stepKey) ?? [];
+            list.push({ step: p.step, startMs: p.startMs });
+            perKey.set(p.stepKey, list);
+        }
+        for (const list of perKey.values()) {
+            list.sort((a, b) => a.startMs !== b.startMs
+                ? a.startMs - b.startMs
+                : (a.step.span_id ?? "") < (b.step.span_id ?? "")
+                    ? -1
+                    : 1);
+            list.forEach(({ step }, i) => steps.push({ ...step, attempt_no: i + 1 }));
+        }
+    }
+    return { runs: runRows, steps, drops, spanCount, scopeNames: [...scopeNames] };
+}
+/** The keys the envelope consumes structurally — everything else on a span is an
+ * "unmapped attribute" in v0 (counted, not stored). */
+function countUnmapped(keys, map, drops) {
+    let unmapped = 0;
+    for (const key of keys) {
+        if (key.startsWith("gen_ai.usage.") ||
+            key.startsWith("llm.token_count.") ||
+            MODEL_CHAIN.includes(key) ||
+            PROVIDER_CHAIN.includes(key) ||
+            EPISODE_CHAIN.includes(key) ||
+            key === "gen_ai.operation.name" ||
+            key === "openinference.span.kind") {
+            continue;
+        }
+        unmapped += 1;
+    }
+    void map;
+    if (unmapped > 0)
+        bump(drops, "unmapped_attribute", unmapped);
+}
+/** Read `resourceSpans` (camel or snake) from a decoded body, tolerating shape. */
+function readResourceSpans(data) {
+    if (!isRecord(data))
+        return [];
+    const rs = data.resourceSpans ?? data.resource_spans;
+    return Array.isArray(rs) ? rs : [];
+}
+/**
+ * Logs-exporter detection (learnings §1.2). ResourceLogs and ResourceSpans share
+ * protobuf field numbers, so a logs exporter pointed at the traces endpoint
+ * decodes as id-less "spans". A JSON logs body carries `resourceLogs` outright.
+ * Returns true when the body is a logs payload that must be rejected 400.
+ */
+function looksLikeLogsPayload(data) {
+    if (!isRecord(data))
+        return false;
+    if (Array.isArray(data.resourceLogs) || Array.isArray(data.resource_logs)) {
+        return true;
+    }
+    const resourceSpans = readResourceSpans(data);
+    if (resourceSpans.length === 0)
+        return false;
+    // Every span across the payload lacking BOTH ids is the decoded-logs symptom.
+    let sawSpan = false;
+    for (const rs of resourceSpans) {
+        for (const ss of rs.scopeSpans ?? rs.scope_spans ?? []) {
+            for (const span of ss.spans ?? []) {
+                sawSpan = true;
+                const hasTrace = toHexId(span.traceId ?? span.trace_id, 16) !== null;
+                const hasSpan = toHexId(span.spanId ?? span.span_id, 8) !== null;
+                if (hasTrace || hasSpan)
+                    return false;
+            }
+        }
+    }
+    return sawSpan;
+}

package/dist/telemetry/otlp-emitter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * OTLP span emitter — E1 (spec §2.3, §4). A SIBLING of the control-plane
+ * exporter, not a sink inside it: it reads the same `inferences` table behind
+ * its OWN watermark (`${sourceId}:otlp`), so the OTLP stream and the
+ * control-plane export never block or drain each other — exactly the pattern
+ * the feedback stream already uses (`:feedback`).
+ *
+ * ── DOCTRINE CLONED FROM exporter.ts (verbatim, on purpose) ───────────────
+ * Fire-and-forget from the run loop; at-least-once with idempotent span ids
+ * (otel-map derives them deterministically, so a re-emit after a crash is a
+ * no-op at the sink); the watermark advances ONLY after a confirmed 2xx;
+ * sink errors are swallowed-and-logged with exponential skip backoff; the
+ * interval timer is `unref()`ed so telemetry never keeps a process alive.
+ *
+ * ── OFF BY DEFAULT ────────────────────────────────────────────────────────
+ * This module is only constructed when `MODELRIG_OTLP_ENDPOINT` is set
+ * (config.ts). No endpoint ⇒ no emitter ⇒ zero behaviour change (spec §6a).
+ *
+ * ── C2 (never leak credentials) ───────────────────────────────────────────
+ * `cfg.headers` may carry sink auth (e.g. Langfuse Basic auth) and `endpoint`
+ * itself may embed a token. NEITHER is ever logged or put in an error. Failure
+ * text is run through the shared secret scrubber before it reaches a warning.
+ */
+import type { OtlpConfig } from "../config";
+import type { ExportableTelemetryStore } from "./store";
+export interface OtlpEmitterConfig {
+    /** OTLP/HTTP traces endpoint, e.g. `https://cloud.langfuse.com/api/public/otel/v1/traces`. */
+    readonly endpoint: string;
+    /** Sink auth headers (`k=v` pairs from MODELRIG_OTLP_HEADERS). May be empty. */
+    readonly headers: Record<string, string>;
+    /** Watermark namespace — the rig's source instance. Key is `${sourceId}:otlp`. */
+    readonly sourceId: string;
+    readonly batchSize?: number;
+    readonly intervalMs?: number;
+    /** Injectable for tests; defaults to global fetch. */
+    readonly fetchFn?: typeof fetch;
+}
+export interface OtlpEmitter {
+    start(): void;
+    /** Flush pending rows now (tests + process-exit hooks). */
+    flushNow(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function createOtlpEmitter(store: ExportableTelemetryStore, config: OtlpEmitterConfig): OtlpEmitter;
+/**
+ * Construct + start the OTLP emitter iff an endpoint is configured, else null
+ * (spec §6a). Lives here rather than index.ts so createRig's wiring stays one
+ * line and this file keeps the LOC cap on index.ts — the same reason
+ * `buildTelemetrySink` moved to sinks.ts.
+ */
+export declare function startOtlpEmitterIfConfigured(store: ExportableTelemetryStore, otlp: OtlpConfig | null | undefined, sourceId: string): OtlpEmitter | null;
+//# sourceMappingURL=otlp-emitter.d.ts.map

package/dist/telemetry/otlp-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-emitter.d.ts","sourceRoot":"","sources":["../../src/telemetry/otlp-emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAKxD,MAAM,WAAW,iBAAiB;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,IAAI,IAAI,CAAC;IACd,2DAA2D;IAC3D,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAQD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,wBAAwB,EAC/B,MAAM,EAAE,iBAAiB,GACxB,WAAW,CAgGb;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,wBAAwB,EAC/B,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACnC,QAAQ,EAAE,MAAM,GACf,WAAW,GAAG,IAAI,CASpB"}