@autter/otlp-ingester 1.4.0 → 1.6.0

package/dist/sdk-versions.js

@@ -0,0 +1,167 @@
+import { createRequire } from "node:module";
+/**
+ * Which SDK (name + version) each service sends with, recorded cheaply so the
+ * Autter dashboard and `/v1/compat` consumers can spot version mismatches.
+ *
+ * Sources, in priority order:
+ * - OTLP resource `telemetry.distro.name` / `telemetry.distro.version` — set
+ *   by `@autter/runtime-node` and `@autter/runtime-next` (OTel semconv for
+ *   SDK distributions);
+ * - otherwise `telemetry.sdk.language` / `telemetry.sdk.version` — any plain
+ *   OpenTelemetry SDK (Python, Go, Java, …), recorded as
+ *   `opentelemetry-<language>`;
+ * - browser payloads: the `sdk` field sent by `@autter/runtime-browser`.
+ *
+ * Writes are deduplicated in memory: one row per (tenant, service,
+ * environment, sdk, version) per `refreshMs`, bounded map, fire-and-forget —
+ * a failed write is logged and never fails ingest.
+ */
+let cachedVersion = null;
+/** This ingester's own version (package.json — present in the npm package
+ * and the Docker image). */
+export function ingesterVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    try {
+        const pkg = createRequire(import.meta.url)("../package.json");
+        cachedVersion = typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        cachedVersion = "0.0.0";
+    }
+    return cachedVersion;
+}
+const CLEAN = /^[\w.@/+:-]{1,100}$/;
+function clean(value, max = 100) {
+    if (typeof value !== "string")
+        return "";
+    const trimmed = value.trim().slice(0, max);
+    return CLEAN.test(trimmed) ? trimmed : "";
+}
+/** SDK identity per OTLP resource. Reads only a handful of resource keys. */
+export function sdkSightingsFromOtlp(request) {
+    if (!request || typeof request !== "object")
+        return [];
+    const holders = [
+        ...(Array.isArray(request.resourceSpans) ? request.resourceSpans : []),
+        ...(Array.isArray(request.resourceMetrics) ? request.resourceMetrics : []),
+        ...(Array.isArray(request.resourceLogs) ? request.resourceLogs : []),
+    ].slice(0, 64);
+    const out = [];
+    for (const holder of holders) {
+        const attrs = holder?.resource?.attributes;
+        if (!Array.isArray(attrs))
+            continue;
+        const get = {};
+        for (const attr of attrs.slice(0, 256)) {
+            const key = attr?.key;
+            const value = attr?.value?.stringValue;
+            if (typeof key === "string" && typeof value === "string" && key.length < 64)
+                get[key] = value;
+        }
+        const service = clean(get["service.name"], 200);
+        if (!service)
+            continue;
+        const language = clean(get["telemetry.sdk.language"]);
+        let sdkName = clean(get["telemetry.distro.name"]);
+        let sdkVersion = clean(get["telemetry.distro.version"]);
+        if (!sdkName || !sdkVersion) {
+            sdkVersion = clean(get["telemetry.sdk.version"]);
+            sdkName = sdkVersion ? `opentelemetry-${language || "unknown"}` : "";
+        }
+        if (!sdkName || !sdkVersion)
+            continue;
+        out.push({
+            service,
+            environment: clean(get["deployment.environment.name"]) ||
+                clean(get["deployment.environment"]) ||
+                "production",
+            sdkName,
+            sdkVersion,
+            sdkLanguage: language,
+        });
+    }
+    return out;
+}
+export const BROWSER_SDK_NAME = "@autter/runtime-browser";
+export class SdkVersionTracker {
+    write;
+    lastWritten = new Map();
+    refreshMs;
+    maxKeys;
+    now;
+    onError;
+    lastErrorLog = 0;
+    constructor(write, options = {}) {
+        this.write = write;
+        this.refreshMs = options.refreshMs ?? 60 * 60 * 1000;
+        this.maxKeys = options.maxKeys ?? 10_000;
+        this.now = options.now ?? Date.now;
+        this.onError =
+            options.onError ??
+                ((err) => {
+                    // One line per minute at most: a missing table on a broken schema
+                    // must not flood the logs on every ingest request.
+                    if (this.now() - this.lastErrorLog < 60_000)
+                        return;
+                    this.lastErrorLog = this.now();
+                    console.warn("sdk version tracking write failed:", err?.message ?? err);
+                });
+    }
+    /** Fire-and-forget. Returns the write promise (resolved) for tests. */
+    observe(ctx, sightings) {
+        if (!sightings.length)
+            return Promise.resolve();
+        const now = this.now();
+        const rows = [];
+        const keys = [];
+        for (const sighting of sightings) {
+            const key = [
+                ctx.orgId,
+                ctx.repositoryId,
+                sighting.service,
+                sighting.environment,
+                sighting.sdkName,
+                sighting.sdkVersion,
+            ].join("\u0000");
+            const last = this.lastWritten.get(key);
+            if (last !== undefined && now - last < this.refreshMs)
+                continue;
+            if (keys.includes(key))
+                continue;
+            keys.push(key);
+            rows.push({ ...sighting, ingesterVersion: ingesterVersion(), seenAt: new Date(now) });
+        }
+        if (!rows.length)
+            return Promise.resolve();
+        if (this.lastWritten.size + keys.length > this.maxKeys)
+            this.lastWritten.clear();
+        for (const key of keys)
+            this.lastWritten.set(key, now);
+        return this.write(ctx, rows).catch((err) => {
+            // Let the next request retry instead of waiting out refreshMs.
+            for (const key of keys)
+                this.lastWritten.delete(key);
+            this.onError(err);
+        });
+    }
+}
+export function sdkVersionTableDDL(db, ttlDays = 90) {
+    return `CREATE TABLE IF NOT EXISTS ${db}.runtime_sdk_versions (
+		org_id String, repository_id String, service LowCardinality(String),
+		environment LowCardinality(String), sdk_name LowCardinality(String),
+		sdk_version String, sdk_language LowCardinality(String) DEFAULT '',
+		ingester_version String DEFAULT '', last_seen DateTime('UTC')
+	) ENGINE = ReplacingMergeTree(last_seen)
+	ORDER BY (org_id, repository_id, service, environment, sdk_name, sdk_version)
+	TTL last_seen + INTERVAL ${ttlDays} DAY`;
+}
+/** One row per ingester version (latest report wins); not tenant data. */
+export function ingesterInfoTableDDL(db) {
+    return `CREATE TABLE IF NOT EXISTS ${db}.runtime_ingester_info (
+		ingester_version String, schema_level String DEFAULT '',
+		report String DEFAULT '{}' CODEC(ZSTD(1)), reported_at DateTime('UTC')
+	) ENGINE = ReplacingMergeTree(reported_at)
+	ORDER BY ingester_version
+	TTL reported_at + INTERVAL 90 DAY`;
+}

