@autter/otlp-ingester 1.3.4 → 1.5.0

package/dist/compat.js

@@ -0,0 +1,219 @@
+/**
+ * Version compatibility between Autter Runtime SDKs, this ingester and its
+ * ClickHouse schema — the single source of truth.
+ *
+ * `compat-manifest.json` lists every feature that needs a minimum ingester
+ * version, a ClickHouse migration, a dedicated ingest route, or a minimum SDK
+ * version. Everything else derives from it:
+ *
+ * - the ingester serves it (evaluated against its own version and applied
+ *   migrations) at `GET /v1/compat`;
+ * - `@autter/runtime-node` / `@autter/runtime-next` bundle this file at build
+ *   time to warn once when an enabled feature needs a newer ingester, and to
+ *   power `npx @autter/runtime-node doctor`;
+ * - the Python adapter (`adapters/python/compat.py`) embeds a copy that a
+ *   parity test keeps identical.
+ *
+ * This module is dependency-free and side-effect-free on purpose: it is
+ * bundled into the Node SDK. Keep it that way.
+ *
+ * Adding a feature: append an entry to compat-manifest.json with the first
+ * ingester release that handles it, the migrations it writes to, its route
+ * (if it has its own), and the first SDK release that emits it. The
+ * consistency test in compat.test.ts checks ids, migrations and routes.
+ */
+import manifestJson from "./compat-manifest.json" with { type: "json" };
+export const COMPAT_MANIFEST = manifestJson;
+export const INGESTER_PACKAGE = "@autter/otlp-ingester";
+/** Response header carrying the ingester version on every ingest response. */
+export const INGESTER_VERSION_HEADER = "x-autter-ingester-version";
+// ── versions ────────────────────────────────────────────────────────────
+/** [major, minor, patch, isPrerelease] or null when unparsable. */
+function parseVersion(version) {
+    if (typeof version !== "string")
+        return null;
+    const match = /^v?(\d{1,6})\.(\d{1,6})\.(\d{1,6})(-[0-9A-Za-z.-]+)?/.exec(version.trim());
+    if (!match)
+        return null;
+    return [
+        Number(match[1]),
+        Number(match[2]),
+        Number(match[3]),
+        // A prerelease sorts before its release: 1.4.0-rc.1 < 1.4.0.
+        match[4] ? 0 : 1,
+    ];
+}
+/** Semver-ish comparison; null when either side is unparsable. */
+export function compareVersions(a, b) {
+    const left = parseVersion(a);
+    const right = parseVersion(b);
+    if (!left || !right)
+        return null;
+    for (let i = 0; i < 4; i++) {
+        if (left[i] !== right[i])
+            return left[i] < right[i] ? -1 : 1;
+    }
+    return 0;
+}
+/** True/false when comparable, null when the version is unknown/unparsable. */
+export function versionAtLeast(version, minimum) {
+    if (!version)
+        return null;
+    const result = compareVersions(version, minimum);
+    return result === null ? null : result >= 0;
+}
+export function featureById(id, manifest = COMPAT_MANIFEST) {
+    return manifest.features.find((feature) => feature.id === id);
+}
+/** Features the given browser payload event types belong to. */
+export function featuresForBrowserEvents(types, manifest = COMPAT_MANIFEST) {
+    const wanted = new Set(types);
+    return manifest.features
+        .filter((feature) => feature.browserEvents?.some((type) => wanted.has(type)))
+        .map((feature) => feature.id);
+}
+export function ingesterUpgradeHint(manifest = COMPAT_MANIFEST) {
+    return `Upgrade the ingester: ${manifest.upgrade.ingester}. See ${manifest.docs}`;
+}
+function sdkUpgradeHint(pkg, manifest) {
+    return `Upgrade the SDK: ${manifest.upgrade.sdk.replace("{package}", pkg)}. See ${manifest.docs}`;
+}
+/**
+ * Every incompatibility for the features in use. Unknown is never an issue:
+ * when the ingester version can't be determined (and a legacy route probe
+ * didn't prove a route missing) nothing is reported, so the check has no
+ * false positives.
+ */
+export function evaluateCompat(input) {
+    const manifest = input.manifest ?? COMPAT_MANIFEST;
+    const issues = [];
+    const seen = new Set();
+    for (const id of input.features) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        const feature = featureById(id, manifest);
+        if (!feature)
+            continue;
+        const sdkMin = input.sdk ? feature.sdks[input.sdk.name] : undefined;
+        if (input.sdk && sdkMin && versionAtLeast(input.sdk.version, sdkMin) === false) {
+            const fix = sdkUpgradeHint(input.sdk.name, manifest);
+            issues.push({
+                feature: id,
+                title: feature.title,
+                kind: "sdk_too_old",
+                component: input.sdk.name,
+                required: sdkMin,
+                actual: input.sdk.version,
+                message: `${feature.title} needs ${input.sdk.name} >= ${sdkMin}; yours is ${input.sdk.version}. ${fix}`,
+                fix,
+            });
+        }
+        const ingester = input.ingester;
+        if (!ingester)
+            continue;
+        const fix = ingesterUpgradeHint(manifest);
+        const atLeast = versionAtLeast(ingester.version, feature.ingester);
+        if (atLeast === false) {
+            issues.push({
+                feature: id,
+                title: feature.title,
+                kind: "ingester_too_old",
+                component: INGESTER_PACKAGE,
+                required: feature.ingester,
+                actual: ingester.version,
+                message: `${feature.title} needs ingester >= ${feature.ingester}; yours is ${ingester.version}. ${fix}`,
+                fix,
+            });
+            continue;
+        }
+        if (ingester.version === null &&
+            feature.route &&
+            ingester.routes?.[feature.route] === false) {
+            const actual = "1.4.0 or older (no /v1/compat)";
+            issues.push({
+                feature: id,
+                title: feature.title,
+                kind: "ingester_too_old",
+                component: INGESTER_PACKAGE,
+                required: feature.ingester,
+                actual,
+                message: `${feature.title} needs ingester >= ${feature.ingester}; yours is ${actual} and has no ${feature.route} route, so this data is dropped. ${fix}`,
+                fix,
+            });
+            continue;
+        }
+        const schema = ingester.schema;
+        if (atLeast && schema && feature.migrations.length) {
+            const applied = new Set(schema.applied);
+            const missing = feature.migrations.filter((m) => !applied.has(m));
+            if (schema.status === "failed" || (schema.status === "ready" && missing.length)) {
+                const schemaFix = "Check the ingester's CLICKHOUSE_URL/credentials and its logs, then restart it so the boot migrations run. " +
+                    `See ${manifest.docs}`;
+                const what = missing.length ? missing.join(", ") : feature.migrations.join(", ");
+                issues.push({
+                    feature: id,
+                    title: feature.title,
+                    kind: "schema_not_applied",
+                    component: INGESTER_PACKAGE,
+                    required: feature.migrations.join(", "),
+                    actual: schema.status === "failed" ? "migrations failed" : `missing ${what}`,
+                    message: `${feature.title} needs ClickHouse migration ${what}, which ingester ${ingester.version} has not applied (schema ${schema.status}). ${schemaFix}`,
+                    fix: schemaFix,
+                });
+            }
+        }
+    }
+    return issues;
+}
+export function buildCompatReport(input) {
+    const manifest = input.manifest ?? COMPAT_MANIFEST;
+    const applied = new Set(input.applied);
+    const appliedOrdered = input.allMigrations.filter((id) => applied.has(id));
+    return {
+        ingester: { name: INGESTER_PACKAGE, version: input.version },
+        schema: {
+            status: input.schemaStatus,
+            level: appliedOrdered[appliedOrdered.length - 1] ?? "",
+            latest: input.allMigrations[input.allMigrations.length - 1] ?? "",
+            applied: appliedOrdered,
+        },
+        features: manifest.features.map((feature) => {
+            const ingesterSupported = versionAtLeast(input.version, feature.ingester) !== false;
+            const missingMigrations = feature.migrations.filter((m) => !applied.has(m));
+            return {
+                ...feature,
+                ingesterSupported,
+                missingMigrations,
+                available: ingesterSupported &&
+                    (feature.migrations.length === 0 ||
+                        (input.schemaStatus === "ready" && missingMigrations.length === 0)),
+            };
+        }),
+        manifestVersion: manifest.manifestVersion,
+        docs: manifest.docs,
+        upgrade: manifest.upgrade,
+    };
+}
+/** IngesterCompatInfo from a /v1/compat response body (defensive: it's network input). */
+export function ingesterInfoFromReport(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const report = body;
+    const version = report.ingester?.version;
+    if (typeof version !== "string" || !parseVersion(version))
+        return null;
+    const schema = report.schema;
+    const statuses = ["ready", "pending", "failed", "unconfigured"];
+    return {
+        version,
+        ...(schema && statuses.includes(schema.status) && Array.isArray(schema.applied)
+            ? {
+                schema: {
+                    status: schema.status,
+                    applied: schema.applied.filter((id) => typeof id === "string"),
+                },
+            }
+            : {}),
+    };
+}

