@autter/otlp-ingester 1.6.0 → 1.7.0

package/dist/normalize-otlp.js

@@ -5,6 +5,7 @@ import { scrubText } from "./redact.js";
 import { normalizeRoute } from "./fingerprint.js";
 import { extractLlmCall } from "./llm.js";
 import { BREADCRUMBS_ATTRIBUTE, breadcrumbsField } from "./breadcrumbs.js";
+import { dedupeTraceSignals, hasAutterKey, hasNextContext } from "./trace-dedupe.js";
 import { asSeverity, } from "./types.js";
 const EMAIL_VALUE_RE = /[A-Z0-9._%+-]{1,64}@[A-Z0-9.-]{1,253}\.[A-Z]{2,63}/gi;
 function attrMap(attributes) {
@@ -100,8 +101,10 @@ function severityOf(eventAttrs, spanAttrs) {
 }
 const MAX_SPANS_PER_REQUEST = 5000;
 export function normalizeTraces(request) {
-    const occurrences = [];
-    const occurrenceSpanIds = [];
+    const signals = [];
+    // Per signal: whether a server span's request rollup already counts it,
+    // and the route its own rollup keys on (before HTTP inheritance).
+    const signalRollups = [];
     const spans = [];
     const llmCalls = [];
     const rollups = new Map();
@@ -143,39 +146,56 @@ export function normalizeTraces(request) {
                     },
                     startedAt,
                 });
-                // Error occurrences: one per exception event; if the span is
+                // Error signals: one per exception event; if the span is
                 // errored without exception events, one from the span status.