package/dist/server.d.ts

@@ -7,5 +7,8 @@ export interface IngesterApp {
     store: ClickHouseStore;
     /** Present when AUTTER_SINK_URL is configured. */
     sink: SinkForwarder | null;
+    /** Record this ingester's version + schema level in ClickHouse (for the
+     * Autter dashboard). Called after the boot schema warm-up; throttled. */
+    reportIngesterInfo: () => Promise<void>;
 }
 export declare function createIngesterApp(config: IngesterConfig): IngesterApp;

package/dist/server.js

@@ -2,17 +2,32 @@ import express from "express";
 import { KeyResolver, RateLimiter } from "./auth.js";
 import { ClickHouseStore } from "./clickhouse.js";
 import { normalizeLatencyHistograms } from "./latency.js";
-import { deriveFields, fingerprintOccurrence, occurrenceIdFor, } from "./fingerprint.js";
+import { deriveFields, occurrenceIdFor } from "./fingerprint.js";
+import { occurrenceIdentity } from "./fingerprint-v3.js";
+import { parseStackFrames } from "./stack-frames.js";
+import { SourceMapCache, Symbolicator } from "./symbolicate.js";
+import { logPromotionCandidates, promotionLookups, promotionRollups, } from "./log-promotion.js";
 import { browserPayloadSchema, normalizeBrowserPayload, } from "./normalize-browser.js";
 import { normalizeMetrics, normalizeTraces, } from "./normalize-otlp.js";
 import { decodeMetricsRequest, decodeTraceRequest, decodeLogsRequest } from "./otlp-proto.js";
 import { normalizeLogs } from "./logs.js";
 import { decodeProfile } from "./profiles.js";
 import { normalizeMemoryMetrics, normalizePlatformEvent, platformEventSchema } from "./memory.js";
