@autter/otlp-ingester 1.5.0 → 1.6.1

package/README.md

@@ -75,6 +75,7 @@ the Autter dashboard reads both. See [docs/COMPATIBILITY.md](../../docs/COMPATIB
 | `SINK_MAX_ATTEMPTS` | `12` | Delivery attempts per batch (1–60 s backoff) |
 | `SINK_MAX_BUFFERED_BATCHES` | `1000` | Retry buffer cap; oldest drops are logged |
 | `SINK_MAX_BUFFERED_MB` | `64` | Sink retry buffer cap (memory) |
+| `SOURCE_MAP_CACHE_MB` | `64` | Memory budget (decoded size, function scope tables included) for parsed source maps used to symbolicate browser frames at ingest; least recently used maps are evicted, and a map that needs more than half of it is used without being kept |
 | `MAX_BODY_BYTES` | `1048576` | Request body cap |
 | `RATE_LIMIT_PER_MINUTE` | `300` | Per-key fixed window (server keys) |
 | `CLIENT_RATE_LIMIT_PER_MINUTE` | `120` | Per-key fixed window (client keys) |

package/dist/breadcrumbs.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Breadcrumbs — the steps before an error (sink contract §1).
+ *
+ * Browser events carry them as `breadcrumbs` (runtime-browser's opt-in
+ * `/breadcrumbs` module); server SDKs put a JSON string of the same array on
+ * the exception span event as `autter.breadcrumbs`. Either way they are
+ * untrusted client input, so this is a whitelist gate: unknown fields are
+ * dropped, every string is scrubbed, and the list is bounded before it is
+ * stored (under `autter.breadcrumbs` in the occurrence's attributes JSON)
+ * and forwarded to the sink.
+ */
+export type BreadcrumbType = "console" | "request" | "navigation" | "click" | "log" | "custom";
+export type BreadcrumbLevel = "debug" | "info" | "warning" | "error";
+export interface Breadcrumb {
+    type: BreadcrumbType;
+    /** ISO timestamp. */
+    at: string;
+    level?: BreadcrumbLevel;
+    /** ≤ 500 chars, scrubbed. */
+    message: string;
+    /** ≤ 10 keys of primitives; strings ≤ 200 chars, scrubbed. */
+    data?: Record<string, string | number | boolean | null>;
+}
+/** Span event / log attribute carrying a JSON string of `Breadcrumb[]`. */
+export declare const BREADCRUMBS_ATTRIBUTE = "autter.breadcrumbs";
+/** Key under which an occurrence's breadcrumbs are stored in its attributes JSON. */
+export declare const BREADCRUMBS_STORAGE_KEY = "autter.breadcrumbs";
+export declare const MAX_BREADCRUMBS = 30;
+/**
+ * Validate, bound and scrub breadcrumbs from any sender: an array, or a JSON
+ * string of one (the span attribute). Keeps the newest 30 valid entries,
+ * oldest first, within 16 KB of JSON; malformed entries are dropped one by
+ * one. Undefined when nothing valid remains.
+ */
+export declare function parseBreadcrumbs(raw: unknown): Breadcrumb[] | undefined;
+/** `{ breadcrumbs }` for an occurrence, or `{}` — spread into the input. */
+export declare function breadcrumbsField(...candidates: unknown[]): {
+    breadcrumbs?: Breadcrumb[];
+};
+/** Attributes JSON to store: the occurrence's attributes plus its breadcrumbs. */
+export declare function attributesWithBreadcrumbs(attributes: Record<string, unknown> | null, breadcrumbs: Breadcrumb[] | undefined): Record<string, unknown>;

package/dist/breadcrumbs.js

@@ -0,0 +1,151 @@
+import { isSensitiveKey, scrubText } from "./redact.js";
+/** Span event / log attribute carrying a JSON string of `Breadcrumb[]`. */
+export const BREADCRUMBS_ATTRIBUTE = "autter.breadcrumbs";
+/** Key under which an occurrence's breadcrumbs are stored in its attributes JSON. */
+export const BREADCRUMBS_STORAGE_KEY = "autter.breadcrumbs";
+export const MAX_BREADCRUMBS = 30;
+const MAX_MESSAGE = 500;
+const MAX_DATA_KEYS = 10;
+const MAX_DATA_STRING = 200;
+/** Stored JSON per occurrence; the oldest breadcrumbs go first. */
+const MAX_TOTAL_CHARS = 16 * 1024;
+/** Raw JSON accepted from a span attribute before parsing. */
+const MAX_RAW_CHARS = 256 * 1024;
+/** Entries examined from the end of an oversized list. */
+const MAX_SCANNED = 200;
+const TYPES = new Set(["console", "request", "navigation", "click", "log", "custom"]);
+const LEVELS = {
+    debug: "debug",
+    trace: "debug",
+    info: "info",
+    log: "info",
+    warning: "warning",
+    warn: "warning",
+    error: "error",
+    fatal: "error",
+    critical: "error",
+};
+const UNSAFE_KEY = /^(?:__proto__|constructor|prototype)$/;
+/** Drop query strings and fragments from http(s) URLs (procedural: linear). */
+function stripUrlQueries(value) {
+    return value.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);
+    });
+}
+function cleanText(value, max) {
+    // Cut before scrubbing (bounded work), with slack so a secret straddling
+    // the cut is masked whole.
+    return stripUrlQueries(scrubText(value.slice(0, max + 512))).slice(0, max);
+}
+function cleanData(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    let count = 0;
+    for (const [rawKey, value] of Object.entries(raw).slice(0, 64)) {
+        if (count >= MAX_DATA_KEYS)
+            break;
+        const key = rawKey.slice(0, 100);
+        if (!key || UNSAFE_KEY.test(key))
+            continue;
+        if (isSensitiveKey(key)) {
+            out[key] = "[redacted]";
+        }
+        else if (typeof value === "string") {
+            const text = /(?:url|path|route|target)$/i.test(key) ? value.split(/[?#]/)[0] : value;
+            out[key] = cleanText(text, MAX_DATA_STRING);
+        }
+        else if (typeof value === "number") {
+            if (!Number.isFinite(value))
+                continue;
+            out[key] = value;
+        }
+        else if (typeof value === "boolean" || value === null) {
+            out[key] = value;
+        }
+        else {
+            continue;
+        }
+        count++;
+    }
+    return count > 0 ? out : undefined;
+}
+function cleanBreadcrumb(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const input = raw;
+    const at = typeof input.at === "string" || typeof input.at === "number" ? new Date(input.at) : null;
+    if (!at || Number.isNaN(at.getTime()))
+        return null;
+    const message = typeof input.message === "string"
+        ? input.message
+        : typeof input.message === "number" || typeof input.message === "boolean"
+            ? String(input.message)
+            : "";
+    const type = typeof input.type === "string" && TYPES.has(input.type) ? input.type : "custom";
+    const level = typeof input.level === "string" ? LEVELS[input.level.toLowerCase()] : undefined;
+    const data = cleanData(input.data);
+    if (!message && !data)
+        return null;
+    return {
+        type: type,
+        at: at.toISOString(),
+        ...(level ? { level } : {}),
+        message: cleanText(message, MAX_MESSAGE),
+        ...(data ? { data } : {}),
+    };
+}
+/**
+ * Validate, bound and scrub breadcrumbs from any sender: an array, or a JSON
+ * string of one (the span attribute). Keeps the newest 30 valid entries,
+ * oldest first, within 16 KB of JSON; malformed entries are dropped one by
+ * one. Undefined when nothing valid remains.
+ */
+export function parseBreadcrumbs(raw) {
+    let list = raw;
+    if (typeof list === "string") {
+        if (list.length > MAX_RAW_CHARS)
+            return undefined;
+        try {
+            list = JSON.parse(list);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!Array.isArray(list) || list.length === 0)
+        return undefined;
+    const out = [];
+    let chars = 2;
+    const first = Math.max(0, list.length - MAX_SCANNED);
+    for (let i = list.length - 1; i >= first && out.length < MAX_BREADCRUMBS; i--) {
+        const crumb = cleanBreadcrumb(list[i]);
+        if (!crumb)
+            continue;
+        const size = JSON.stringify(crumb).length + 1;
+        if (chars + size > MAX_TOTAL_CHARS)
+            break;
+        chars += size;
+        out.push(crumb);
+    }
+    return out.length > 0 ? out.reverse() : undefined;
+}
+/** `{ breadcrumbs }` for an occurrence, or `{}` — spread into the input. */
+export function breadcrumbsField(...candidates) {
+    for (const candidate of candidates) {
+        if (candidate === undefined || candidate === null)
+            continue;
+        const breadcrumbs = parseBreadcrumbs(candidate);
+        if (breadcrumbs)
+            return { breadcrumbs };
+    }
+    return {};
+}
+/** Attributes JSON to store: the occurrence's attributes plus its breadcrumbs. */
+export function attributesWithBreadcrumbs(attributes, breadcrumbs) {
+    return breadcrumbs?.length
+        ? { ...(attributes ?? {}), [BREADCRUMBS_STORAGE_KEY]: breadcrumbs }
+        : (attributes ?? {});
+}

package/dist/clickhouse.d.ts

@@ -2,6 +2,8 @@ import type { IngesterConfig } from "./config.js";
 import { type LatencyHistogram } from "./latency.js";
 import { type ProfileSample } from "./profiles.js";
 import { type MemorySample, type PlatformEvent } from "./memory.js";
+import { type SourceMapCheck, type ValidSourceMap } from "./source-maps.js";
+import { type SourceMapKey } from "./source-maps-lookup.js";
 import { type RuntimeLogRecord } from "./logs.js";
 import { type SdkVersionRow } from "./sdk-versions.js";
 import type { SchemaStatus } from "./compat.js";
@@ -40,7 +42,9 @@ export declare class ClickHouseStore {
      * this tenant in [from, to] — the cross-batch half of the log-promotion
      * dedupe. `excludeIds` are the candidate occurrences' own deterministic
      * ids, so a retried batch does not dedupe against its own earlier,
-     * partially-committed write. Throws on failure; the caller decides.
+     * partially-committed write. Browser occurrences share the server's trace
+     * id (runtime-browser traceparent) but are a different signal, so they
+     * never suppress a server error. Throws on failure; the caller decides.
      */
     recentOccurrenceTraceIds(ctx: IngestContext, traceIds: string[], from: Date, to: Date, excludeIds: string[]): Promise<Set<string>>;
     /** Schema state as of the last ensureSchema attempt — never triggers DDL
@@ -63,11 +67,11 @@ export declare class ClickHouseStore {
     insertProfileSamples(ctx: IngestContext, samples: ProfileSample[]): Promise<void>;
     insertMemorySamples(ctx: IngestContext, samples: MemorySample[]): Promise<void>;
     insertPlatformEvent(ctx: IngestContext, event: PlatformEvent): Promise<void>;
-    insertSourceMap(ctx: IngestContext, sourceMap: {
-        release: string;
-        filename: string;
-        map: string;
-    }): Promise<void>;
+    insertSourceMap(ctx: IngestContext, sourceMap: ValidSourceMap): Promise<void>;
+    /** The uploaded source map for a minified file, or null (source-maps-lookup.ts). */
+    lookupSourceMap(key: SourceMapKey): Promise<string | null>;
+    /** Indexes of `check.entries` this tenant uploaded recently (see presentSourceMaps). */
+    sourceMapsPresent(ctx: IngestContext, check: SourceMapCheck): Promise<number[]>;
     insertLlmCalls(ctx: IngestContext, calls: RuntimeLlmCall[]): Promise<void>;
     insertMetricPoints(ctx: IngestContext, points: RuntimeMetricPoint[]): Promise<void>;
     insertLatencyHistograms(ctx: IngestContext, points: LatencyHistogram[]): Promise<void>;

package/dist/clickhouse.js

@@ -3,9 +3,11 @@ import { latencyTableDDL } from "./latency.js";
 import { profileTableDDL } from "./profiles.js";
 import { memoryTableDDL, platformEventTableDDL } from "./memory.js";
 import { sourceMapTableDDL } from "./source-maps.js";
+import { attributesWithBreadcrumbs } from "./breadcrumbs.js";
+import { lookupSourceMap, presentSourceMaps } from "./source-maps-lookup.js";
 import { logTableDDL, requestRollupTableDDL, } from "./logs.js";
 import { ingesterInfoTableDDL, sdkVersionTableDDL, } from "./sdk-versions.js";
-import { MIGRATIONS, OCCURRENCE_CODE_COLUMNS, OCCURRENCE_REQUEST_ID_INDEX, migrationsTableDDL, } from "./migrations.js";
+import { MIGRATIONS, OCCURRENCE_CODE_COLUMNS, OCCURRENCE_GROUPING_COLUMNS, OCCURRENCE_REQUEST_ID_INDEX, migrationsTableDDL, } from "./migrations.js";
 /**
  * ClickHouse persistence. The schema is idempotent and applied lazily once
  * per process. Every row is keyed by (org_id, repository_id) — tenant
@@ -17,6 +19,9 @@ const INSERT_SETTINGS = {
     async_insert: 1,
     wait_for_async_insert: 1,
 };
+/** Source maps above this go in with a plain insert (below ClickHouse's
+ * default async_insert_max_data_size of 10 MiB). */
+const ASYNC_INSERT_MAX_MAP_CHARS = 8 * 1024 * 1024;
 /** "YYYY-MM-DD hh:mm:ss.sss" (UTC) — the DateTime64 query-parameter form. */
 function chDateTime(date) {
     return date.toISOString().replace("T", " ").replace("Z", "");
@@ -95,6 +100,7 @@ export class ClickHouseStore {
 				occurred_at        DateTime64(3, 'UTC'),
 				ingested_at        DateTime64(3, 'UTC') DEFAULT now64(3),
 				${OCCURRENCE_CODE_COLUMNS.join(",\n\t\t\t\t")},
+				${OCCURRENCE_GROUPING_COLUMNS.join(",\n\t\t\t\t")},
 				${OCCURRENCE_REQUEST_ID_INDEX}
 			)
 			ENGINE = MergeTree
@@ -259,7 +265,9 @@ export class ClickHouseStore {
      * this tenant in [from, to] — the cross-batch half of the log-promotion
      * dedupe. `excludeIds` are the candidate occurrences' own deterministic
      * ids, so a retried batch does not dedupe against its own earlier,
-     * partially-committed write. Throws on failure; the caller decides.
+     * partially-committed write. Browser occurrences share the server's trace
+     * id (runtime-browser traceparent) but are a different signal, so they
+     * never suppress a server error. Throws on failure; the caller decides.
      */
     async recentOccurrenceTraceIds(ctx, traceIds, from, to, excludeIds) {
         if (traceIds.length === 0 || !this.configured)
@@ -269,6 +277,7 @@ export class ClickHouseStore {
             query: `SELECT DISTINCT trace_id FROM ${this.table("runtime_error_occurrences")}
 				WHERE org_id = {org:String} AND repository_id = {repo:String}
 					AND occurred_at >= {from:DateTime64(3, 'UTC')} AND occurred_at <= {to:DateTime64(3, 'UTC')}
+					AND source != 'browser'
 					AND has({traces:Array(String)}, trace_id)
 					AND NOT has({exclude:Array(String)}, occurrence_id)`,
             query_params: {
@@ -364,7 +373,7 @@ export class ClickHouseStore {
                 status_code: o.statusCode ?? 0,
                 trace_id: o.traceId ?? "",
                 session_id: o.sessionId ?? "",
-                attributes: JSON.stringify(o.attributes ?? {}),
+                attributes: JSON.stringify(attributesWithBreadcrumbs(o.attributes, o.breadcrumbs)),
                 occurred_at: o.occurredAt.toISOString(),
                 error_code: o.errorCode ?? "",
                 error_why: o.why ?? "",
@@ -373,6 +382,8 @@ export class ClickHouseStore {
                 expected: o.expected ? 1 : 0,
                 request_id: o.requestId ?? "",
                 fingerprint_scheme: o.fingerprintScheme,
+                frames: o.frames?.length ? JSON.stringify(o.frames) : "",
+                fingerprints: (o.fingerprints ?? []).map((candidate) => candidate.fingerprint),
             })),
         });
     }
@@ -466,10 +477,32 @@ export class ClickHouseStore {
         await this.ensureSchema();
         await this.getClient().insert({
             table: this.table("runtime_source_maps"), format: "JSONEachRow",
-            clickhouse_settings: INSERT_SETTINGS,
-            values: [{ org_id: ctx.orgId, repository_id: ctx.repositoryId, ...sourceMap }],
+            // One row of up to 32 MiB. Parallel parsing cuts input into
+            // 10 MiB chunks, refuses single JSON rows far past that, and gains
+            // nothing on one row. A map past the async-insert buffer (10 MiB
+            // by default) is inserted directly rather than buffered.
+            clickhouse_settings: {
+                ...INSERT_SETTINGS,
+                input_format_parallel_parsing: 0,
+                ...(sourceMap.map.length > ASYNC_INSERT_MAX_MAP_CHARS ? { async_insert: 0 } : {}),
+            },
+            values: [{ org_id: ctx.orgId, repository_id: ctx.repositoryId, release: sourceMap.release,
+                    filename: sourceMap.filename, map: sourceMap.map, debug_id: sourceMap.debugId,
+                    content_hash: sourceMap.contentHash }],
         });
     }
+    /** The uploaded source map for a minified file, or null (source-maps-lookup.ts). */
+    async lookupSourceMap(key) {
+        if (!this.configured)
+            return null;
+        await this.ensureSchema();
+        return lookupSourceMap(this.getClient(), this.config.clickhouseDatabase, key);
+    }
+    /** Indexes of `check.entries` this tenant uploaded recently (see presentSourceMaps). */
+    async sourceMapsPresent(ctx, check) {
+        await this.ensureSchema();
+        return presentSourceMaps(this.getClient(), this.config.clickhouseDatabase, ctx, check);
+    }
     async insertLlmCalls(ctx, calls) {
         if (calls.length === 0 || !this.configured)
             return;

package/dist/compat-manifest.json

@@ -89,6 +89,35 @@
             "ingester": "1.5.0",
             "migrations": ["0013-occurrence-codes"],
             "sdks": { "@autter/runtime-node": "1.5.0", "@autter/runtime-next": "1.5.0", "@autter/runtime-browser": "1.4.0", "@autter/runtime-edge": "1.0.0" }
+        },
+        {
+            "id": "breadcrumbs",
+            "title": "Breadcrumbs: the steps before an error",
+            "ingester": "1.6.0",
+            "migrations": [],
+            "sdks": { "@autter/runtime-browser": "1.6.0", "@autter/runtime-node": "1.6.0", "@autter/runtime-next": "1.6.0" }
+        },
+        {
+            "id": "source_map_debug_ids",
+            "title": "Source map debug ids",
+            "ingester": "1.6.0",
+            "migrations": ["0017-source-maps-debug-id"],
+            "route": "/v1/sourcemaps/check",
+            "sdks": { "@autter/runtime-browser": "1.6.0", "@autter/runtime-next": "1.6.0" }
+        },
+        {
+            "id": "fingerprint_override",
+            "title": "Fingerprint override",
+            "ingester": "1.6.0",
+            "migrations": [],
+            "sdks": { "@autter/runtime-browser": "1.6.0", "@autter/runtime-node": "1.6.0", "@autter/runtime-next": "1.6.0", "@autter/runtime-edge": "1.1.0" }
+        },
+        {
+            "id": "browser_trace_propagation",
+            "title": "Browser trace propagation (browser errors linked to server traces)",
+            "ingester": "1.6.0",
+            "migrations": [],
+            "sdks": { "@autter/runtime-browser": "1.6.0", "@autter/runtime-next": "1.6.0", "@autter/runtime-node": "1.6.0" }
         }
     ]
 }

package/dist/compat.d.ts

@@ -20,7 +20,9 @@
  * 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.
+ * consistency test in compat.test.ts checks ids, migrations and routes, and
+ * that no version is ahead of its package's package.json: a feature for the
+ * next release bumps the packages it names in the same change.
  */
 export interface CompatFeature {
     id: string;

package/dist/compat.js

@@ -20,7 +20,9 @@
  * 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.
+ * consistency test in compat.test.ts checks ids, migrations and routes, and
+ * that no version is ahead of its package's package.json: a feature for the
+ * next release bumps the packages it names in the same change.
  */
 import manifestJson from "./compat-manifest.json" with { type: "json" };
 export const COMPAT_MANIFEST = manifestJson;

package/dist/config.d.ts

@@ -54,5 +54,11 @@ export interface IngesterConfig {
      */
     redactValuePatterns?: string[];
     redactKeyPatterns?: string[];
+    /**
+     * In-memory budget (MiB, decoded size) for parsed source maps used to
+     * symbolicate browser frames at ingest (SOURCE_MAP_CACHE_MB, default 64).
+     * A map that needs more than half of it is used without being kept.
+     */
+    sourceMapCacheMb?: number;
 }
 export declare function loadConfig(): IngesterConfig;

package/dist/config.js

@@ -66,6 +66,7 @@ export function loadConfig() {
         logTtlDays: intEnv("LOG_TTL_DAYS", 14),
         redactValuePatterns: patternListEnv("AUTTER_REDACT_VALUE_PATTERNS"),
         redactKeyPatterns: patternListEnv("AUTTER_REDACT_KEY_PATTERNS"),
+        sourceMapCacheMb: intEnv("SOURCE_MAP_CACHE_MB", 64),
     };
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(config.clickhouseDatabase)) {
         throw new Error(`Invalid CLICKHOUSE_DATABASE name: ${config.clickhouseDatabase}`);

package/dist/context.js

@@ -1,4 +1,5 @@
 import { isSensitiveKey, scrubText } from "./redact.js";
+import { BREADCRUMBS_ATTRIBUTE } from "./breadcrumbs.js";
 /** Bounded, defensive privacy boundary for custom telemetry from any OTLP SDK. */
 export function sanitizeRuntimeContext(input) {
     let budget = 512;
@@ -97,6 +98,8 @@ export function decodeOtlpAttributes(attributes) {
         .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))
+        .filter(
+    // Breadcrumbs are their own validated field (breadcrumbs.ts), never a plain attribute.
+    (a) => a.key && a.key !== BREADCRUMBS_ATTRIBUTE && !/^(?:__proto__|constructor|prototype)$/.test(a.key))
         .map((a) => [a.key, decode(a.value)])));
 }

package/dist/fingerprint-override.d.ts

@@ -0,0 +1,42 @@
+import type { RuntimeOccurrenceInput } from "./types.js";
+/**
+ * SDK fingerprint override (EI-16) → the `manual-v1` issue identity.
+ *
+ * Where it comes from:
+ * - browser events: `fingerprint` (a string or an array of strings), from
+ *   `captureException(err, { fingerprint })` or `beforeSend`;
+ * - OTLP exception events (or their span) and promoted error logs:
+ *   `autter.fingerprint`, a string or a JSON array of strings (the SDKs always
+ *   send the JSON array, so a single value never reads as a list by accident).
+ *
+ * The normalisers carry it as `RuntimeOccurrenceInput.fingerprintOverride`:
+ * strings only, empty values dropped, at most 10 values, each scrubbed like
+ * the rest of the occurrence and then cut to 200 characters. A malformed
+ * override is dropped on its own; it never rejects the signal.
+ *
+ * `manualFingerprint` hashes it. `manual-v1` takes precedence over every
+ * other scheme (rule-v1, code-v1, frames-v3, message-v1) and is only ever
+ * computed here, never on the platform:
+ *
+ *   sha256("manual-v1" \0 service \0 values.join("\u0001")).hex()[:32]
+ */
+export declare const MANUAL_FINGERPRINT_SCHEME = "manual-v1";
+export declare const FINGERPRINT_ATTRIBUTE = "autter.fingerprint";
+export declare const MAX_FINGERPRINT_VALUES = 10;
+export declare const MAX_FINGERPRINT_VALUE_LENGTH = 200;
+/**
+ * The override values carried on the wire, cleaned: `value` is a string, a
+ * JSON array string, or an already-decoded array. Undefined when absent or
+ * unusable.
+ */
+export declare function parseFingerprintOverride(value: unknown): string[] | undefined;
+/** `{ fingerprintOverride }` to spread into an occurrence, or `{}`. */
+export declare function fingerprintOverrideOf(value: unknown): {
+    fingerprintOverride?: string[];
+};
+/**
+ * The `manual-v1` fingerprint (32 lowercase hex) of an occurrence's override,
+ * or null when it has none. The values are bounded again here (at most 10,
+ * each ≤ 200 chars), so the hash never depends on how the input was built.
+ */
+export declare function manualFingerprint(input: Pick<RuntimeOccurrenceInput, "service" | "fingerprintOverride">): string | null;

package/dist/fingerprint-override.js

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+import { scrubText } from "./redact.js";
+/**
+ * SDK fingerprint override (EI-16) → the `manual-v1` issue identity.
+ *
+ * Where it comes from:
+ * - browser events: `fingerprint` (a string or an array of strings), from
+ *   `captureException(err, { fingerprint })` or `beforeSend`;
+ * - OTLP exception events (or their span) and promoted error logs:
+ *   `autter.fingerprint`, a string or a JSON array of strings (the SDKs always
+ *   send the JSON array, so a single value never reads as a list by accident).
+ *
+ * The normalisers carry it as `RuntimeOccurrenceInput.fingerprintOverride`:
+ * strings only, empty values dropped, at most 10 values, each scrubbed like
+ * the rest of the occurrence and then cut to 200 characters. A malformed
+ * override is dropped on its own; it never rejects the signal.
+ *
+ * `manualFingerprint` hashes it. `manual-v1` takes precedence over every
+ * other scheme (rule-v1, code-v1, frames-v3, message-v1) and is only ever
+ * computed here, never on the platform:
+ *
+ *   sha256("manual-v1" \0 service \0 values.join("\u0001")).hex()[:32]
+ */
+export const MANUAL_FINGERPRINT_SCHEME = "manual-v1";
+export const FINGERPRINT_ATTRIBUTE = "autter.fingerprint";
+export const MAX_FINGERPRINT_VALUES = 10;
+export const MAX_FINGERPRINT_VALUE_LENGTH = 200;
+/** Strings only, empty dropped, first 10, each cut to 200 chars; null when none remain. */
+function boundValues(list, scrub) {
+    const values = list
+        .filter((value) => typeof value === "string" && value !== "")
+        .slice(0, MAX_FINGERPRINT_VALUES)
+        // Cut with slack, scrub, then cut: a secret straddling the limit is
+        // masked whole.
+        .map((value) => scrub(value.slice(0, MAX_FINGERPRINT_VALUE_LENGTH + 512)).slice(0, MAX_FINGERPRINT_VALUE_LENGTH))
+        .filter((value) => value !== "");
+    return values.length > 0 ? values : null;
+}
+/**
+ * The override values carried on the wire, cleaned: `value` is a string, a
+ * JSON array string, or an already-decoded array. Undefined when absent or
+ * unusable.
+ */
+export function parseFingerprintOverride(value) {
+    let list = value;
+    if (typeof value === "string" && /^\s*\[/.test(value)) {
+        try {
+            list = JSON.parse(value);
+        }
+        catch {
+            /* not JSON: one plain value */
+        }
+    }
+    return boundValues(Array.isArray(list) ? list : [list], scrubText) ?? undefined;
+}
+/** `{ fingerprintOverride }` to spread into an occurrence, or `{}`. */
+export function fingerprintOverrideOf(value) {
+    const values = parseFingerprintOverride(value);
+    return values ? { fingerprintOverride: values } : {};
+}
+/**
+ * The `manual-v1` fingerprint (32 lowercase hex) of an occurrence's override,
+ * or null when it has none. The values are bounded again here (at most 10,
+ * each ≤ 200 chars), so the hash never depends on how the input was built.
+ */
+export function manualFingerprint(input) {
+    if (!Array.isArray(input.fingerprintOverride))
+        return null;
+    const values = boundValues(input.fingerprintOverride, (text) => text);
+    if (!values)
+        return null;
+    return createHash("sha256")
+        .update(`${MANUAL_FINGERPRINT_SCHEME}\u0000${input.service}\u0000${values.join("\u0001")}`)
+        .digest("hex")
+        .slice(0, 32);
+}

package/dist/fingerprint-v3.d.ts

@@ -0,0 +1,54 @@
+import type { FingerprintCandidate, FingerprintRecord, RuntimeOccurrenceInput, StackFrame } from "./types.js";
+/**
+ * `frames-v3` — the structural issue identity (contract §2). Byte-for-byte
+ * shared with the platform mirror (`runtime-frames-fingerprint.ts`); the
+ * vectors in fingerprint-v3-vectors.json pin both.
+ *
+ * It hashes service + error type + up to five in-app frames reduced to
+ * `function@file`, where file is a lowercased basename with build hashes
+ * (`index-5f3a9c1e.js` → `index-*.js`) templated out. Line and column
+ * numbers, route, source (browser vs server) and release are never part of
+ * it, so one bug stays one issue across deploys, pages, preview domains and
+ * tiers. The normalised message is hashed only when no frame was picked.
+ */
+export declare const FRAMES_V3 = "frames-v3";
+/** §2.3 — the function half of a frame token. */
+export declare function frameTokenFunction(frame: Pick<StackFrame, "function" | "resolved">): string;
+/** §2.3 — the file half of a frame token. */
+export declare function frameTokenFile(frame: Pick<StackFrame, "filename" | "module">): string;
+export declare function frameToken(frame: StackFrame): string;
+/** §2.1–2.2 — in-app frames in order, else only the first frame; at most 5. */
+export declare function pickFrames(frames: StackFrame[]): StackFrame[];
+export interface FramesV3Input {
+    service: string;
+    errorType: string;
+    message: string;
+    frames: StackFrame[];
+}
+export interface FramesV3Result {
+    fingerprint: string;
+    record: FingerprintRecord;
+}
+export declare function framesV3Fingerprint(input: FramesV3Input): FramesV3Result;
+export interface OccurrenceIdentity {
+    /** Legacy identity, unchanged: what `fingerprint`/`fingerprintScheme` carry. */
+    legacy: {
+        fingerprint: string;
+        scheme: "message-v1" | "code-v1";
+    };
+    /** Every applicable scheme, highest precedence first; ends with the legacy one. */
+    candidates: FingerprintCandidate[];
+    /** What went into the frames-v3 fingerprint, when one was computed. */
+    record: FingerprintRecord | null;
+}
+/**
+ * The candidate list the sink carries (contract §1/§4), highest precedence
+ * first:
+ *   manual-v1 (SDK override) → code-v1 (valid error code) → frames-v3 →
+ *   message-v1 (legacy).
+ * A coded error's legacy identity IS code-v1, which outranks every auto
+ * scheme, so its list is [manual-v1?, code-v1]; an uncoded one is
+ * [manual-v1?, frames-v3, message-v1]. Either way the list ends with the
+ * legacy fingerprint, so the platform can always fall back to it.
+ */
+export declare function occurrenceIdentity(input: RuntimeOccurrenceInput, frames: StackFrame[]): OccurrenceIdentity;