package/dist/config.d.ts

@@ -32,10 +32,27 @@ export interface IngesterConfig {
     rateLimitPerMinute: number;
     /** Per-key requests per minute for publishable client keys. */
     clientRateLimitPerMinute: number;
+    /** ClickHouse dedupe lookups per tenant per minute for /v1/logs promotion. */
+    promotionLookupsPerMinute?: number;
     /** Retention, overridable per deployment. */
     occurrenceTtlDays: number;
     spanTtlDays: number;
     metricsTtlDays: number;
     llmCallTtlDays: number;
+    /**
+     * runtime_logs retention (LOG_TTL_DAYS, default 14). Request summaries are
+     * always kept (never sampled), so this is the main volume knob. Applied to
+     * fresh tables by the baseline and to existing ones at boot.
+     */
+    logTtlDays: number;
+    /**
+     * Extra regex sources scrubbed from stored/forwarded free text and
+     * attribute values, and extra regex sources for sensitive attribute
+     * keys — on top of the built-in secret/PII patterns (see redact.ts).
+     * Env: AUTTER_REDACT_VALUE_PATTERNS / AUTTER_REDACT_KEY_PATTERNS (JSON
+     * arrays of strings).
+     */
+    redactValuePatterns?: string[];
+    redactKeyPatterns?: string[];
 }
 export declare function loadConfig(): IngesterConfig;

