@autter/otlp-ingester 1.5.0 → 1.6.1

package/dist/server.js

@@ -2,7 +2,10 @@ import express from "express";
 import { KeyResolver, RateLimiter } from "./auth.js";
 import { ClickHouseStore } from "./clickhouse.js";
 import { normalizeLatencyHistograms } from "./latency.js";
-import { deriveFields, occurrenceFingerprint, 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";
@@ -10,7 +13,7 @@ import { decodeMetricsRequest, decodeTraceRequest, decodeLogsRequest } from "./o
 import { normalizeLogs } from "./logs.js";
 import { decodeProfile } from "./profiles.js";
 import { normalizeMemoryMetrics, normalizePlatformEvent, platformEventSchema } from "./memory.js";
-import { validateSourceMap } from "./source-maps.js";
+import { SOURCE_MAP_MAX_BODY_BYTES, 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";
@@ -22,6 +25,9 @@ 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.
@@ -78,7 +84,40 @@ export function createIngesterApp(config) {
         next();
     });
     app.use(express.raw({ limit: "1mb", type: ["application/x-pprof"] }));
-    app.use("/v1/sourcemaps", express.json({ limit: "5mb" }));
+    // A check names at most 500 maps: well under 1 MB, whatever MAX_BODY_BYTES is.
+    app.use("/v1/sourcemaps/check", express.json({ limit: "1mb" }));
+    // Source map uploads (up to 32 MiB of JSON, usually gzipped) are routed
+    // before the small-body parsers below, and read their body only once the
+    // key is checked: an anonymous client can't make the ingester inflate and
+    // parse one. body-parser inflates gzip/deflate and applies the limit to
+    // the inflated bytes, so a small compressed body can't expand past it.
+    const sourceMapBody = express.json({ limit: SOURCE_MAP_MAX_BODY_BYTES });
+    app.post("/v1/sourcemaps", async (req, res, next) => {
+        // On failure the body is never read (Node discards it).
+        const ctx = await authenticate(req, res, "otlp");
+        if (!ctx)
+            return;
+        sourceMapBody(req, res, async (err) => {
+            if (err) {
+                next(err);
+                return;
+            }
+            const sourceMap = validateSourceMap(req.body);
+            if (!sourceMap) {
+                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 });
+            }
+            catch (storeErr) {
+                storageError(res, storeErr);
+            }
+        });
+    });
     app.use(express.json({
         limit: config.maxBodyBytes,
         type: ["application/json"],
@@ -203,28 +242,64 @@ 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((raw, index) => {
+     * 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 { fingerprint, scheme } = occurrenceFingerprint(input);
+            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
@@ -234,7 +309,7 @@ export function createIngesterApp(config) {
         const candidates = logPromotionCandidates(logs);
         if (candidates.length === 0)
             return [];
-        const fingerprinted = fingerprintAll(ctx, candidates);
+        const fingerprinted = await fingerprintAll(ctx, candidates);
         const seen = new Set();
         const ownIds = fingerprinted.map((o) => o.occurrenceId);
         for (const lookup of promotionLookups(candidates)) {
@@ -299,18 +374,19 @@ export function createIngesterApp(config) {
             storageError(res, err);
         }
     });
-    app.post("/v1/sourcemaps", async (req, res) => {
+    /** 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 sourceMap = validateSourceMap(req.body);
-        if (!sourceMap) {
-            res.status(400).json({ error: "invalid source map" });
+        const check = validateSourceMapCheck(req.body);
+        if (!check) {
+            res.status(400).json({ error: "invalid source map check" });
             return;
         }
         try {
-            await store.insertSourceMap(ctx, sourceMap);
-            res.status(202).json({ accepted: true });
+            res.status(200).json({ present: await store.sourceMapsPresent(ctx, check) });
         }
         catch (err) {
             storageError(res, err);
@@ -357,7 +433,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
@@ -473,7 +549,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),

package/dist/sink.d.ts

@@ -107,6 +107,10 @@ export declare class SinkForwarder {
  * 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.
- * Older consumers ignore unknown keys, so the version stays 1.
+ * 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

@@ -301,10 +301,16 @@ export class SinkForwarder {
  * 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.
- * Older consumers ignore unknown keys, so the version stays 1.
+ * 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, ...rest } = 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(),
@@ -318,6 +324,11 @@ export function sinkOccurrence(o) {
         ...(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. */

package/dist/source-map-mappings.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Position lookups in a source map's `mappings`, without the memory of a
+ * general-purpose decoder.
+ *
+ * @jridgewell/trace-mapping decodes `mappings` into one small array per
+ * segment: about 14 bytes of heap per byte of JSON (a 5 MB map takes 67 MB).
+ * Symbolication only needs "which original position is at or before this
+ * generated one", so a map that is kept in the cache is decoded into one
+ * Int32Array (5 ints per segment: about 3 bytes per byte of JSON), and a map
+ * too big to keep is not decoded at all: its frames are resolved in one
+ * streaming pass over the string.
+ *
+ * Lookup semantics match trace-mapping's `originalPositionFor` (greatest
+ * lower bound): the first segment that starts at the frame's column, else
+ * the last segment before it on the same line; a segment without a source
+ * maps to nothing.
+ */
+/** An original position. Lines and columns are 0-based; `name` is -1 when the segment has none. */
+export interface MappedSegment {
+    source: number;
+    line: number;
+    column: number;
+    name: number;
+}
+/** A 0-based generated (line, column). */
+export interface GeneratedPosition {
+    line: number;
+    column: number;
+}
+/**
+ * Walk a mappings-style string — `;` between generated lines, `,` between
+ * groups of base64 VLQ values — calling `visit(line, values, count)` with
+ * each group's raw (relative) values. `values` is reused between calls and
+ * holds the first 6; `count` is how many the group had. Throws on
+ * malformed VLQ. Also reads `x_autter_scopes` (source-map-scopes.ts).
+ */
+export declare function forEachVlqGroup(text: string, visit: (line: number, values: readonly number[], count: number) => void): void;
+/** Heap a DecodedMappings of `mappings` would take, without decoding it. */
+export declare function decodedMappingsBytes(mappings: string): number;
+export declare class DecodedMappings {
+    /** FIELDS ints per segment, each line's segments sorted by generated column. */
+    private readonly segments;
+    /** Index of each line's first segment; one extra entry closes the last line. */
+    private readonly lineStarts;
+    private constructor();
+    static decode(mappings: string): DecodedMappings;
+    get bytes(): number;
+    /** Generators almost always emit a line's segments in column order; sort the rare line that isn't (stable, as trace-mapping does). */
+    private sortLine;
+    /** The original position at a 0-based generated (line, column), or null. */
+    find(line: number, column: number): MappedSegment | null;
+}
+/**
+ * Resolve several positions in one pass over `mappings` without decoding
+ * it — for maps too big to keep. Same results as DecodedMappings.find.
+ */
+export declare function findInMappings(mappings: string, positions: readonly GeneratedPosition[]): Array<MappedSegment | null>;

package/dist/source-map-mappings.js

@@ -0,0 +1,245 @@
+/**
+ * Position lookups in a source map's `mappings`, without the memory of a
+ * general-purpose decoder.
+ *
+ * @jridgewell/trace-mapping decodes `mappings` into one small array per
+ * segment: about 14 bytes of heap per byte of JSON (a 5 MB map takes 67 MB).
+ * Symbolication only needs "which original position is at or before this
+ * generated one", so a map that is kept in the cache is decoded into one
+ * Int32Array (5 ints per segment: about 3 bytes per byte of JSON), and a map
+ * too big to keep is not decoded at all: its frames are resolved in one
+ * streaming pass over the string.
+ *
+ * Lookup semantics match trace-mapping's `originalPositionFor` (greatest
+ * lower bound): the first segment that starts at the frame's column, else
+ * the last segment before it on the same line; a segment without a source
+ * maps to nothing.
+ */
+/** generated column, source, original line, original column, name. */
+const FIELDS = 5;
+const NONE = -1;
+const BASE64 = new Int8Array(128).fill(-1);
+for (const [i, ch] of [..."ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"].entries()) {
+    BASE64[ch.charCodeAt(0)] = i;
+}
+/**
+ * Walk a mappings-style string — `;` between generated lines, `,` between
+ * groups of base64 VLQ values — calling `visit(line, values, count)` with
+ * each group's raw (relative) values. `values` is reused between calls and
+ * holds the first 6; `count` is how many the group had. Throws on
+ * malformed VLQ. Also reads `x_autter_scopes` (source-map-scopes.ts).
+ */
+export function forEachVlqGroup(text, visit) {
+    const values = [0, 0, 0, 0, 0, 0];
+    let line = 0;
+    let i = 0;
+    while (i < text.length) {
+        const ch = text.charCodeAt(i);
+        if (ch === 59 /* ; */) {
+            line++;
+            i++;
+            continue;
+        }
+        if (ch === 44 /* , */) {
+            i++;
+            continue;
+        }
+        let count = 0;
+        while (i < text.length) {
+            const next = text.charCodeAt(i);
+            if (next === 44 || next === 59)
+                break;
+            let value = 0;
+            let shift = 0;
+            let digit;
+            do {
+                const code = text.charCodeAt(i++);
+                digit = code < 128 ? BASE64[code] : -1;
+                if (digit < 0 || shift > 30)
+                    throw new Error("invalid VLQ");
+                value |= (digit & 31) << shift;
+                shift += 5;
+            } while (digit & 32);
+            if (count < values.length)
+                values[count] = value & 1 ? -(value >>> 1) : value >>> 1;
+            count++;
+        }
+        visit(line, values, count);
+    }
+}
+/**
+ * Walk every segment: `visit(line, generatedColumn, source, originalLine,
+ * originalColumn, name)`, with source and name -1 when absent. Throws on
+ * malformed VLQ.
+ */
+function forEachSegment(mappings, visit) {
+    let currentLine = 0;
+    let column = 0;
+    let source = 0;
+    let originalLine = 0;
+    let originalColumn = 0;
+    let name = 0;
+    forEachVlqGroup(mappings, (line, values, count) => {
+        // The generated column restarts on each line; the other fields don't.
+        if (line !== currentLine) {
+            currentLine = line;
+            column = 0;
+        }
+        column += values[0];
+        if (count >= 4) {
+            source += values[1];
+            originalLine += values[2];
+            originalColumn += values[3];
+        }
+        if (count >= 5)
+            name += values[4];
+        visit(line, column, count >= 4 ? source : NONE, originalLine, originalColumn, count >= 5 ? name : NONE);
+    });
+}
+/** Segments and generated lines in `mappings`, from one scan without decoding. */
+function countSegments(mappings) {
+    let segments = 0;
+    let lines = 1;
+    let inSegment = false;
+    for (let i = 0; i < mappings.length; i++) {
+        const ch = mappings.charCodeAt(i);
+        if (ch === 59) {
+            lines++;
+            inSegment = false;
+        }
+        else if (ch === 44) {
+            inSegment = false;
+        }
+        else if (!inSegment) {
+            segments++;
+            inSegment = true;
+        }
+    }
+    return { segments, lines };
+}
+/** Heap a DecodedMappings of `mappings` would take, without decoding it. */
+export function decodedMappingsBytes(mappings) {
+    const { segments, lines } = countSegments(mappings);
+    return segments * FIELDS * 4 + (lines + 1) * 4 + 64;
+}
+export class DecodedMappings {
+    segments;
+    lineStarts;
+    constructor(
+    /** FIELDS ints per segment, each line's segments sorted by generated column. */
+    segments, 
+    /** Index of each line's first segment; one extra entry closes the last line. */
+    lineStarts) {
+        this.segments = segments;
+        this.lineStarts = lineStarts;
+    }
+    static decode(mappings) {
+        const { segments: count, lines } = countSegments(mappings);
+        const segments = new Int32Array(count * FIELDS);
+        const lineStarts = new Int32Array(lines + 1);
+        let n = 0;
+        let currentLine = 0;
+        forEachSegment(mappings, (line, column, source, originalLine, originalColumn, name) => {
+            while (currentLine < line)
+                lineStarts[++currentLine] = n;
+            const at = n * FIELDS;
+            segments[at] = column;
+            segments[at + 1] = source;
+            segments[at + 2] = originalLine;
+            segments[at + 3] = originalColumn;
+            segments[at + 4] = name;
+            n++;
+        });
+        while (currentLine < lines)
+            lineStarts[++currentLine] = n;
+        const decoded = new DecodedMappings(segments, lineStarts);
+        for (let line = 0; line < lines; line++)
+            decoded.sortLine(line);
+        return decoded;
+    }
+    get bytes() {
+        return this.segments.byteLength + this.lineStarts.byteLength + 64;
+    }
+    /** Generators almost always emit a line's segments in column order; sort the rare line that isn't (stable, as trace-mapping does). */
+    sortLine(line) {
+        const start = this.lineStarts[line];
+        const end = this.lineStarts[line + 1];
+        const s = this.segments;
+        let sorted = true;
+        for (let i = start + 1; i < end && sorted; i++)
+            sorted = s[(i - 1) * FIELDS] <= s[i * FIELDS];
+        if (sorted)
+            return;
+        const rows = [];
+        for (let i = start; i < end; i++)
+            rows.push(Array.from(s.subarray(i * FIELDS, (i + 1) * FIELDS)));
+        rows.sort((a, b) => a[0] - b[0]);
+        rows.forEach((row, k) => s.set(row, (start + k) * FIELDS));
+    }
+    /** The original position at a 0-based generated (line, column), or null. */
+    find(line, column) {
+        if (line < 0 || line + 1 >= this.lineStarts.length)
+            return null;
+        const s = this.segments;
+        let lo = this.lineStarts[line];
+        let hi = this.lineStarts[line + 1] - 1;
+        let found = -1;
+        while (lo <= hi) {
+            const mid = (lo + hi) >> 1;
+            if (s[mid * FIELDS] <= column) {
+                found = mid;
+                lo = mid + 1;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        if (found < 0)
+            return null;
+        // Several segments at exactly this column: the first one (before it,
+        // the last one — as trace-mapping does).
+        if (s[found * FIELDS] === column) {
+            while (found > this.lineStarts[line] && s[(found - 1) * FIELDS] === column)
+                found--;
+        }
+        const at = found * FIELDS;
+        if (s[at + 1] === NONE)
+            return null;
+        return { source: s[at + 1], line: s[at + 2], column: s[at + 3], name: s[at + 4] };
+    }
+}
+/**
+ * Resolve several positions in one pass over `mappings` without decoding
+ * it — for maps too big to keep. Same results as DecodedMappings.find.
+ */
+export function findInMappings(mappings, positions) {
+    const byLine = new Map();
+    positions.forEach((position, index) => {
+        const list = byLine.get(position.line);
+        if (list)
+            list.push(index);
+        else
+            byLine.set(position.line, [index]);
+    });
+    const best = positions.map(() => null);
+    forEachSegment(mappings, (line, column, source, originalLine, originalColumn, name) => {
+        const wanted = byLine.get(line);
+        if (!wanted)
+            return;
+        for (const index of wanted) {
+            const target = positions[index].column;
+            const current = best[index];
+            // Greatest column at or before the position. On a tie the first
+            // segment wins at the position itself and the last one before it.
+            if (column > target)
+                continue;
+            if (current && (current.column > column || (current.column === column && column === target)))
+                continue;
+            best[index] = {
+                column,
+                segment: source === NONE ? null : { source, line: originalLine, column: originalColumn, name },
+            };
+        }
+    });
+    return best.map((found) => found?.segment ?? null);
+}

package/dist/source-map-scopes.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Function scopes uploaded with a source map (`x_autter_scopes`, written by
+ * `autter-runtime sourcemaps upload` in @autter/runtime-cli after 1.0.0):
+ * every function of the bundle as served, with its generated range and its
+ * ORIGINAL name. A frame is named after the innermost function that
+ * contains it — the name of the function it is in, as Sentry's
+ * js-source-scopes and PostHog cymbal's `token.scope()` do — instead of the
+ * name mapped at its caller's position, which is wrong whenever the call
+ * goes through a variable or a framework.
+ *
+ * Shape: `{ version: 1, names: (string | null)[], scopes: string }`.
+ * `scopes` is encoded like `mappings`: base64 VLQ, `;` between generated
+ * lines (the line each scope starts on), `,` between the scopes that start
+ * on one line, in start order (outer first on a tie). Each scope is 3 or 4
+ * values, 0-based and in UTF-16 columns:
+ *
+ *   1. start column, relative to the previous scope's start on the same
+ *      line (absolute for a line's first scope);
+ *   2. end line, relative to the start line;
+ *   3. end column (exclusive), relative to the start column when the scope
+ *      ends on its start line, else absolute;
+ *   4. the name, when the function has one: an index into the map's own
+ *      `names` followed by `x_autter_scopes.names`, relative to the last
+ *      name index written (starting from 0). A `null` entry in
+ *      `x_autter_scopes.names` is a name the CLI could not map back.
+ *
+ * A 3-value scope is anonymous. Anything else (wrong version, bad VLQ,
+ * out-of-range names, ranges that overlap without nesting) makes the whole
+ * field unusable, and the map is used as if it had none.
+ */
+export declare const SCOPES_KEY = "x_autter_scopes";
+export type ScopeName = 
+/** In a function with a known original name. */
+{
+    kind: "named";
+    name: string;
+}
+/** In an anonymous function, or in no function at all (top-level code). */
+ | {
+    kind: "anonymous";
+}
+/** In a named function whose original name is unknown. */
+ | {
+    kind: "unknown";
+};
+export declare class ScopeIndex {
+    /** STRIDE ints per scope, sorted by start (outer first on a tie). */
+    private readonly table;
+    /** The map's own `names`, then `x_autter_scopes.names`. */
+    private readonly mapNames;
+    private readonly extraNames;
+    private constructor();
+    /** Number of function scopes. */
+    get size(): number;
+    /** Estimated memory, for the source map cache's byte budget (the map's
+     * own `names` are counted with the map). */
+    get bytes(): number;
+    /**
+     * The parsed `x_autter_scopes` value, or null when it is absent or
+     * malformed. `mapNames` is the map's own `names` array, which scope name
+     * indexes continue.
+     */
+    static from(raw: unknown, mapNames?: readonly unknown[]): ScopeIndex | null;
+    private nameOf;
+    /**
+     * The name for a frame at a 0-based generated (line, column): the
+     * innermost function containing it. Outside every function (top-level
+     * code) it is anonymous.
+     */
+    nameAt(line: number, column: number): ScopeName;
+}