-import { validateSourceMap } from "./source-maps.js";
+import { validateSourceMap, validateSourceMapCheck } from "./source-maps.js";
 import { SinkForwarder } from "./sink.js";
+import { configureRedaction, scrubOccurrence } from "./redact.js";
+import { buildCompatReport, evaluateCompat, INGESTER_VERSION_HEADER, } from "./compat.js";
+import { MIGRATIONS } from "./migrations.js";
+import { BROWSER_SDK_NAME, ingesterVersion, SdkVersionTracker, sdkSightingsFromOtlp, } from "./sdk-versions.js";
+/** Re-report the ingester version at most this often (keeps the row inside
+ * its TTL for long-running ingesters). */
+const INGESTER_INFO_INTERVAL_MS = 6 * 60 * 60 * 1000;
 export function createIngesterApp(config) {
+    configureRedaction(config);
     const store = new ClickHouseStore(config);
+    // Browser JS frames are resolved through uploaded source maps before they
+    // are fingerprinted (frames-v3), with parsed maps cached per release+file.
+    const symbolicator = new Symbolicator((key) => store.lookupSourceMap(key), new SourceMapCache({ maxBytes: (config.sourceMapCacheMb ?? 64) * 1024 * 1024 }));
     // Fingerprinted occurrences feed the consumer's issue grouping, metric
     // points feed the request/error-rate rollups, LLM calls feed spend
     // watching. Delivery is at-least-once with bounded retries — see sink.ts.
@@ -20,8 +35,54 @@ export function createIngesterApp(config) {
     const keys = new KeyResolver(config);
     const serverRateLimiter = new RateLimiter(config.rateLimitPerMinute);
     const clientRateLimiter = new RateLimiter(config.clientRateLimitPerMinute);
+    // ClickHouse dedupe lookups made by /v1/logs promotion, per tenant. Far
+    // tighter than the request limit: each lookup is a query, not an insert.
+    const promotionLookupLimiter = new RateLimiter(config.promotionLookupsPerMinute ?? 30);
+    const version = ingesterVersion();
+    const sdkVersions = new SdkVersionTracker((ctx, rows) => store.insertSdkVersions(ctx, rows));
+    const allMigrationIds = MIGRATIONS.map((migration) => migration.id);
+    const compatReport = () => {
+        const schema = store.schemaStatus();
+        return buildCompatReport({
+            version,
+            schemaStatus: schema.status,
+            applied: schema.applied,
+            allMigrations: allMigrationIds,
+        });
+    };
+    let lastInfoReport = 0;
+    async function reportIngesterInfo() {
+        if (!store.configured)
+            return;
+        if (Date.now() - lastInfoReport < INGESTER_INFO_INTERVAL_MS)
+            return;
+        lastInfoReport = Date.now();
+        try {
+            // Only reached from boot and authenticated ingest, which run the
+            // (memoized) schema bootstrap anyway.
+            await store.ensureSchema();
+            const report = compatReport();
+            await store.insertIngesterInfo({ version, schemaLevel: report.schema.level, report });
+        }
+        catch (err) {
+            // Retry in a minute, not on every request.
+            lastInfoReport = Date.now() - INGESTER_INFO_INTERVAL_MS + 60_000;
+            console.warn("ingester info report failed:", err?.message ?? err);
+        }
+    }
+    /** Fire-and-forget after a successful ingest: never delays or fails it. */
+    function recordSdks(ctx, request) {
+        void sdkVersions.observe(ctx, sdkSightingsFromOtlp(request));
+        void reportIngesterInfo();
+    }
     const app = express();
     app.disable("x-powered-by");
+    // Every response names the ingester version, so SDKs (and the browser
+    // relay) learn it for free from responses they already receive.
+    app.use((_req, res, next) => {
+        res.setHeader(INGESTER_VERSION_HEADER, version);
+        next();
+    });
     app.use(express.raw({ limit: "1mb", type: ["application/x-pprof"] }));
     app.use("/v1/sourcemaps", express.json({ limit: "5mb" }));
     app.use(express.json({
@@ -49,6 +110,7 @@ export function createIngesterApp(config) {
         res.setHeader("access-control-allow-origin", "*");
         res.setHeader("access-control-allow-methods", "POST, OPTIONS");
         res.setHeader("access-control-allow-headers", "content-type, authorization, x-autter-key");
+        res.setHeader("access-control-expose-headers", INGESTER_VERSION_HEADER);
         res.setHeader("access-control-max-age", "86400");
         if (req.method === "OPTIONS") {
             res.status(204).end();
@@ -72,6 +134,36 @@ export function createIngesterApp(config) {
             res.status(503).json({ ok: false, clickhouse: "down", ...sinkStats });
         }
     });
+    /**
+     * Version compatibility (public, like /healthz; no tenant data): this
+     * ingester's version, its ClickHouse schema level, and every feature in
+     * the compat manifest with whether it is available here. Optional
+     * `?features=a,b&sdk=<name>@<version>` adds the evaluated `issues`.
+     * Never triggers schema DDL.
+     */
+    app.get("/v1/compat", (req, res) => {
+        const report = compatReport();
+        const features = typeof req.query.features === "string"
+            ? req.query.features.split(",").map((f) => f.trim()).filter(Boolean).slice(0, 50)
+            : [];
+        const sdkParam = typeof req.query.sdk === "string" ? req.query.sdk.slice(0, 120) : "";
+        const at = sdkParam.lastIndexOf("@");
+        const sdk = at > 0 ? { name: sdkParam.slice(0, at), version: sdkParam.slice(at + 1) } : null;
+        const body = features.length || sdk
+            ? {
+                ...report,
+                issues: evaluateCompat({
+                    features: features.length
+                        ? features
+                        : report.features.filter((f) => sdk && f.sdks[sdk.name]).map((f) => f.id),
+                    ingester: { version, schema: { status: report.schema.status, applied: report.schema.applied } },
+                    sdk,
+                }),
+            }
+            : report;
+        res.setHeader("cache-control", "no-store");
+        res.status(200).json(body);
+    });
     /** Auth + scope + rate limit; returns null (response sent) on failure. */
     async function authenticate(req, res, surface) {
         // A storage-less ingester must refuse, not accept-and-drop: exporters
@@ -117,21 +209,89 @@ export function createIngesterApp(config) {
         }
         return ctx;
     }
+    /**
+     * Structured frames for the frames-v3 identity and the platform's stack
+     * view: parsed innermost-first, then — browser only, where bundles are
+     * minified — resolved through the release's source maps. Symbolication
+     * never fails ingest (it falls back to the parsed frames).
+     */
+    async function framesFor(ctx, input) {
+        let frames;
+        try {
+            frames = parseStackFrames(input.stack);
+        }
+        catch (err) {
+            console.warn("stack parse failed — no frames:", err instanceof Error ? err.message : err);
+            return [];
+        }
+        if (input.source !== "browser" || frames.length === 0)
+            return frames;
+        return symbolicator.symbolicate(frames, {
+            orgId: ctx.orgId,
+            repositoryId: ctx.repositoryId,
+            release: input.release,
+            debugIds: input.debugIds ?? null,
+        });
+    }
     /** Ids are content-derived (occurrenceIdFor), NOT random: an exporter
      * that retries a batch — after a 503 from a partially-failed ClickHouse
      * write, or when only our 2xx got lost — must produce the same ids, so
      * the sink consumer's per-occurrence dedupe holds across transport
-     * retries and duplicated ClickHouse rows stay identifiable. */
-    function fingerprintAll(ctx, inputs) {
-        return inputs.map((input, index) => {
-            const fingerprint = fingerprintOccurrence(input);
+     * retries and duplicated ClickHouse rows stay identifiable.
+     *
+     * `fingerprint` / `fingerprintScheme` stay the legacy identity
+     * (message-v1 or code-v1) byte-for-byte; `fingerprints` carries every
+     * candidate (manual-v1, code-v1, frames-v3, message-v1) for the platform
+     * to resolve the issue from. */
+    async function fingerprintAll(ctx, inputs) {
+        return Promise.all(inputs.map(async (raw, index) => {
+            // Second line of defence, before fingerprinting, storage, and the
+            // sink (which feeds LLM fix generation): scrub secrets from the
+            // free-text fields old SDKs and third-party OTLP senders pass
+            // through verbatim. Attributes were already sanitised by the
+            // normalisers (sanitizeRuntimeContext).
+            const input = scrubOccurrence(raw);
+            const frames = await framesFor(ctx, input);
+            const identity = occurrenceIdentity(input, frames);
+            const { fingerprint, scheme } = identity.legacy;
+            // Debug ids only locate source maps; they are not stored or forwarded.
+            const { debugIds: _debugIds, ...stored } = input;
             return {
-                ...input,
+                ...stored,
                 occurrenceId: occurrenceIdFor(ctx, input, fingerprint, index),
                 fingerprint,
+                fingerprintScheme: scheme,
                 ...deriveFields(input),
+                ...(frames.length > 0 ? { frames } : {}),
+                fingerprints: identity.candidates,
+                ...(identity.record ? { fingerprintRecord: identity.record } : {}),
             };
-        });
+        }));
+    }
+    /** Fingerprint log-promotion candidates and drop the ones whose trace
+     * already produced an occurrence (in this batch, or within ±60 s). Ids
+     * are assigned BEFORE the lookup so they stay stable across retries
+     * whatever the lookup returns. */
+    async function promoteLogs(ctx, logs) {
+        const candidates = logPromotionCandidates(logs);
+        if (candidates.length === 0)
+            return [];
+        const fingerprinted = await fingerprintAll(ctx, candidates);
+        const seen = new Set();
+        const ownIds = fingerprinted.map((o) => o.occurrenceId);
+        for (const lookup of promotionLookups(candidates)) {
+            if (!promotionLookupLimiter.allow(`${ctx.orgId}:${ctx.repositoryId}`))
+                break;
+            try {
+                const found = await store.recentOccurrenceTraceIds(ctx, lookup.traceIds, lookup.from, lookup.to, ownIds);
+                for (const traceId of found)
+                    seen.add(traceId);
+            }
+            catch (err) {
+                console.warn("log promotion dedupe lookup failed — promoting without it:", err instanceof Error ? err.message : err);
+            }
+        }
+        return fingerprinted.filter((o) => !o.traceId || !seen.has(o.traceId));
     }
     function storageError(res, err) {
         console.error("clickhouse write failed:", err);
@@ -190,6 +350,8 @@ export function createIngesterApp(config) {
             res.status(400).json({ error: "invalid source map" });
             return;
         }
+        // Idempotent: the same release + path replaces the earlier row
+        // (ReplacingMergeTree), so CI retries and re-runs are harmless.
         try {
             await store.insertSourceMap(ctx, sourceMap);
             res.status(202).json({ accepted: true });
@@ -198,6 +360,24 @@ export function createIngesterApp(config) {
             storageError(res, err);
         }
     });
+    /** Which of these maps does this tenant already have? Lets
+     * `autter-runtime sourcemaps upload` skip unchanged maps (1.6.0+). */
+    app.post("/v1/sourcemaps/check", async (req, res) => {
+        const ctx = await authenticate(req, res, "otlp");
+        if (!ctx)
+            return;
+        const check = validateSourceMapCheck(req.body);
+        if (!check) {
+            res.status(400).json({ error: "invalid source map check" });
+            return;
+        }
+        try {
+            res.status(200).json({ present: await store.sourceMapsPresent(ctx, check) });
+        }
+        catch (err) {
+            storageError(res, err);
+        }
+    });
     /** ECS/Kubernetes event forwarders use the same server key as OTLP. */
     app.post("/v1/platform-events", async (req, res) => {
         const ctx = await authenticate(req, res, "otlp");
@@ -239,7 +419,7 @@ export function createIngesterApp(config) {
             request = req.body;
         }
         const { occurrences, spans, metricPoints, llmCalls } = normalizeTraces(request);
-        const fingerprinted = fingerprintAll(ctx, occurrences);
+        const fingerprinted = await fingerprintAll(ctx, occurrences);
         // ClickHouse has no cross-table transaction, so these four inserts can
         // partially commit. Recovery boundary: any failure → 503 → the exporter
         // retries the whole batch. Deterministic occurrence ids make the retry
@@ -261,6 +441,7 @@ export function createIngesterApp(config) {
             return;
         }
         sink?.enqueue(ctx, fingerprinted, metricPoints, llmCalls);
+        recordSdks(ctx, request);
         otlpSuccess(req, res);
     });
     app.post("/v1/logs", async (req, res) => {
@@ -268,22 +449,34 @@ export function createIngesterApp(config) {
         if (!ctx)
             return;
         let logs;
+        let logsRequest;
         try {
-            logs = normalizeLogs(req.is("application/x-protobuf") ? decodeLogsRequest(req.body) : req.body);
+            logsRequest = req.is("application/x-protobuf") ? decodeLogsRequest(req.body) : req.body;
+            logs = normalizeLogs(logsRequest);
         }
         catch {
             res.status(400).json({ error: "invalid OTLP logs payload" });
             return;
         }
+        // Logs are diagnostic evidence; exceptions and failed outcomes normally
+        // reach grouping through the trace path. The exception: logger-only /
+        // edge SDKs mark span-less error records `autter.capture.mode = "log"`,
+        // and those are promoted to occurrences here — see log-promotion.ts.
+        const promoted = await promoteLogs(ctx, logs);
+        const metricPoints = promotionRollups(promoted);
         try {
-            await store.insertLogs(ctx, logs);
+            await Promise.all([
+                store.insertLogs(ctx, logs),
+                store.insertOccurrences(ctx, promoted),
+                store.insertMetricPoints(ctx, metricPoints),
+            ]);
         }
         catch (err) {
             storageError(res, err);
             return;
         }
-        // Logs are diagnostic evidence. Exceptions and failed outcomes use the trace sink,
-        // so one operation does not create duplicate issues through two export paths.
+        sink?.enqueue(ctx, promoted, metricPoints);
+        recordSdks(ctx, logsRequest);
         otlpSuccess(req, res);
     });
     app.post("/v1/metrics", async (req, res) => {
@@ -315,6 +508,7 @@ export function createIngesterApp(config) {
             return;
         }
         sink?.enqueue(ctx, [], metricPoints);
+        recordSdks(ctx, request);
         otlpSuccess(req, res);
     });
     app.post("/v1/browser", async (req, res) => {
@@ -341,7 +535,7 @@ export function createIngesterApp(config) {
             return;
         }
         const { occurrences, metricPoints } = normalizeBrowserPayload(parsed.data);
-        const fingerprinted = fingerprintAll(ctx, occurrences);
+        const fingerprinted = await fingerprintAll(ctx, occurrences);
         try {
             await Promise.all([
                 store.insertOccurrences(ctx, fingerprinted),
@@ -353,6 +547,16 @@ export function createIngesterApp(config) {
             return;
         }
         sink?.enqueue(ctx, fingerprinted, metricPoints);
+        if (parsed.data.sdk) {
+            void sdkVersions.observe(ctx, [{
+                    service: parsed.data.service,
+                    environment: parsed.data.environment,
+                    sdkName: BROWSER_SDK_NAME,
+                    sdkVersion: parsed.data.sdk,
+                    sdkLanguage: "webjs",
+                }]);
+        }
+        void reportIngesterInfo();
         res.status(202).json({ accepted: fingerprinted.length });
     });
     // Body-parser errors (oversized/malformed JSON) → clean 4xx, not a stack.
@@ -370,5 +574,5 @@ export function createIngesterApp(config) {
         console.error("unhandled error:", err);
         res.status(500).json({ error: "internal error" });
     });
-    return { app, store, sink };
+    return { app, store, sink, reportIngesterInfo };
 }

package/dist/sink.d.ts

@@ -101,3 +101,16 @@ export declare class SinkForwarder {
     private scheduleWake;
     private send;
 }
+/**
+ * Wire shape of one occurrence (payload `version: 1`). 1.5.0 adds, all
+ * optional and omitted when absent: errorCode, why, fix, link, expected,
+ * requestId, traceId, route, method, statusCode, fingerprintScheme. The
+ * request-context four were previously spread as `null` when unknown and
+ * are now simply left out, matching the documented optional-string shape.
+ * 1.6.0 adds `frames` (innermost first, ≤ 50), `fingerprints` (every
+ * identity candidate, highest precedence first, ending with the legacy
+ * `fingerprint`) and `fingerprintRecord`; `fingerprint`/`fingerprintScheme`
+ * keep their legacy meaning. Older consumers ignore unknown keys, so the
+ * version stays 1.
+ */
+export declare function sinkOccurrence(o: RuntimeOccurrence): Record<string, unknown>;

package/dist/sink.js

@@ -108,10 +108,7 @@ export class SinkForwarder {
             batchId,
             orgId: ctx.orgId,
             repositoryId: ctx.repositoryId,
-            occurrences: occurrences.map((o) => ({
-                ...o,
-                occurredAt: o.occurredAt.toISOString(),
-            })),
+            occurrences: occurrences.map(sinkOccurrence),
             metrics: metricPoints.map((p) => ({
                 ...p,
                 bucketAt: p.bucketAt.toISOString(),
@@ -298,6 +295,42 @@ export class SinkForwarder {
         this.scheduleWake();
     }
 }
+/**
+ * Wire shape of one occurrence (payload `version: 1`). 1.5.0 adds, all
+ * optional and omitted when absent: errorCode, why, fix, link, expected,
+ * requestId, traceId, route, method, statusCode, fingerprintScheme. The
+ * request-context four were previously spread as `null` when unknown and
+ * are now simply left out, matching the documented optional-string shape.
+ * 1.6.0 adds `frames` (innermost first, ≤ 50), `fingerprints` (every
+ * identity candidate, highest precedence first, ending with the legacy
+ * `fingerprint`) and `fingerprintRecord`; `fingerprint`/`fingerprintScheme`
+ * keep their legacy meaning. Older consumers ignore unknown keys, so the
+ * version stays 1.
+ */
+export function sinkOccurrence(o) {
+    const { traceId, route, method, statusCode, errorCode, why, fix, link, expected, requestId, breadcrumbs, frames, fingerprints, fingerprintRecord, 
+    // Input-only: locates source maps, never leaves the ingester.
+    debugIds: _debugIds, ...rest } = o;
+    return {
+        ...rest,
+        occurredAt: o.occurredAt.toISOString(),
+        ...(traceId ? { traceId } : {}),
+        ...(route ? { route } : {}),
+        ...(method ? { method } : {}),
+        ...(statusCode != null ? { statusCode } : {}),
+        ...(errorCode ? { errorCode } : {}),
+        ...(why ? { why } : {}),
+        ...(fix ? { fix } : {}),
+        ...(link ? { link } : {}),
+        ...(expected ? { expected: true } : {}),
+        ...(requestId ? { requestId } : {}),
+        // 1.6.0: steps before the error, oldest first, ≤ 30.
+        ...(breadcrumbs?.length ? { breadcrumbs } : {}),
+        ...(frames?.length ? { frames } : {}),
+        ...(fingerprints?.length ? { fingerprints } : {}),
+        ...(fingerprintRecord ? { fingerprintRecord } : {}),
+    };
+}
 /** ISO range across every signal in the batch — the replay hint on drops. */
 function signalRange(occurrences, metricPoints, llmCalls) {
     const timestamps = [

package/dist/source-maps-lookup.d.ts

@@ -0,0 +1,31 @@
+import type { ClickHouseClient } from "@clickhouse/client";
+import { type SourceMapCheck } from "./source-maps.js";
+/**
+ * Source map lookups against `runtime_source_maps` (EI-13). Uploads come
+ * from `autter-runtime sourcemaps upload` / the bundler plugins, or any
+ * client of `POST /v1/sourcemaps`.
+ */
+export interface SourceMapKey {
+    orgId: string;
+    repositoryId: string;
+    release: string | null;
+    filename: string;
+    debugId?: string | null;
+}
+/** The stored map JSON for a minified file: by debug id first when given, else by release + filename (path only, no origin/query). Null when none. */
+export declare function lookupSourceMap(client: ClickHouseClient, database: string, key: SourceMapKey): Promise<string | null>;
+/**
+ * Re-uploading a map refreshes its 30-day TTL, so a map only counts as
+ * already uploaded when it was stored this recently; older ones are sent
+ * again and stay alive while the release is still being built.
+ */
+export declare const SOURCE_MAP_FRESH_DAYS = 7;
+/**
+ * Which check entries the tenant already has: same release, path, debug id
+ * and content hash, uploaded in the last SOURCE_MAP_FRESH_DAYS. Returns the
+ * indexes of `check.entries` that need no upload.
+ */
+export declare function presentSourceMaps(client: ClickHouseClient, database: string, tenant: {
+    orgId: string;
+    repositoryId: string;
+}, check: SourceMapCheck): Promise<number[]>;