package/dist/config.js

@@ -5,6 +5,20 @@ function intEnv(name, fallback) {
     const value = Number.parseInt(raw, 10);
     return Number.isFinite(value) && value > 0 ? value : fallback;
 }
+/** JSON array of regex sources; invalid input fails startup loudly rather
+ * than silently running without the operator's extra patterns. */
+function patternListEnv(name) {
+    const raw = process.env[name];
+    if (!raw)
+        return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed) || !parsed.every((p) => typeof p === "string")) {
+        throw new Error(`${name} must be a JSON array of regex source strings`);
+    }
+    for (const source of parsed)
+        new RegExp(source);
+    return parsed;
+}
 function parseIngestKeys(raw) {
     if (!raw)
         return [];
@@ -42,12 +56,16 @@ export function loadConfig() {
         maxBodyBytes: intEnv("MAX_BODY_BYTES", 1024 * 1024),
         rateLimitPerMinute: intEnv("RATE_LIMIT_PER_MINUTE", 300),
         clientRateLimitPerMinute: intEnv("CLIENT_RATE_LIMIT_PER_MINUTE", 120),
+        promotionLookupsPerMinute: intEnv("PROMOTION_LOOKUPS_PER_MINUTE", 30),
         occurrenceTtlDays: intEnv("OCCURRENCE_TTL_DAYS", 14),
         spanTtlDays: intEnv("SPAN_TTL_DAYS", 7),
         metricsTtlDays: intEnv("METRICS_TTL_DAYS", 90),
         // LLM calls keep the metrics horizon, not the span one — cost trends
         // need months, and per-call volume is small next to HTTP spans.
         llmCallTtlDays: intEnv("LLM_CALL_TTL_DAYS", 90),
+        logTtlDays: intEnv("LOG_TTL_DAYS", 14),
+        redactValuePatterns: patternListEnv("AUTTER_REDACT_VALUE_PATTERNS"),
+        redactKeyPatterns: patternListEnv("AUTTER_REDACT_KEY_PATTERNS"),
     };
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(config.clickhouseDatabase)) {
         throw new Error(`Invalid CLICKHOUSE_DATABASE name: ${config.clickhouseDatabase}`);

package/dist/context.d.ts

@@ -0,0 +1,19 @@
+/** Bounded, defensive privacy boundary for custom telemetry from any OTLP SDK. */
+export declare function sanitizeRuntimeContext(input: unknown): Record<string, unknown>;
+export interface OtlpValue {
+    stringValue?: string;
+    intValue?: string | number;
+    doubleValue?: number;
+    boolValue?: boolean;
+    arrayValue?: {
+        values?: OtlpValue[];
+    };
+    kvlistValue?: {
+        values?: OtlpAttribute[];
+    };
+}
+export interface OtlpAttribute {
+    key?: string;
+    value?: OtlpValue;
+}
+export declare function decodeOtlpAttributes(attributes: OtlpAttribute[] | undefined): Record<string, unknown>;

package/dist/context.js

@@ -0,0 +1,102 @@
+import { isSensitiveKey, scrubText } from "./redact.js";
+/** Bounded, defensive privacy boundary for custom telemetry from any OTLP SDK. */
+export function sanitizeRuntimeContext(input) {
+    let budget = 512;
+    const seen = new WeakSet();
+    // Shared secret/PII patterns (redact.ts), then drop URL query strings
+    // and fragments outright — whitelist-style privacy for free text.
+    const scrub = (value) => scrubText(value)
+        // Query strings: procedural (a `[^\s?#]+[?#]` regex is quadratic on
+        // long runs of URLs without a query).
+        .replace(/https?:\/\/[^\s]*/gi, (url) => {
+        const rest = url.slice(url.indexOf("://") + 3);
+        const cut = rest.search(/[?#]/);
+        return cut <= 0 ? url : url.slice(0, url.length - rest.length + cut);
+    });
+    const visit = (value, key, depth) => {
+        if (--budget < 0 || depth > 6)
+            return "[truncated]";
+        if (/__proto__|constructor|prototype/i.test(key))
+            return undefined;
+        const usage = 
+        // Numeric token COUNTS (incl. the AI rollup's cache_read_tokens) are
+        // usage, not secrets.
+        /(?:^|\.)(?:input|output|total|prompt|completion|cache_read|cache_creation)_?tokens$/i.test(key) &&
+            typeof value === "number" &&
+            Number.isFinite(value) &&
+            value >= 0;
+        if (!usage && key && isSensitiveKey(key))
+            return "[redacted]";
+        if (typeof value === "string") {
+            // Serialized custom context crosses the same privacy boundary as nested values.
+            if (/^\s*[\[{]/.test(value)) {
+                try {
+                    return visit(JSON.parse(value), key, depth + 1);
+                }
+                catch {
+                    /* plain text */
+                }
+            }
+            const text = /(?:url|path|route|target)$/i.test(key)
+                ? value.split(/[?#]/)[0]
+                : value;
+            // Cut before scrubbing so scrub work is bounded by the stored size;
+            // the slack keeps a secret straddling the cut whole for the scrubber.
+            const limit = /stack/i.test(key) ? 32000 : 2048;
+            return scrub(text.slice(0, limit + 512)).slice(0, limit);
+        }
+        if (typeof value === "number")
+            return Number.isFinite(value) ? value : undefined;
+        if (typeof value === "boolean" || value === null)
+            return value;
+        if (!value || typeof value !== "object")
+            return undefined;
+        if (seen.has(value))
+            return "[circular]";
+        seen.add(value);
+        if (Array.isArray(value))
+            return value.slice(0, 64).map((v) => visit(v, key, depth + 1));
+        const result = {};
+        for (const [k, v] of Object.entries(value).slice(0, 128)) {
+            const safe = visit(v, k, depth + 1);
+            if (safe !== undefined)
+                result[k.slice(0, 200)] = safe;
+        }
+        return result;
+    };
+    const result = visit(input, "", 0);
+    return result && typeof result === "object" && !Array.isArray(result)
+        ? result
+        : {};
+}
+export function decodeOtlpAttributes(attributes) {
+    const decode = (v, depth = 0) => {
+        if (!v || depth > 6)
+            return undefined;
+        if (v.stringValue !== undefined)
+            return v.stringValue;
+        if (v.intValue !== undefined)
+            return Number(v.intValue);
+        if (v.doubleValue !== undefined)
+            return v.doubleValue;
+        if (v.boolValue !== undefined)
+            return v.boolValue;
+        if (v.arrayValue)
+            return (v.arrayValue.values ?? [])
+                .slice(0, 64)
+                .map((value) => decode(value, depth + 1));
+        if (v.kvlistValue)
+            return Object.fromEntries((v.kvlistValue.values ?? [])
+                .slice(0, 128)
+                .filter((a) => a.key && !/^(?:__proto__|constructor|prototype)$/.test(a.key))
+                .map((a) => [a.key, decode(a.value, depth + 1)]));
+        return undefined;
+    };
+    return sanitizeRuntimeContext(Object.fromEntries((attributes ?? [])
+        .slice()
+        .sort((a, b) => Number(/^autter\.(?:operation|event)\./.test(b.key ?? "")) -
+        Number(/^autter\.(?:operation|event)\./.test(a.key ?? "")))
+        .slice(0, 128)
+        .filter((a) => a.key && !/^(?:__proto__|constructor|prototype)$/.test(a.key))
+        .map((a) => [a.key, decode(a.value)])));
+}

package/dist/error-fields.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Declared error metadata on the wire (span/event attributes, log
+ * attributes, browser context keys):
+ *
+ *   autter.error.code      string matching CODE_PATTERN (≤80) — grouping key
+ *   autter.error.why       declared cause   (≤1000 chars)
+ *   autter.error.fix       declared remedy  (≤1000 chars)
+ *   autter.error.link      docs link        (http(s) only, ≤500 chars)
+ *   autter.error.expected  boolean — expected business failure
+ *   autter.request.id      request id joining the error to its summary
+ *
+ * Every field is optional and validated independently: a bad value is
+ * dropped on its own and never rejects the signal. Values are lifted onto
+ * dedicated occurrence fields (and columns) instead of living only in the
+ * attributes JSON, because the generic context sanitiser rewrites URLs
+ * (query AND fragment stripped) — the declared link keeps its #anchor here.
+ */
+export declare const REQUEST_ID_PATTERN: RegExp;
+export interface DeclaredErrorFields {
+    errorCode?: string;
+    why?: string;
+    fix?: string;
+    link?: string;
+    expected?: boolean;
+    requestId?: string;
+}
+type AttributeSource = Map<string, string> | Record<string, unknown> | null | undefined;
+/**
+ * http(s) only; credentials and query string removed (a docs link never
+ * needs them), fragment kept. Over-long links are dropped rather than
+ * truncated — a cut URL is a broken link.
+ */
+export declare function declaredLink(value: unknown): string | undefined;
+export declare function validRequestId(value: unknown): string | undefined;
+/**
+ * Lift the declared fields from one or more attribute sources; the first
+ * source carrying a key wins (e.g. exception event before its span).
+ * Returns only the fields that are present and valid.
+ */
+export declare function liftErrorFields(...sources: AttributeSource[]): DeclaredErrorFields;
+export {};

package/dist/error-fields.js

@@ -0,0 +1,103 @@
+import { sanitizeRuntimeContext } from "./context.js";
+import { validErrorCode } from "./fingerprint.js";
+/**
+ * Declared error metadata on the wire (span/event attributes, log
+ * attributes, browser context keys):
+ *
+ *   autter.error.code      string matching CODE_PATTERN (≤80) — grouping key
+ *   autter.error.why       declared cause   (≤1000 chars)
+ *   autter.error.fix       declared remedy  (≤1000 chars)
+ *   autter.error.link      docs link        (http(s) only, ≤500 chars)
+ *   autter.error.expected  boolean — expected business failure
+ *   autter.request.id      request id joining the error to its summary
+ *
+ * Every field is optional and validated independently: a bad value is
+ * dropped on its own and never rejects the signal. Values are lifted onto
+ * dedicated occurrence fields (and columns) instead of living only in the
+ * attributes JSON, because the generic context sanitiser rewrites URLs
+ * (query AND fragment stripped) — the declared link keeps its #anchor here.
+ */
+export const REQUEST_ID_PATTERN = /^[\w.-]{8,128}$/;
+const EMAIL_RE = /(?<![A-Z0-9._%+-])[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+function lookup(sources, key) {
+    for (const source of sources) {
+        if (!source)
+            continue;
+        const value = source instanceof Map ? source.get(key) : source[key];
+        if (value !== undefined && value !== null && value !== "")
+            return value;
+    }
+    return undefined;
+}
+/** First source whose value for `key` passes `valid` (an invalid value on
+ * the exception event must not hide a valid one on its span). */
+function lookupValid(sources, key, valid) {
+    for (const source of sources) {
+        const value = valid(lookup([source], key));
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+/** Free text through the same scrubber as custom context, then capped. */
+function declaredText(value, max) {
+    if (typeof value !== "string")
+        return undefined;
+    const text = sanitizeRuntimeContext({ text: value.trim() }).text;
+    return typeof text === "string" && text ? text.slice(0, max) : undefined;
+}
+/**
+ * http(s) only; credentials and query string removed (a docs link never
+ * needs them), fragment kept. Over-long links are dropped rather than
+ * truncated — a cut URL is a broken link.
+ */
+export function declaredLink(value) {
+    if (typeof value !== "string")
+        return undefined;
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return undefined;
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    const link = url.toString().replace(EMAIL_RE, "[redacted]");
+    return link.length <= 500 ? link : undefined;
+}
+export function validRequestId(value) {
+    return typeof value === "string" && REQUEST_ID_PATTERN.test(value)
+        ? value
+        : undefined;
+}
+/**
+ * Lift the declared fields from one or more attribute sources; the first
+ * source carrying a key wins (e.g. exception event before its span).
+ * Returns only the fields that are present and valid.
+ */
+export function liftErrorFields(...sources) {
+    const out = {};
+    const code = lookupValid(sources, "autter.error.code", validErrorCode);
+    if (code)
+        out.errorCode = code;
+    const why = declaredText(lookup(sources, "autter.error.why"), 1000);
+    if (why)
+        out.why = why;
+    const fix = declaredText(lookup(sources, "autter.error.fix"), 1000);
+    if (fix)
+        out.fix = fix;
+    const link = declaredLink(lookup(sources, "autter.error.link"));
+    if (link)
+        out.link = link;
+    const expected = lookup(sources, "autter.error.expected");
+    if (expected === true || expected === "true")
+        out.expected = true;
+    const requestId = lookupValid(sources, "autter.request.id", validRequestId);
+    if (requestId)
+        out.requestId = requestId;
+    return out;
+}

package/dist/fingerprint.d.ts

@@ -3,6 +3,35 @@ export declare function normalizeMessage(message: string): string;
 /** Replace id-like path segments so /orders/812 and /orders/44 group. */
 export declare function normalizeRoute(route: string | null): string;
 export declare function normalizeStackFrames(stack: string | null, topN?: number): string[];
+/**
+ * Error codes (`autter.error.code`) — namespaced, stable, low-cardinality
+ * identifiers such as "billing.declined". Anything else (Node's "ECONNRESET",
+ * ids, free text) is not a code and the error groups by message as before.
+ * Shared spec: runtime-core and the Autter backend validate identically.
+ */
+export declare const CODE_PATTERN: RegExp;
+export declare const CODE_MAX_LENGTH = 80;
+export declare function validErrorCode(value: unknown): string | undefined;
+export type FingerprintScheme = "message-v1" | "code-v1";
+/**
+ * Scheme "code-v1": a SOURCE-INDEPENDENT issue identity for coded errors.
+ * Source, error type, message, stack and route are deliberately left out so
+ * the same code from the trace path, log promotion, the browser or an
+ * external connector (Sentry, PostHog, …) lands in ONE issue. Route and
+ * message stay as facets on the occurrence rows. Mirrored byte-for-byte by
+ * the backend (`runtime-code-fingerprint.ts`) — shared test vectors pin it.
+ */
+export declare function codeFingerprint(service: string, code: string): string;
+/**
+ * Issue identity plus the scheme that produced it. A valid
+ * `autter.error.code` selects "code-v1"; everything else keeps the
+ * historical message/stack/route fingerprint ("message-v1") byte-for-byte,
+ * so existing issues never regroup.
+ */
+export declare function occurrenceFingerprint(input: RuntimeOccurrenceInput): {
+    fingerprint: string;
+    scheme: FingerprintScheme;
+};
 export declare function fingerprintOccurrence(input: RuntimeOccurrenceInput): string;
 /**
  * Deterministic per-occurrence identity (as opposed to the fingerprint,

package/dist/fingerprint.js

@@ -233,7 +233,52 @@ export function normalizeStackFrames(stack, topN = 5) {
     }
     return frames.length > 0 ? frames : fallbackFrames(lines, topN);
 }
+/**
+ * Error codes (`autter.error.code`) — namespaced, stable, low-cardinality
+ * identifiers such as "billing.declined". Anything else (Node's "ECONNRESET",
+ * ids, free text) is not a code and the error groups by message as before.
+ * Shared spec: runtime-core and the Autter backend validate identically.
+ */
+export const CODE_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z0-9_]+){0,3}$/;
+export const CODE_MAX_LENGTH = 80;
+export function validErrorCode(value) {
+    return typeof value === "string" &&
+        value.length <= CODE_MAX_LENGTH &&
+        CODE_PATTERN.test(value)
+        ? value
+        : undefined;
+}
+/**
+ * Scheme "code-v1": a SOURCE-INDEPENDENT issue identity for coded errors.
+ * Source, error type, message, stack and route are deliberately left out so
+ * the same code from the trace path, log promotion, the browser or an
+ * external connector (Sentry, PostHog, …) lands in ONE issue. Route and
+ * message stay as facets on the occurrence rows. Mirrored byte-for-byte by
+ * the backend (`runtime-code-fingerprint.ts`) — shared test vectors pin it.
+ */
+export function codeFingerprint(service, code) {
+    return createHash("sha256")
+        .update(`code-v1\u0000${service}\u0000${code}`)
+        .digest("hex")
+        .slice(0, 32);
+}
+/**
+ * Issue identity plus the scheme that produced it. A valid
+ * `autter.error.code` selects "code-v1"; everything else keeps the
+ * historical message/stack/route fingerprint ("message-v1") byte-for-byte,
+ * so existing issues never regroup.
+ */
+export function occurrenceFingerprint(input) {
+    const code = validErrorCode(input.errorCode);
+    return code
+        ? { fingerprint: codeFingerprint(input.service, code), scheme: "code-v1" }
+        : { fingerprint: messageFingerprint(input), scheme: "message-v1" };
+}
 export function fingerprintOccurrence(input) {
+    return occurrenceFingerprint(input).fingerprint;
+}
+/** Scheme "message-v1" — the pre-1.5.0 fingerprint, unchanged. */
+function messageFingerprint(input) {
     const parts = [
         input.source,
         input.service,

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createIngesterApp } from "./server.js";
 export { loadConfig } from "./config.js";
+export * from "./compat.js";
 export { SinkForwarder, type SinkStats, type SinkTuning } from "./sink.js";
 export * from "./types.js";

package/dist/index.js

@@ -1,14 +1,15 @@
 import { loadConfig } from "./config.js";
 import { createIngesterApp } from "./server.js";
+import { ingesterVersion } from "./sdk-versions.js";
 const config = loadConfig();
-const { app, store, sink } = createIngesterApp(config);
+const { app, store, sink, reportIngesterInfo } = createIngesterApp(config);
 const server = app.listen(config.port, () => {
-    console.log(`autter otlp-ingester listening on :${config.port} ` +
+    console.log(`autter otlp-ingester ${ingesterVersion()} listening on :${config.port} ` +
         `(clickhouse: ${config.clickhouseUrl ? "configured" : "NOT configured"})`);
 });
 // Warm the schema at boot so the first ingest request doesn't pay for DDL.
 if (store.configured) {
-    store.ensureSchema().catch((err) => {
+    store.ensureSchema().then(reportIngesterInfo).catch((err) => {
         console.error("clickhouse schema bootstrap failed (will retry on first ingest):", err?.message ?? err);
     });
 }
@@ -32,5 +33,6 @@ process.on("SIGTERM", () => void shutdown("SIGTERM"));
 process.on("SIGINT", () => void shutdown("SIGINT"));
 export { createIngesterApp } from "./server.js";
 export { loadConfig } from "./config.js";
+export * from "./compat.js";
 export { SinkForwarder } from "./sink.js";
 export * from "./types.js";