rea-agents 6.0.0 → 6.1.0

package/dist/hopper/HopperRequestQueue.js

@@ -1,5 +1,8 @@
-import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, } from "../domain/hopperErrors.js";
+import { hopperOperationStage } from "./HopperOperationStage.js";
+import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, HopperTimeoutError, } from "../domain/hopperErrors.js";
 import { err } from "../domain/result.js";
+/** Node timer ceiling; larger deadlines would be clamped instead of honored. */
+const MAX_TIMEOUT_MS = 2_147_483_647;
 /** FIFO that keeps the wire serialized until Hopper actually replies. */
 export class HopperRequestQueue {
     send;
@@ -8,10 +11,18 @@ export class HopperRequestQueue {
     constructor(send) {
         this.send = send;
     }
-    /** Queue one request until Hopper replies or the caller cancels it. */
+    /** Settle the caller on reply, cancellation, or deadline; retain active wire work. */
     run(id, method, params, options) {
         if (options.signal?.aborted === true)
             return Promise.resolve(err(new HopperCancelledError()));
+        const timeoutMs = options.timeoutMs;
+        if (timeoutMs !== undefined &&
+            (!Number.isInteger(timeoutMs) ||
+                timeoutMs < 0 ||
+                timeoutMs > MAX_TIMEOUT_MS))
+            return Promise.resolve(err(new HopperProtocolError(`Hopper timeoutMs must be an integer between 0 and ${String(MAX_TIMEOUT_MS)}`)));
+        if (timeoutMs === 0)
+            return Promise.resolve(err(new HopperTimeoutError(0, method, id, "not_started", hopperOperationStage(method))));
         return new Promise((resolve) => {
             let entry;
             const onAbort = options.signal === undefined ? undefined : () => this.#cancel(entry);
@@ -25,12 +36,18 @@ export class HopperRequestQueue {
                 onAbort,
                 callerState: "waiting",
                 callerSettled: false,
+                transmitted: false,
                 startedAt: undefined,
                 heartbeat: undefined,
+                deadline: undefined,
+                deadlineAt: timeoutMs === undefined ? undefined : performance.now() + timeoutMs,
+                timeoutMs,
             };
             this.#queue.push(entry);
             if (onAbort !== undefined)
                 options.signal?.addEventListener("abort", onAbort, { once: true });
+            if (timeoutMs !== undefined)
+                entry.deadline = setTimeout(() => this.#cancel(entry, this.#timeoutError(entry, timeoutMs)), timeoutMs);
             if (this.#active !== undefined || this.#queue.length > 1)
                 this.#report(entry, `${method} queued behind ${String(this.#size() - 1)} Hopper request(s)`);
             this.#drain();
@@ -41,17 +58,10 @@ export class HopperRequestQueue {
         const entry = this.#active;
         if (entry === undefined || entry.id !== id)
             return false;
+        this.#expireIfElapsed(entry);
         this.#releaseWire(entry);
-        if (!entry.callerSettled) {
-            const contextual = !result.ok && result.error instanceof HopperRemoteError
-                ? err(new HopperRemoteError(result.error.code, result.error.safeMessage, {
-                    diagnosticType: result.error.diagnosticType,
-                    operation: entry.method,
-                    requestId: entry.id,
-                }))
-                : result;
-            this.#settleCaller(entry, contextual, "waiting");
-        }
+        if (!entry.callerSettled)
+            this.#settleCaller(entry, result.ok ? result : err(withRequestContext(result.error, entry)), "waiting");
         this.#active = undefined;
         this.#drain();
         return true;
@@ -120,6 +130,10 @@ export class HopperRequestQueue {
         const entry = this.#queue.shift();
         if (entry === undefined)
             return;
+        if (this.#expireIfElapsed(entry)) {
+            this.#drain();
+            return;
+        }
         if (entry.signal?.aborted === true) {
             this.#settleCaller(entry, err(new HopperCancelledError()), "cancelled");
             this.#drain();
@@ -128,6 +142,17 @@ export class HopperRequestQueue {
         this.#active = entry;
         entry.startedAt = performance.now();
         this.#report(entry, `${entry.method} started on Hopper's serial bridge`);
+        this.#expireIfElapsed(entry);
+        // A progress observer may cancel or tear down synchronously before send.
+        // No native work exists yet, so it is safe to release this reserved slot.
+        if (this.#active !== entry || entry.callerSettled) {
+            if (this.#active === entry) {
+                this.#active = undefined;
+                this.#releaseWire(entry);
+                this.#drain();
+            }
+            return;
+        }
         entry.heartbeat = setInterval(() => {
             if (entry.callerSettled || entry.startedAt === undefined)
                 return;
@@ -135,30 +160,44 @@ export class HopperRequestQueue {
             this.#report(entry, `${entry.method} is still running in Hopper (${String(elapsed)} ms elapsed)`);
         }, 1_000);
         try {
-            this.send({ id: entry.id, method: entry.method, params: entry.params }, () => this.accept(entry.id, err(new HopperProcessError(null))));
+            entry.transmitted = true;
+            this.send({ id: entry.id, method: entry.method, params: entry.params }, () => this.accept(entry.id, err(new HopperProcessError(null, undefined, entry.method, entry.id, "unreachable", hopperOperationStage(entry.method)))));
         }
         catch (cause) {
             this.accept(entry.id, err(new HopperProtocolError("Hopper socket write failed", { cause })));
         }
     }
-    #cancel(entry) {
+    #timeoutError(entry, timeoutMs) {
+        return new HopperTimeoutError(timeoutMs, entry.method, entry.id, entry.transmitted ? "busy" : "not_started", hopperOperationStage(entry.method));
+    }
+    #expireIfElapsed(entry) {
+        if (entry.deadlineAt !== undefined &&
+            entry.timeoutMs !== undefined &&
+            performance.now() >= entry.deadlineAt)
+            this.#settleCaller(entry, err(this.#timeoutError(entry, entry.timeoutMs)), "cancelled");
+        return entry.callerSettled;
+    }
+    #cancel(entry, error = new HopperCancelledError()) {
         if (entry.callerSettled)
             return;
         if (this.#active === entry) {
-            this.#settleCaller(entry, err(new HopperCancelledError()), "cancelled");
+            this.#settleCaller(entry, err(error), "cancelled");
             return;
         }
         const index = this.#queue.indexOf(entry);
         if (index < 0)
             return;
         this.#queue.splice(index, 1);
-        this.#settleCaller(entry, err(new HopperCancelledError()), "cancelled");
+        this.#settleCaller(entry, err(error), "cancelled");
     }
     #settleCaller(entry, result, callerState) {
         if (entry.callerSettled)
             return;
         entry.callerSettled = true;
         entry.callerState = callerState;
+        if (entry.deadline !== undefined)
+            clearTimeout(entry.deadline);
+        entry.deadline = undefined;
         if (this.#active === entry && entry.heartbeat !== undefined) {
             clearInterval(entry.heartbeat);
             entry.heartbeat = undefined;
@@ -195,6 +234,16 @@ export class HopperRequestQueue {
         }
     }
 }
-const withRequestContext = (error, entry) => error instanceof HopperProcessError
-    ? new HopperProcessError(error.exitCode, error.diagnostic, entry.method, entry.id)
-    : error;
+const withRequestContext = (error, entry) => {
+    if (error instanceof HopperProcessError)
+        return new HopperProcessError(error.exitCode, error.diagnostic, error.operation ?? entry.method, error.requestId ?? entry.id, error.providerState, error.operation === undefined && error.stage === "connection"
+            ? hopperOperationStage(entry.method)
+            : error.stage);
+    if (error instanceof HopperRemoteError)
+        return new HopperRemoteError(error.code, error.safeMessage, {
+            diagnosticType: error.diagnosticType,
+            operation: error.operation ?? entry.method,
+            requestId: error.requestId ?? entry.id,
+        });
+    return error;
+};

package/dist/hopper/HopperTargetLease.js

@@ -4,10 +4,11 @@ import { createConnection, createServer, } from "node:net";
 import { join, resolve } from "node:path";
 import { HopperStartError } from "../domain/hopperErrors.js";
 import { safeParseJson } from "../domain/safeJson.js";
-const leaseDirectory = join("/tmp", `rea-hopper-${process.getuid?.() ?? 0}`);
+/** Shared private parent of per-target lease sockets; it outlives individual sessions. */
+export const HOPPER_TARGET_LEASE_DIRECTORY = join("/tmp", `rea-hopper-${process.getuid?.() ?? 0}`);
 /** Keep two REA processes from opening duplicate Hopper documents for one target/profile. */
 export const acquireHopperTargetLease = async (input) => {
-    const directory = input.directory ?? leaseDirectory;
+    const directory = input.directory ?? HOPPER_TARGET_LEASE_DIRECTORY;
     await ensureLeaseDirectory(directory);
     // The canonical path only derives the lease key; it never authorizes access.
     // Common expected `realpath` failures include a missing target or path

package/dist/inspector/JavaScriptRuntimeScope.js

@@ -1,6 +1,12 @@
 import { pathToFileURL } from "node:url";
 import { browserOriginSchema, sanitizeBrowserUrl, } from "../domain/browserObservation.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { authorizedElectronFile } from "../browser/ElectronFileScope.js";
+/** Throw the operation's typed cancellation error whenever its signal is aborted. */
+export const throwIfRuntimeObservationCancelled = (signal) => {
+    if (signal?.aborted === true)
+        throw new AnalysisCancelledError("observe_javascript_runtime");
+};
 /**
  * Wire bucket for inspector script exclusions. The V8 observation schemas
  * fix the `unsupported_location` key, so every canonical denial reason maps
@@ -13,7 +19,8 @@ export const inspectorExclusionKey = (reason) => {
     return "unsupported_location";
 };
 /** Resolve a protocol location exposed by the explicitly selected Inspector endpoint. */
-export const authorizeRuntimeLocation = async (value) => {
+export const authorizeRuntimeLocation = async (value, signal) => {
+    throwIfRuntimeObservationCancelled(signal);
     if (value.startsWith("node:") && value.length > 0)
         return {
             allowed: true,
@@ -21,6 +28,7 @@ export const authorizeRuntimeLocation = async (value) => {
         };
     if (value.startsWith("file:")) {
         const filePath = await authorizedElectronFile(value);
+        throwIfRuntimeObservationCancelled(signal);
         return filePath === undefined
             ? { allowed: false, reason: "not_approved" }
             : { allowed: true, location: { kind: "file", file_path: filePath } };

package/dist/inspector/V8InspectorCaptureProjection.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { authorizeRuntimeLocation, inspectorExclusionKey, } from "./JavaScriptRuntimeScope.js";
+import { authorizeRuntimeLocation, inspectorExclusionKey, throwIfRuntimeObservationCancelled, } from "./JavaScriptRuntimeScope.js";
 /** Empty durable-location exclusion counters. */
 export const createInspectorExclusionCounts = () => ({
     unsupported_location: 0,
@@ -15,7 +15,8 @@ export const describeInspectorTargetLimitations = () => [
 ];
 const LOCATION_AUTHORIZATION_WORKERS = 8;
 /** Canonically authorize, deduplicate, and sort one bounded raw capture. */
-export const finalizeInspectorCapture = async ({ input, runtime, target, state, authorizeLocation = authorizeRuntimeLocation, }) => {
+export const finalizeInspectorCapture = async ({ input, runtime, target, state, authorizeLocation = authorizeRuntimeLocation, signal, }) => {
+    throwIfRuntimeObservationCancelled(signal);
     const exclusions = createInspectorExclusionCounts();
     const scripts = new Map();
     const draftsByUrl = new Map();
@@ -31,6 +32,7 @@ export const finalizeInspectorCapture = async ({ input, runtime, target, state,
     const worker = async () => {
         try {
             for (;;) {
+                throwIfRuntimeObservationCancelled(signal);
                 if (stopScheduling)
                     return;
                 const index = nextGroup;
@@ -41,8 +43,9 @@ export const finalizeInspectorCapture = async ({ input, runtime, target, state,
                 const [rawUrl, drafts] = group;
                 authorizedGroups[index] = {
                     drafts,
-                    decision: await authorizeLocation(rawUrl),
+                    decision: await authorizeLocation(rawUrl, signal),
                 };
+                throwIfRuntimeObservationCancelled(signal);
             }
         }
         catch (cause) {
@@ -52,6 +55,7 @@ export const finalizeInspectorCapture = async ({ input, runtime, target, state,
     };
     const workerResults = await Promise.allSettled(Array.from({ length: Math.min(LOCATION_AUTHORIZATION_WORKERS, groups.length) }, worker));
     const failedWorker = workerResults.find((result) => result.status === "rejected");
+    throwIfRuntimeObservationCancelled(signal);
     if (failedWorker?.status === "rejected")
         throw failedWorker.reason;
     for (const { drafts, decision } of authorizedGroups) {
@@ -81,6 +85,7 @@ export const finalizeInspectorCapture = async ({ input, runtime, target, state,
         : left.context_key > right.context_key
             ? 1
             : 0);
+    throwIfRuntimeObservationCancelled(signal);
     return {
         runtime,
         target: {

package/dist/inspector/V8InspectorProvider.js

@@ -12,6 +12,11 @@ import { discoverV8Inspector, } from "./V8InspectorEndpoint.js";
 /** Public identity committed by passive V8 Inspector observations. */
 export { V8_INSPECTOR_PROVIDER_IDENTITY } from "./providerIdentity.js";
 import { V8_INSPECTOR_PROVIDER_IDENTITY } from "./providerIdentity.js";
+/** Maximum decoded CDP message accepted while observing one Inspector target. */
+export const INSPECTOR_MAX_PAYLOAD_BYTES = 16 * 1024 * 1024;
+/** Aggregate retained metadata budget, including an estimate of JS object overhead. */
+export const INSPECTOR_MAX_RETAINED_METADATA_BYTES = 8 * 1024 * 1024;
+const RETAINED_OBJECT_OVERHEAD_BYTES = 512;
 /** Attach-only provider; sends only Runtime.enable and Debugger.enable. */
 export class V8InspectorProvider {
     identity() {
@@ -61,7 +66,7 @@ export class V8InspectorProvider {
             const target = await authorizedTarget(discovery.targets, input, discovery.runtime.product);
             if (input.runtime_kind !== undefined)
                 assertRuntimeKind(target, input.runtime_kind);
-            connection = await CdpConnection.connect(target.webSocketUrl, "observe_javascript_runtime", options.signal);
+            connection = await CdpConnection.connect(target.webSocketUrl, "observe_javascript_runtime", options.signal, { maxPayloadBytes: INSPECTOR_MAX_PAYLOAD_BYTES });
             const state = emptyCaptureState();
             const removeListener = connection.onEvent((event) => ingestEvent(event, input, state));
             try {
@@ -77,6 +82,7 @@ export class V8InspectorProvider {
                 runtime: discovery.runtime,
                 target,
                 state,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
             outcome = ok(javascriptRuntimeObservationSchema.parse(result));
         }
@@ -206,15 +212,24 @@ const ingestScript = (event, input, state) => {
         length: nonnegativeInteger(value?.length),
         isModule: value?.isModule === true,
     };
-    const bytes = metadataBytes(draft);
-    retainEvent(state, bytes);
+    const bytes = retainedMetadataBytes(draft);
+    if (!retainEvent(state, bytes))
+        return;
     state.scripts.push(draft);
 };
 const ingestContext = (event, input, state) => {
     if (event.method === "Runtime.executionContextsCleared") {
-        for (const context of state.contexts.values())
-            context.state = "cleared";
-        retainEvent(state, 0);
+        let byteDelta = 0;
+        for (const context of state.contexts.values()) {
+            byteDelta +=
+                retainedMetadataBytes({ ...context, state: "cleared" }) -
+                    retainedMetadataBytes(context);
+        }
+        if (replaceRetainedMetadata(state, byteDelta)) {
+            for (const context of state.contexts.values())
+                context.state = "cleared";
+            retainEvent(state, 0);
+        }
         return;
     }
     const parameters = recordValue(event.params);
@@ -238,18 +253,33 @@ const ingestContext = (event, input, state) => {
             : "destroyed",
         origin: origin === "" ? null : origin,
     };
-    const bytes = metadataBytes(draft);
-    retainEvent(state, bytes);
+    const previous = state.contexts.get(key);
+    const bytes = retainedMetadataBytes(draft) -
+        (previous === undefined ? 0 : retainedMetadataBytes(previous));
+    if (!retainEvent(state, bytes))
+        return;
     state.contexts.set(key, draft);
 };
 const retainEvent = (state, bytes) => {
-    state.metadataBytes += bytes;
+    if (!replaceRetainedMetadata(state, bytes))
+        return false;
     state.eventsRetained += 1;
+    return true;
+};
+const replaceRetainedMetadata = (state, byteDelta) => {
+    if (state.metadataBytes + byteDelta > INSPECTOR_MAX_RETAINED_METADATA_BYTES) {
+        state.eventsDropped += 1;
+        state.truncated = true;
+        state.truncationReasons.add("retained_metadata_budget_exceeded");
+        return false;
+    }
+    state.metadataBytes += byteDelta;
+    return true;
 };
 const waitForCapture = async (connection, observationMs, signal) => {
     let removeDisconnect = () => undefined;
     const disconnected = new Promise((_resolve, reject) => {
-        removeDisconnect = connection.onDisconnect(() => reject(new BrowserObservationError("observe_javascript_runtime", "disconnected")));
+        removeDisconnect = connection.onDisconnect((error) => reject(error));
     });
     try {
         await Promise.race([
@@ -261,7 +291,13 @@ const waitForCapture = async (connection, observationMs, signal) => {
         removeDisconnect();
     }
 };
-const metadataBytes = (value) => Buffer.byteLength(JSON.stringify(value));
+const retainedMetadataBytes = (value) => {
+    const strings = "rawUrl" in value
+        ? [value.rawUrl, value.rawUrl, value.executionContextKey, value.cdpHash]
+        : [value.contextKey, value.origin];
+    return (RETAINED_OBJECT_OVERHEAD_BYTES +
+        strings.reduce((total, text) => total + (text?.length ?? 0) * 2, 0));
+};
 const nonnegativeInteger = (value) => {
     const parsed = numberValue(value);
     return parsed === undefined ? 0 : Math.max(0, Math.trunc(parsed));

package/dist/javascript/sourceMaps/DecodedSourceMap.js

@@ -0,0 +1,47 @@
+import { TraceMap, decodedMappings } from "@jridgewell/trace-mapping";
+import { SourceMapFormatFailure, } from "./SourceMapFormat.js";
+/** Determine whether a leaf-local mapping falls before its enclosing boundary. */
+export const isBeforeSourceMapLeafStop = (leaf, line, column) => {
+    if (leaf.stop === null)
+        return true;
+    const generatedLine = leaf.offset.line + line;
+    const generatedColumn = column + (line === 0 ? leaf.offset.column : 0);
+    return (generatedLine < leaf.stop.line ||
+        (generatedLine === leaf.stop.line && generatedColumn < leaf.stop.column));
+};
+/** Resolve one declaration with the same pinned upstream implementation used by full maps. */
+export const resolveSourceMapSource = (source, sourceRoot, mapUrl) => {
+    const map = new TraceMap({
+        version: 3,
+        names: [],
+        sources: [source ?? ""],
+        ...(sourceRoot == null ? {} : { sourceRoot }),
+        mappings: "",
+    }, mapUrl);
+    const resolved = map.resolvedSources[0];
+    if (resolved === undefined)
+        throw new SourceMapFormatFailure("format", "Source-map resolver did not return the requested source identity.");
+    return resolved;
+};
+/** Decode leaf mappings and validate producer indices before any consumer publishes them. */
+export const decodeValidatedSourceMapLeaves = (leaves, mapUrl, check) => leaves.map((leaf) => {
+    check?.();
+    const map = new TraceMap(JSON.stringify(leaf.map), mapUrl);
+    const rows = decodedMappings(map);
+    for (const [line, row] of rows.entries()) {
+        if ((line & 255) === 0)
+            check?.();
+        for (const segment of row) {
+            const generatedLine = leaf.offset.line + line;
+            const generatedColumn = segment[0] + (line === 0 ? leaf.offset.column : 0);
+            if (!Number.isSafeInteger(generatedLine) ||
+                !Number.isSafeInteger(generatedColumn) ||
+                ![1, 4, 5].includes(segment.length) ||
+                segment.some((value) => !Number.isSafeInteger(value) || value < 0) ||
+                (segment.length !== 1 && segment[1] >= leaf.map.sources.length) ||
+                (segment.length === 5 && segment[4] >= leaf.map.names.length))
+                throw new SourceMapFormatFailure("format", "Decoded local or absolute position, source index or name index is invalid.");
+        }
+    }
+    return { leaf, rows, resolvedSources: map.resolvedSources };
+});

package/dist/javascript/sourceMaps/SourceMapCommand.js

@@ -12,10 +12,26 @@ import { PrivateRuntimeRoot, PrivateRuntimeRootUnavailableError, } from "../../p
 import { ProviderStartupDeadline } from "../../process/ProviderDeadline.js";
 import { cleanupOwnedProcessGroup } from "../../process/ProcessOwnership.js";
 import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../../process/ProviderProcess.js";
+import { prepareProcessOwnershipInspection } from "../../process/ProcessOwnershipObservation.js";
 const OPERATION = "trace_web_source_location";
 const PROVIDER = "source-map-decoder";
 /** Run a trusted codec command and release its process/root before returning output. */
 export const runSourceMapCommand = async (request, path, options, dependencies) => {
+    try {
+        await (dependencies.prepareOwnership ?? prepareProcessOwnershipInspection)(options?.signal);
+    }
+    catch (cause) {
+        return err(options?.signal?.aborted === true
+            ? new AnalysisCancelledError(OPERATION)
+            : new ProviderAdapterError(PROVIDER, OPERATION, {
+                cause,
+                diagnostics: {
+                    map_path: path,
+                    error_message: message(cause),
+                    phase: "process_ownership_preparation",
+                },
+            }));
+    }
     const deadline = new ProviderStartupDeadline(WEB_SOURCE_MAP_LIMITS.decodeTimeoutMs, options?.signal);
     const command = new OwnedCodec(path, dependencies, deadline);
     let result;

package/dist/javascript/sourceMaps/SourceMapFormat.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { WEB_SOURCE_MAP_LIMITS } from "../../domain/webSourceLocation.js";
+import { hasValidSourceMapContents } from "../../domain/sourceMapContents.js";
 const leafSchema = z.object({
     version: z.literal(3),
     file: z.string().nullable().optional(),
@@ -48,9 +49,21 @@ const addOffset = (base, offset) => {
         throw new SourceMapFormatFailure("limit", "Indexed offset exceeds the 262144 generated-row decoder budget.");
     return result;
 };
-const addSections = (node, pending) => {
+const consumeRecords = (budget, count) => {
+    if (count > WEB_SOURCE_MAP_LIMITS.decodedRecords - budget.records)
+        throw new SourceMapFormatFailure("limit", `Source-map structure exceeds the ${WEB_SOURCE_MAP_LIMITS.decodedRecords}-record decoder budget.`);
+    budget.records += count;
+};
+const addSections = (node, pending, budget, options) => {
+    options.check?.();
+    const header = mapHeaderSchema.parse(node.value);
+    if (!Array.isArray(header.sections))
+        throw new SourceMapFormatFailure("format", "Indexed source-map sections must be an array.");
+    consumeRecords(budget, header.sections.length);
     const sections = indexedSchema.parse(node.value).sections;
     for (const [index, section] of sections.entries()) {
+        if ((index & 255) === 0)
+            options.check?.();
         const previous = sections[index - 1];
         if (previous !== undefined && compare(section.offset, previous.offset) <= 0)
             throw new SourceMapFormatFailure("format", "Indexed section offsets must be strictly increasing.");
@@ -81,7 +94,7 @@ const addSections = (node, pending) => {
         });
     }
 };
-const inspectMappingLayout = (mappings) => {
+const inspectMappingLayout = (mappings, check) => {
     let lines = 1;
     let segments = 0;
     let components = 0;
@@ -94,7 +107,10 @@ const inspectMappingLayout = (mappings) => {
         if (inSegment && ![1, 4, 5].includes(components))
             throw new SourceMapFormatFailure("format", "Source-map segment requires one, four or five VLQ components.");
     };
+    let index = 0;
     for (const character of mappings) {
+        if ((index++ & 0x3fff) === 0)
+            check?.();
         if (character === "," || character === ";") {
             finish();
             inSegment = false;
@@ -123,6 +139,35 @@ const inspectMappingLayout = (mappings) => {
     finish();
     return { lines, segments };
 };
+const inspectLeaf = (node, budget, options) => {
+    options.check?.();
+    consumeRecords(budget, 1);
+    if (typeof node.value !== "object" ||
+        node.value === null ||
+        Array.isArray(node.value))
+        return leafSchema.parse(node.value);
+    const rawMap = node.value;
+    const rawSources = rawMap.sources;
+    const rawNames = rawMap.names;
+    const rawContents = rawMap.sourcesContent;
+    consumeRecords(budget, Array.isArray(rawSources) ? rawSources.length : 0);
+    consumeRecords(budget, Array.isArray(rawNames) ? rawNames.length : 0);
+    consumeRecords(budget, Array.isArray(rawContents) ? rawContents.length : 0);
+    options.check?.();
+    if (options.profile === "browser-collection" && !Array.isArray(rawNames))
+        throw new SourceMapFormatFailure("format", "Source-map leaf requires a names array.");
+    if (options.profile === "browser-collection" &&
+        !hasValidSourceMapContents(Array.isArray(rawSources) ? rawSources.length : 0, rawContents))
+        throw new SourceMapFormatFailure("format", "Source-map sourcesContent must align with its source declarations.");
+    options.check?.();
+    const leaf = leafSchema.parse(node.value);
+    const layout = inspectMappingLayout(leaf.mappings, options.check);
+    consumeRecords(budget, layout.segments + layout.lines);
+    if (layout.segments > WEB_SOURCE_MAP_LIMITS.decodedSegments ||
+        node.offset.line + layout.lines > WEB_SOURCE_MAP_LIMITS.decodedRows)
+        throw new SourceMapFormatFailure("limit", "Source-map layout exceeds the 262144 segment/generated-row decoder budget.");
+    return leaf;
+};
 /** Validate structure before allocation, retaining raw declarations and section boundaries. */
 export const inspectSourceMap = (text) => {
     const withoutBom = text.replace(/^\uFEFF/u, "");
@@ -130,53 +175,56 @@ export const inspectSourceMap = (text) => {
         ? withoutBom.slice(withoutBom.indexOf("\n") + 1)
         : withoutBom;
     const value = JSON.parse(jsonText);
+    const inspected = inspectSourceMapValue(value);
+    const normalized = inspected.format === "regular"
+        ? inspected.leaves[0]?.map
+        : {
+            version: 3,
+            sections: inspected.leaves.map((leaf) => ({
+                offset: leaf.offset,
+                map: leaf.map,
+            })),
+        };
+    return {
+        jsonText: JSON.stringify(normalized),
+        ...inspected,
+    };
+};
+/** Return validated leaves when a consumer needs decoded rows after preflight. */
+export const inspectSourceMapValue = (value, options = {}) => {
+    options.check?.();
     const root = mapHeaderSchema.parse(value);
     const declarations = [];
     const leaves = [];
     const pending = [
         { value, path: [], offset: { line: 0, column: 0 }, stop: null },
     ];
-    let segmentCount = 0;
+    const budget = options.budget ?? { records: 0 };
     while (pending.length > 0) {
+        options.check?.();
         const node = pending.pop();
         if (node === undefined)
             break;
         if (node.path.length > WEB_SOURCE_MAP_LIMITS.sectionDepth)
             throw new SourceMapFormatFailure("limit", "Indexed source-map nesting exceeds the 64-level decoder stack budget.");
         if (mapHeaderSchema.parse(node.value).sections !== undefined) {
-            addSections(node, pending);
+            addSections(node, pending, budget, options);
             continue;
         }
-        const leaf = leafSchema.parse(node.value);
-        const layout = inspectMappingLayout(leaf.mappings);
-        segmentCount += layout.segments;
-        if (segmentCount > WEB_SOURCE_MAP_LIMITS.decodedSegments ||
-            node.offset.line + layout.lines > WEB_SOURCE_MAP_LIMITS.decodedRows)
-            throw new SourceMapFormatFailure("limit", "Source-map layout exceeds the 262144 segment/generated-row decoder budget.");
+        const leaf = inspectLeaf(node, budget, options);
         leaves.push({ map: leaf, offset: node.offset, stop: node.stop });
-        for (const [sourceIndex, source] of leaf.sources.entries())
-            declarations.push({
-                sectionPath: node.path,
-                sourceIndex,
-                source,
-                root: leaf.sourceRoot ?? null,
-                content: leaf.sourcesContent?.[sourceIndex] ?? null,
-                ignored: (leaf.ignoreList ?? leaf.x_google_ignoreList ?? []).includes(sourceIndex),
-            });
+        if (options.profile !== "browser-collection")
+            for (const [sourceIndex, source] of leaf.sources.entries())
+                declarations.push({
+                    sectionPath: node.path,
+                    sourceIndex,
+                    source,
+                    root: leaf.sourceRoot ?? null,
+                    content: leaf.sourcesContent?.[sourceIndex] ?? null,
+                    ignored: (leaf.ignoreList ?? leaf.x_google_ignoreList ?? []).includes(sourceIndex),
+                });
     }
-    // Absolute leaves adapt nested first-line column offsets before upstream AnyMap.
-    // Raw map bytes and the original section/source identities are retained separately.
-    const normalized = root.sections === undefined
-        ? leaves[0]?.map
-        : {
-            version: 3,
-            sections: leaves.map((leaf) => ({
-                offset: leaf.offset,
-                map: leaf.map,
-            })),
-        };
     return {
-        jsonText: JSON.stringify(normalized),
         format: root.sections === undefined ? "regular" : "indexed",
         reportedFile: root.file ?? null,
         declarations,