-                const occurrencesBefore = occurrences.length;
+                // They become occurrences after the batch-wide dedupe below.
+                const traceId = span.traceId ?? "";
+                const spanId = span.spanId ?? "";
+                const rollup = {
+                    onRequestRollup: kind === "server" && attrs.get("autter.tail_retained") !== "true",
+                    route: route ?? "",
+                };
+                const spanAutter = attrs.has("autter.severity");
                 const exceptionEvents = (span.events ?? []).filter((event) => event.name === "exception");
                 for (const event of exceptionEvents) {
                     const eventAttrs = attrMap(event.attributes);
                     const handled = eventAttrs.get("autter.handled") === "true";
-                    occurrenceSpanIds.push(span.spanId ?? "");
-                    occurrences.push({
-                        source: "server",
-                        severity: severityOf(eventAttrs, attrs),
-                        service: resource.service,
-                        environment: resource.environment,
-                        release: resource.release,
-                        errorType: eventAttrs.get("exception.type") ?? "Error",
-                        message: eventAttrs.get("exception.message") ??
-                            span.status?.message ??
-                            span.name ??
-                            "Unknown error",
-                        stack: eventAttrs.get("exception.stacktrace") ?? null,
-                        route,
-                        method: methodOf(attrs),
-                        statusCode,
-                        traceId: span.traceId ?? null,
-                        sessionId: null,
-                        attributes: sanitizeRuntimeContext({ ...decodeOtlpAttributes(span.attributes), ...decodeOtlpAttributes(event.attributes),
-                            ...(handled ? { "autter.handled": true, "autter.sampled": eventAttrs.get("autter.sampled") === "true" } : {}) }),
-                        occurredAt: nanosToDate(event.timeUnixNano ?? span.startTimeUnixNano),
-                        // Event attributes first: one span can carry several
-                        // exceptions, each with its own code.
-                        ...liftErrorFields(eventAttrs, attrs),
-                        ...breadcrumbsField(eventAttrs.get(BREADCRUMBS_ATTRIBUTE), attrs.get(BREADCRUMBS_ATTRIBUTE)),
-                        ...fingerprintOverrideOf(eventAttrs.get("autter.fingerprint") ?? attrs.get("autter.fingerprint")),
+                    const eventAutter = hasAutterKey(eventAttrs);
+                    signalRollups.push(rollup);
+                    signals.push({
+                        traceId,
+                        spanId,
+                        signal: "exception",
+                        autterCapture: eventAutter || spanAutter,
+                        eventAutter,
+                        nextContext: hasNextContext(eventAttrs, attrs),
+                        handled,
+                        occurrence: {
+                            source: "server",
+                            severity: severityOf(eventAttrs, attrs),
+                            service: resource.service,
+                            environment: resource.environment,
+                            release: resource.release,
+                            errorType: eventAttrs.get("exception.type") ?? "Error",
+                            message: eventAttrs.get("exception.message") ??
+                                span.status?.message ??
+                                span.name ??
+                                "Unknown error",
+                            stack: eventAttrs.get("exception.stacktrace") ?? null,
+                            route,
+                            method: methodOf(attrs),
+                            statusCode,
+                            traceId: span.traceId ?? null,
+                            sessionId: null,
+                            attributes: sanitizeRuntimeContext({ ...decodeOtlpAttributes(span.attributes), ...decodeOtlpAttributes(event.attributes),
+                                ...(handled ? { "autter.handled": true, "autter.sampled": eventAttrs.get("autter.sampled") === "true" } : {}) }),
+                            occurredAt: nanosToDate(event.timeUnixNano ?? span.startTimeUnixNano),
+                            // Event attributes first: one span can carry several
+                            // exceptions, each with its own code.
+                            ...liftErrorFields(eventAttrs, attrs),
+                            ...breadcrumbsField(eventAttrs.get(BREADCRUMBS_ATTRIBUTE), attrs.get(BREADCRUMBS_ATTRIBUTE)),
+                            ...fingerprintOverrideOf(eventAttrs.get("autter.fingerprint") ?? attrs.get("autter.fingerprint")),
+                        },
                     });
                 }
                 const failedOutcomes = (span.events ?? []).filter((event) => {
@@ -186,40 +206,58 @@ export function normalizeTraces(request) {
                 for (const event of failedOutcomes) {
                     const outcome = attrMap(event.attributes);
                     const name = (outcome.get("autter.outcome.name") ?? "operation").replace(EMAIL_VALUE_RE, "[redacted]").slice(0, 200);
-                    occurrenceSpanIds.push(span.spanId ?? "");
-                    occurrences.push({
-                        source: "server", severity: "error", service: resource.service,
-                        environment: resource.environment, release: resource.release,
-                        errorType: "OutcomeFailure",
-                        message: `${name}: ${(outcome.get("autter.outcome.message") ?? "failed").replace(EMAIL_VALUE_RE, "[redacted]").slice(0, 1000)}`,
-                        stack: String(decodeOtlpAttributes(event.attributes)["autter.outcome.stack"] ?? "") || null, route, method: methodOf(attrs), statusCode,
-                        traceId: span.traceId ?? null, sessionId: null,
-                        attributes: sanitizeRuntimeContext({ ...decodeOtlpAttributes(span.attributes), ...decodeOtlpAttributes(event.attributes) }),
-                        occurredAt: nanosToDate(event.timeUnixNano ?? span.startTimeUnixNano),
-                        ...liftErrorFields(outcome, attrs),
+                    signalRollups.push(rollup);
+                    signals.push({
+                        traceId,
+                        spanId,
+                        signal: "outcome",
+                        autterCapture: true,
+                        eventAutter: true,
+                        nextContext: hasNextContext(outcome, attrs),
+                        handled: false,
+                        occurrence: {
+                            source: "server", severity: "error", service: resource.service,
+                            environment: resource.environment, release: resource.release,
+                            errorType: "OutcomeFailure",
+                            message: `${name}: ${(outcome.get("autter.outcome.message") ?? "failed").replace(EMAIL_VALUE_RE, "[redacted]").slice(0, 1000)}`,
+                            stack: String(decodeOtlpAttributes(event.attributes)["autter.outcome.stack"] ?? "") || null, route, method: methodOf(attrs), statusCode,
+                            traceId: span.traceId ?? null, sessionId: null,
+                            attributes: sanitizeRuntimeContext({ ...decodeOtlpAttributes(span.attributes), ...decodeOtlpAttributes(event.attributes) }),
+                            occurredAt: nanosToDate(event.timeUnixNano ?? span.startTimeUnixNano),
+                            ...liftErrorFields(outcome, attrs),
+                        },
                     });
                 }
                 if (exceptionEvents.length === 0 && failedOutcomes.length === 0 && isError) {
-                    occurrenceSpanIds.push(span.spanId ?? "");
-                    occurrences.push({
-                        source: "server",
-                        severity: severityOf(new Map(), attrs),
-                        service: resource.service,
-                        environment: resource.environment,
-                        release: resource.release,
-                        errorType: statusCode !== null && statusCode >= 500 ? "HttpServerError" : "SpanError",
-                        message: span.status?.message || (statusCode !== null && statusCode >= 500
-                            ? `${methodOf(attrs) ?? "HTTP"} ${route ?? span.name ?? "request"} returned ${statusCode}`
-                            : `${span.name ?? "span"} failed`),
-                        stack: null,
-                        route,
-                        method: methodOf(attrs),
-                        statusCode,
-                        traceId: span.traceId ?? null,
-                        sessionId: null,
-                        attributes: decodeOtlpAttributes(span.attributes),
-                        occurredAt: startedAt,
-                        ...liftErrorFields(attrs),
+                    signalRollups.push(rollup);
+                    signals.push({
+                        traceId,
+                        spanId,
+                        signal: "status",
+                        autterCapture: spanAutter,
+                        eventAutter: false,
+                        nextContext: hasNextContext(attrs),
+                        handled: false,
+                        occurrence: {
+                            source: "server",
+                            severity: severityOf(new Map(), attrs),
+                            service: resource.service,
+                            environment: resource.environment,
+                            release: resource.release,
+                            errorType: statusCode !== null && statusCode >= 500 ? "HttpServerError" : "SpanError",
+                            message: span.status?.message || (statusCode !== null && statusCode >= 500
+                                ? `${methodOf(attrs) ?? "HTTP"} ${route ?? span.name ?? "request"} returned ${statusCode}`
+                                : `${span.name ?? "span"} failed`),
+                            stack: null,
+                            route,
+                            method: methodOf(attrs),
+                            statusCode,
+                            traceId: span.traceId ?? null,
+                            sessionId: null,
+                            attributes: decodeOtlpAttributes(span.attributes),
+                            occurredAt: startedAt,
+                            ...liftErrorFields(attrs),
+                        },
                     });
                 }
                 // LLM provider calls (GenAI semconv, Vercel AI SDK telemetry,
@@ -249,7 +287,7 @@ export function normalizeTraces(request) {
                 // ships those at ~100% alongside a metrics pipeline that already
                 // counts every request, so folding them in would double-count
                 // erroring routes.
-                if (kind === "server" && attrs.get("autter.tail_retained") !== "true") {
+                if (rollup.onRequestRollup) {
                     addToRollup(rollups, {
                         service: resource.service,
                         environment: resource.environment,
@@ -262,33 +300,42 @@ export function normalizeTraces(request) {
                         sessionCount: 0,
                     });
                 }
-                else {
-                    // Occurrences on non-server spans (captureException's internal
-                    // error spans, workers, consumers) have no request rollup to
-                    // ride — count each as one event / one error event, or a
-                    // service whose errors arrive outside HTTP handlers groups
-                    // issues while every event counter stays 0. Server spans are
-                    // excluded: their request rollup above already represents them.
-                    for (const occ of occurrences.slice(occurrencesBefore)) {
-                        addToRollup(rollups, {
-                            service: occ.service,
-                            environment: occ.environment,
-                            release: occ.release,
-                            route: occ.route ?? "",
-                            bucketAt: minuteBucket(occ.occurredAt),
-                            requestCount: 1,
-                            errorCount: occ.severity === "fatal" || occ.severity === "error" ? 1 : 0,
-                            durationSumMs: 0,
-                            sessionCount: 0,
-                        });
-                    }
-                }
             }
         }
     }
-    inheritHttpFromParent(occurrences, occurrenceSpanIds, spans);
+    // One occurrence per thrown error: recordings of one error on several
+    // spans of a trace merge, and status-only occurrences an error on their
+    // span chain explains are dropped (trace-dedupe.ts).
+    const deduped = dedupeTraceSignals(signals, spans);
+    const occurrences = deduped.occurrences;
+    // Occurrences on non-server spans (captureException's internal error
+    // spans, workers, consumers) have no request rollup to ride — count each
+    // as one event / one error event, or a service whose errors arrive
+    // outside HTTP handlers groups issues while every event counter stays 0.
+    // Server spans are excluded: their request rollup above already
+    // represents them, and so does it for a merged error any of whose
+    // recordings sits on one. Counted after the dedupe, so each thrown error
+    // is one event; a dropped status-only occurrence is none.
+    deduped.members.forEach((members, i) => {
+        if (members.some((m) => signalRollups[m].onRequestRollup))
+            return;
+        const occ = occurrences[i];
+        addToRollup(rollups, {
+            service: occ.service,
+            environment: occ.environment,
+            release: occ.release,
+            route: signalRollups[deduped.sourceIndexes[i]].route,
+            bucketAt: minuteBucket(occ.occurredAt),
+            requestCount: 1,
+            errorCount: occ.severity === "fatal" || occ.severity === "error" ? 1 : 0,
+            durationSumMs: 0,
+            sessionCount: 0,
+        });
+    });
+    inheritHttpFromParent(occurrences, deduped.sourceIndexes.map((index) => signals[index].spanId), spans);
     return {
         occurrences,
+        occurrenceBatchIndexes: deduped.sourceIndexes,
         spans,
         metricPoints: [...rollups.values()],
         llmCalls,

package/dist/server.d.ts

@@ -11,4 +11,11 @@ export interface IngesterApp {
      * Autter dashboard). Called after the boot schema warm-up; throttled. */
     reportIngesterInfo: () => Promise<void>;
 }
+/** The only routes an upload key (`autter_rtu_…`, scope "upload") may call. */
+export declare const UPLOAD_KEY_ROUTES: readonly ["/v1/sourcemaps", "/v1/sourcemaps/check"];
+/** The 403 an upload key gets on every other authenticated route. */
+export declare const UPLOAD_KEY_NOT_ALLOWED: {
+    readonly error: "upload_key_not_allowed";
+    readonly detail: string;
+};
 export declare function createIngesterApp(config: IngesterConfig): IngesterApp;

package/dist/server.js

@@ -13,12 +13,20 @@ 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, validateSourceMapCheck } 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";
 import { MIGRATIONS } from "./migrations.js";
 import { BROWSER_SDK_NAME, ingesterVersion, SdkVersionTracker, sdkSightingsFromOtlp, } from "./sdk-versions.js";
+/** The only routes an upload key (`autter_rtu_…`, scope "upload") may call. */
+export const UPLOAD_KEY_ROUTES = ["/v1/sourcemaps", "/v1/sourcemaps/check"];
+/** The 403 an upload key gets on every other authenticated route. */
+export const UPLOAD_KEY_NOT_ALLOWED = {
+    error: "upload_key_not_allowed",
+    detail: "autter_rtu_ keys can only upload source maps (POST /v1/sourcemaps and /v1/sourcemaps/check); " +
+        "telemetry needs a server key (autter_rt_…), or a client key (autter_rtc_…) for /v1/browser",
+};
 /** 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;
@@ -84,7 +92,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, "sourcemaps");
+        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"],
@@ -164,7 +205,12 @@ export function createIngesterApp(config) {
         res.setHeader("cache-control", "no-store");
         res.status(200).json(body);
     });
-    /** Auth + scope + rate limit; returns null (response sent) on failure. */
+    /**
+     * Auth + scope + rate limit; returns null (response sent) on failure.
+     * Server keys pass everywhere; client keys only on "browser"; upload
+     * keys only on "sourcemaps". A new route that passes "otlp" is closed to
+     * client and upload keys without further changes.
+     */
     async function authenticate(req, res, surface) {
         // A storage-less ingester must refuse, not accept-and-drop: exporters
         // retry on 503, so telemetry survives a misconfigured deploy.
@@ -182,12 +228,22 @@ export function createIngesterApp(config) {
             res.status(401).json({ error: "invalid ingest key" });
             return null;
         }
-        if (ctx.scope === "client") {
+        if (ctx.scope === "upload") {
+            // CI keys: source map upload and check only. Server rate window
+            // (each key has its own).
+            if (surface !== "sourcemaps") {
+                res.status(403).json(UPLOAD_KEY_NOT_ALLOWED);
+                return null;
+            }
+        }
+        else if (ctx.scope === "client") {
             // Publishable keys: browser surface only, origin allow-list, and
             // the tighter rate window.
             if (surface !== "browser") {
                 res.status(403).json({
-                    error: "client keys cannot send OTLP — use a server key",
+                    error: surface === "sourcemaps"
+                        ? "client keys cannot upload source maps — use an upload key (autter_rtu_…) or a server key"
+                        : "client keys cannot send OTLP — use a server key",
                 });
                 return null;
             }
@@ -203,6 +259,12 @@ export function createIngesterApp(config) {
             }
             return ctx;
         }
+        else if (ctx.scope !== "server") {
+            // KeyResolver never yields another scope; refuse rather than
+            // treat an unknown one as a server key.
+            res.status(403).json({ error: "key scope not allowed" });
+            return null;
+        }
         if (!serverRateLimiter.allow(key)) {
             res.status(429).json({ error: "rate limit exceeded" });
             return null;
@@ -242,8 +304,13 @@ export function createIngesterApp(config) {
      * `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) {
+     * to resolve the issue from.
+     *
+     * `batchIndexes` (traces): each occurrence's position among the batch's
+     * signals before the per-trace dedupe, so a merged occurrence keeps the
+     * id of the recording it kept and a drop never shifts another's id.
+     * Defaults to the position in `inputs`. */
+    async function fingerprintAll(ctx, inputs, batchIndexes) {
         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
@@ -258,7 +325,7 @@ export function createIngesterApp(config) {
             const { debugIds: _debugIds, ...stored } = input;
             return {
                 ...stored,
-                occurrenceId: occurrenceIdFor(ctx, input, fingerprint, index),
+                occurrenceId: occurrenceIdFor(ctx, input, fingerprint, batchIndexes?.[index] ?? index),
                 fingerprint,
                 fingerprintScheme: scheme,
                 ...deriveFields(input),
@@ -341,29 +408,10 @@ export function createIngesterApp(config) {
             storageError(res, err);
         }
     });
-    app.post("/v1/sourcemaps", 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" });
-            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 (err) {
-            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");
+        const ctx = await authenticate(req, res, "sourcemaps");
         if (!ctx)
             return;
         const check = validateSourceMapCheck(req.body);
@@ -418,8 +466,8 @@ export function createIngesterApp(config) {
         else {
             request = req.body;
         }
-        const { occurrences, spans, metricPoints, llmCalls } = normalizeTraces(request);
-        const fingerprinted = await fingerprintAll(ctx, occurrences);
+        const { occurrences, occurrenceBatchIndexes, spans, metricPoints, llmCalls } = normalizeTraces(request);
+        const fingerprinted = await fingerprintAll(ctx, occurrences, occurrenceBatchIndexes);
         // 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

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>;