rea-agents 6.2.0 → 6.4.0

package/dist/javascript/recovery/WakaruCommand.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
-import { access, realpath } from "node:fs/promises";
+import { access, realpath, stat } from "node:fs/promises";
 import { isAbsolute } from "node:path";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
@@ -10,7 +10,24 @@ import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../../pro
 import { checkRecoveryDeadline, inventoryRecoveryFiles, fingerprintRecoveryFile, recoveryFailureMessage, } from "./RecoveryFiles.js";
 import { RECOVERY_LIMITS } from "./WakaruRelease.js";
 const OPERATION = "recover_javascript_sources";
-const WAKARU_REQUIREMENT = "Provide an absolute REA_WAKARU_COMMAND pointing to Wakaru 1.13.0 on Linux x64; no tool is installed by REA";
+const WAKARU_REQUIREMENT = "Provide an absolute REA_WAKARU_COMMAND pointing to a Wakaru ^1.13.0 Linux x64 binary (verified with 1.14.0); no tool is installed by REA. See docs/javascript-recovery.md#install-wakaru.";
+/** Cleanup failure carrying the live supervisor so the provider can retry it. */
+export class WakaruCleanupFailure extends ProviderCleanupError {
+    cleanupOwner;
+    runId;
+    cwd;
+    constructor(cleanupOwner, runId, cwd, reason, previousError, snapshot) {
+        super("wakaru", [runId, cwd], {
+            reason,
+            previous_error: previousError instanceof Error ? previousError.message : null,
+            exit_code: snapshot.exitCode ?? null,
+            signal: snapshot.signal ?? null,
+        }, { operation: OPERATION, cause: previousError });
+        this.cleanupOwner = cleanupOwner;
+        this.runId = runId;
+        this.cwd = cwd;
+    }
+}
 /** Resolve and fingerprint explicitly configured tools; acquire nothing at startup. */
 export const resolveWakaruCommand = async (environment) => {
     const configured = environment.REA_WAKARU_COMMAND;
@@ -27,6 +44,8 @@ export const resolveWakaruCommand = async (environment) => {
         if (!isAbsolute(limiter))
             throw new TypeError("REA_JAVASCRIPT_PRLIMIT_COMMAND must be absolute");
         await access(limiter, constants.X_OK);
+        if (!(await stat(limiter)).isFile())
+            throw new TypeError(`Resource limiter is not a regular file: ${limiter}`);
         return { command, limiter, ...fingerprint };
     }
     catch (cause) {
@@ -100,14 +119,8 @@ export const runWakaruCommand = async (context) => {
     }
     const stopped = await supervisor.stop();
     const snapshot = supervisor.snapshot();
-    supervisor.dispose();
     if (stopped.status === "incomplete")
-        throw new ProviderCleanupError("wakaru", [runId, context.cwd], {
-            reason: stopped.reason,
-            previous_error: failure instanceof Error ? failure.message : null,
-            exit_code: snapshot.exitCode ?? null,
-            signal: snapshot.signal ?? null,
-        });
+        throw new WakaruCleanupFailure(supervisor, runId, context.cwd, stopped.reason, failure, snapshot);
     if (failure !== undefined)
         throw failure;
     if (context.signal?.aborted === true)

package/dist/javascript/recovery/WakaruExecution.js

@@ -6,7 +6,8 @@ import { fingerprintRecoveryFile, inventoryRecoveryFiles, readRecoveryFile, reco
 import { runWakaruCommand, } from "./WakaruCommand.js";
 import { parseWakaruReports } from "./WakaruReport.js";
 import { publishWakaruArtifacts } from "./WakaruPublication.js";
-import { RECOVERY_LIMITS, WAKARU_RELEASE, WAKARU_PROVIDER_IDENTITY, } from "./WakaruRelease.js";
+import { RECOVERY_LIMITS, WAKARU_PROVIDER_IDENTITY } from "./WakaruRelease.js";
+import { admitWakaruVersion } from "./WakaruVersion.js";
 const OPERATION = "recover_javascript_sources";
 const MODES = {
     structural: "strict",
@@ -29,10 +30,12 @@ const executeWakaruRecovery = async (context) => {
         ...commandContext,
         arguments: ["--version"],
     });
-    if (version.exit_code !== 0 ||
-        version.stdout.trim() !== `wakaru ${WAKARU_RELEASE.version}`) {
+    const admitted = version.exit_code === 0
+        ? admitWakaruVersion(version.stdout.trim())
+        : undefined;
+    if (admitted === undefined || admitted.status === "unsupported") {
         // The message names the mismatch; the reason also keeps the tool's stderr.
-        const mismatch = `This adapter requires Wakaru ${WAKARU_RELEASE.version}; reported version: ${version.stdout.trim()}; exit: ${String(version.exit_code)}`;
+        const mismatch = `${admitted?.message ?? `Wakaru --version failed; reported version: ${version.stdout.trim()}`}; exit: ${String(version.exit_code)}`;
         throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, `${mismatch}; stderr: ${version.stderr}`, { userMessage: `${mismatch}.` });
     }
     const run = await runWakaruCommand({
@@ -58,19 +61,20 @@ const executeWakaruRecovery = async (context) => {
         sourceBytes: snapshot,
         files,
     });
-    return { version, run, parsed };
+    return { version, admitted, run, parsed };
 };
 /** Publish validated recovery and retain exact source and engine bindings. */
 export const prepareWakaruExecution = async (context) => {
     const { root, tree, input, source, engine, options } = context;
     const staging = join(root, "modules");
-    const { version, run, parsed } = await executeWakaruRecovery(context);
+    const { version, admitted, run, parsed } = await executeWakaruRecovery(context);
     const result = await publishWakaruArtifacts({
         tree,
         staging,
         input,
         source,
         engine,
+        admitted,
         parsed,
         execution: run,
         ...(options?.signal === undefined ? {} : { signal: options.signal }),
@@ -79,7 +83,7 @@ export const prepareWakaruExecution = async (context) => {
         throw new AnalysisOutputError(OPERATION, `Original input changed during recovery: ${input.path}`);
     if ((await fingerprintRecoveryFile(engine.command, RECOVERY_LIMITS.outputBytes, options?.signal)).sha256 !== engine.sha256)
         throw new AnalysisOutputError(OPERATION, "Configured engine bytes changed during recovery");
-    return createAnalysisExecution(result, WAKARU_PROVIDER_IDENTITY, {
+    return createAnalysisExecution(result, { ...WAKARU_PROVIDER_IDENTITY, version: admitted.version }, {
         rawResult: jsonValueSchema.parse({
             version,
             execution: run,

package/dist/javascript/recovery/WakaruProvider.js

@@ -3,29 +3,47 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {} from "../../application/AnalysisProvider.js";
 import { SafeOutputTree } from "../../artifacts/SafeOutputTree.js";
+import { SafeOutputTreeCreationFailure } from "../../artifacts/SafeOutputTreeCreationFailure.js";
 import { AnalysisError } from "../../domain/analysisErrorBase.js";
 import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { javascriptRecoveryResultSchema, } from "../../domain/javascript/javascriptRecovery.js";
 import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
 import { err, ok } from "../../domain/result.js";
 import { checkRecoveryCancellation, checkRecoveryDeadline, recoveryFailureMessage, recoveryInputFailure, snapshotRecoveryInput, } from "./RecoveryFiles.js";
-import { resolveWakaruCommand } from "./WakaruCommand.js";
+import { resolveWakaruCommand, WakaruCleanupFailure, } from "./WakaruCommand.js";
 import { prepareWakaruExecution } from "./WakaruExecution.js";
 import { RECOVERY_LIMITS } from "./WakaruRelease.js";
 const OPERATION = "recover_javascript_sources";
-/** Stateless adapter; each recovery owns its snapshot, process and publication. */
+/** Serialized recovery adapter retaining failed process, workspace and publication cleanup. */
 export class WakaruProvider {
     environment;
     launcher;
+    #tail = Promise.resolve();
+    #closing = false;
+    #closePromise;
+    #pendingCleanup;
     constructor(environment = process.env, launcher) {
         this.environment = environment;
         this.launcher = launcher;
     }
     /** Recover one script using validated upstream reports and verified output bytes. */
-    async recover(input, options) {
+    recover(input, options) {
+        if (this.#closing)
+            return Promise.resolve(err(new ProviderCleanupError("wakaru", [], { reason: "Provider is closing" }, { operation: OPERATION })));
+        const operation = this.#tail.then(() => this.#closing
+            ? err(new ProviderCleanupError("wakaru", [], { reason: "Provider is closing" }, { operation: OPERATION }))
+            : this.#recover(input, options));
+        this.#tail = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    async #recover(input, options) {
+        const pending = await this.#retire();
+        if (pending !== undefined)
+            return err(pending);
         let root;
         let tree;
-        let failure;
+        let failed;
         let execution;
         const deadline = Date.now() + RECOVERY_LIMITS.timeoutMs;
         try {
@@ -37,9 +55,14 @@ export class WakaruProvider {
             await mkdir(inputs, { mode: 0o700 });
             await mkdir(staging, { mode: 0o700 });
             const source = await snapshotRecoveryInput(input.path, join(inputs, "bundle.js"), options?.signal);
-            tree = await SafeOutputTree.create(input.output_directory).catch((cause) => {
+            try {
+                tree = await SafeOutputTree.create(input.output_directory);
+            }
+            catch (cause) {
+                if (cause instanceof SafeOutputTreeCreationFailure)
+                    tree = cause.tree;
                 throw recoveryInputFailure("output_directory", `Cannot create new recovery directory ${input.output_directory}: ${recoveryFailureMessage(cause)}`, cause);
-            });
+            }
             execution = await prepareWakaruExecution({
                 root,
                 tree,
@@ -58,30 +81,80 @@ export class WakaruProvider {
             await tree.commit();
         }
         catch (cause) {
-            failure = cause;
+            failed = { cause };
         }
-        if (failure !== undefined) {
+        if (failed !== undefined) {
+            const failure = failed.cause;
             const residuals = [];
+            const cleanupFailures = [];
+            const cleanupOwner = failure instanceof WakaruCleanupFailure
+                ? failure.cleanupOwner
+                : undefined;
+            let failedTree;
             try {
                 await tree?.rollback();
             }
-            catch {
-                if (tree !== undefined)
+            catch (cause) {
+                if (tree !== undefined) {
+                    failedTree = tree;
                     residuals.push(tree.outputRoot);
+                    cleanupFailures.push({
+                        resource: tree.outputRoot,
+                        reason: recoveryFailureMessage(cause),
+                    });
+                }
             }
-            if (root !== undefined &&
-                !(failure instanceof AnalysisError && failure.cleanupIncomplete)) {
+            if (cleanupOwner !== undefined)
+                residuals.push(cleanupOwner.launch.ownership?.runId ?? "wakaru-worker");
+            if (root !== undefined && cleanupOwner === undefined) {
+                const failedRoot = root;
                 try {
-                    await rm(root, { recursive: true, force: true });
+                    await rm(failedRoot, { recursive: true, force: true });
+                    root = undefined;
                 }
-                catch {
-                    residuals.push(root);
+                catch (cause) {
+                    residuals.push(failedRoot);
+                    cleanupFailures.push({
+                        resource: failedRoot,
+                        reason: recoveryFailureMessage(cause),
+                    });
                 }
             }
+            if (cleanupOwner !== undefined ||
+                failedTree !== undefined ||
+                root !== undefined) {
+                this.#pendingCleanup = {
+                    root,
+                    process: cleanupOwner,
+                    tree: failedTree,
+                };
+                if (root !== undefined)
+                    residuals.push(root);
+                root = undefined;
+            }
             if (residuals.length > 0)
                 return err(new ProviderCleanupError("wakaru", residuals, {
-                    previous_error: recoveryFailureMessage(failure),
+                    ...(failure instanceof WakaruCleanupFailure
+                        ? failure.diagnostics
+                        : {}),
+                    previous_error: failure instanceof WakaruCleanupFailure
+                        ? (failure.diagnostics?.previous_error ?? null)
+                        : recoveryFailureMessage(failure),
+                    cleanup_failures: cleanupFailures,
+                }, {
+                    operation: OPERATION,
+                    cause: failure,
+                    ...(tree?.published && execution !== undefined
+                        ? {
+                            partialObservation: {
+                                kind: "javascript-recovery",
+                                result: javascriptRecoveryResultSchema.parse(execution.result),
+                            },
+                        }
+                        : {}),
                 }));
+            if (tree?.published === true && execution !== undefined)
+                return ok(execution);
             return err(failure instanceof AnalysisError
                 ? failure
                 : new ProviderAdapterError("wakaru", OPERATION, {
@@ -93,4 +166,54 @@ export class WakaruProvider {
             ? err(new AnalysisOutputError(OPERATION, "Recovery returned no execution"))
             : ok(execution);
     }
+    async close() {
+        this.#closing = true;
+        this.#closePromise ??= this.#tail
+            .then(async () => {
+            const failure = await this.#retire();
+            if (failure !== undefined)
+                throw failure;
+        })
+            .catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
+        return this.#closePromise;
+    }
+    async #retire() {
+        const pending = this.#pendingCleanup;
+        if (pending === undefined)
+            return undefined;
+        if (pending.process !== undefined) {
+            const stopped = await pending.process.stop();
+            if (stopped.status === "incomplete")
+                return new ProviderCleanupError("wakaru", [
+                    pending.process.launch.ownership?.runId ?? "wakaru-worker",
+                    ...(pending.root === undefined ? [] : [pending.root]),
+                ], { reason: stopped.reason }, { operation: OPERATION });
+            pending.process = undefined;
+        }
+        if (pending.tree !== undefined) {
+            const tree = pending.tree;
+            try {
+                await tree.rollback();
+                pending.tree = undefined;
+            }
+            catch (cause) {
+                return new ProviderCleanupError("wakaru", [tree.outputRoot], { reason: recoveryFailureMessage(cause) }, { operation: OPERATION, cause });
+            }
+        }
+        if (pending.root !== undefined) {
+            const root = pending.root;
+            try {
+                await rm(root, { recursive: true, force: true });
+                pending.root = undefined;
+            }
+            catch (cause) {
+                return new ProviderCleanupError("wakaru", [root], { reason: recoveryFailureMessage(cause) }, { operation: OPERATION, cause });
+            }
+        }
+        this.#pendingCleanup = undefined;
+        return undefined;
+    }
 }

package/dist/javascript/recovery/WakaruPublication.js

@@ -10,7 +10,7 @@ export const publishWakaruArtifacts = async (context) => {
     const { tree, source, parsed, staging, signal } = context;
     const write = async (path, bytes) => {
         const sha256 = recoveryDigest(bytes);
-        const file = await tree.write(path, Readable.from([bytes]), sha256, signal);
+        const file = await tree.write(path, Readable.from([bytes]), { sha256, bytes: bytes.byteLength }, signal);
         return {
             path: join(tree.outputRoot, file.relativePath),
             sha256: file.sha256,
@@ -31,7 +31,7 @@ export const publishWakaruArtifacts = async (context) => {
         source: { ...source, published_copy: publishedCopy },
         engine: {
             id: "wakaru",
-            version: WAKARU_RELEASE.version,
+            version: context.admitted.version,
             executable: {
                 path: context.engine.command,
                 sha256: context.engine.sha256,
@@ -52,7 +52,12 @@ export const publishWakaruArtifacts = async (context) => {
         total: parsed.report.total,
         failed: parsed.report.failed,
         modules,
-        warnings: parsed.report.warnings,
+        warnings: parsed.report.warnings.map(({ filename, kind, is_error, message }) => ({
+            filename,
+            kind,
+            is_error,
+            message,
+        })),
         report,
         provenance,
         analysis_input: modules.length === 0
@@ -62,7 +67,12 @@ export const publishWakaruArtifacts = async (context) => {
                 format: "directory",
             },
         runtime_equivalence: "unknown",
-        limitations: [...RECOVERY_LIMITATIONS],
+        limitations: [
+            ...RECOVERY_LIMITATIONS,
+            ...(context.admitted.status === "compatible"
+                ? [context.admitted.limitation]
+                : []),
+        ],
     };
     const manifest = await write("manifest.json", Buffer.from(`${JSON.stringify(details, null, 2)}\n`));
     return javascriptRecoveryResultSchema.parse({ ...details, manifest });

package/dist/javascript/recovery/WakaruRelease.js

@@ -1,10 +1,17 @@
 /** Unchanged upstream source pin; executed bytes are identified separately. */
 export const WAKARU_RELEASE = {
-    version: "1.13.0",
-    revision: "6070266d24b32951fa2fe1d2dad5b4313bd5c81b",
+    version: "1.14.0",
+    revision: "8219bf5016a063d7fb215101a8c45d5959ec733f",
     repository: "https://github.com/pionxzh/wakaru",
 };
-/** Exact provider identity shared by executions and the generated catalog. */
+/**
+ * Releases the report parser accepts. Wakaru changes `--version`, `--json`
+ * and `provenance.json` only by addition within a major version
+ * (https://github.com/pionxzh/wakaru/blob/v1.14.0/docs/cli.md#machine-readable-output-compatibility);
+ * 1.13.0 is the first release this adapter verified.
+ */
+export const WAKARU_ACCEPTED_RANGE = "^1.13.0";
+/** Catalog identity for the verified Wakaru release. Evidence replaces version with the observed banner. */
 export const WAKARU_PROVIDER_IDENTITY = {
     id: "wakaru",
     name: "Wakaru",

package/dist/javascript/recovery/WakaruReport.js

@@ -4,19 +4,19 @@ import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
 import { readRecoveryFile, recoveryFailureMessage } from "./RecoveryFiles.js";
 import { RECOVERY_LIMITS } from "./WakaruRelease.js";
-const warningSchema = z.strictObject({
+const warningSchema = z.looseObject({
     filename: z.string(),
     kind: z.string(),
     is_error: z.boolean(),
     message: z.string(),
 });
-const reportSchema = z.strictObject({
+const reportSchema = z.looseObject({
     detected_formats: z.array(z.string()),
     safety: z.string(),
-    modules: z.array(z.strictObject({
+    modules: z.array(z.looseObject({
         filename: z.string().min(1),
         kind: z.literal("javascript"),
-        status: z.literal("decompiled"),
+        status: z.string().min(1),
     })),
     warnings: z.array(warningSchema),
     total: z.number().int().nonnegative(),
@@ -27,10 +27,10 @@ const rangeSchema = z.tuple([
     z.number().int().nonnegative(),
     z.number().int().nonnegative(),
 ]);
-const provenanceSchema = z.strictObject({
+const provenanceSchema = z.looseObject({
     format: z.string(),
     strategy: z.string(),
-    modules: z.record(z.string(), z.strictObject({
+    modules: z.record(z.string(), z.looseObject({
         input: z.string(),
         ranges: z.array(rangeSchema),
         extraction: z.string(),
@@ -38,7 +38,12 @@ const provenanceSchema = z.strictObject({
     })),
 });
 const OPERATION = "recover_javascript_sources";
-/** Parse exact pinned producer JSON before projecting provider-neutral artifacts. */
+/**
+ * Parse producer JSON before projecting provider-neutral artifacts. Wakaru adds
+ * fields and category values within a major version, so unknown keys are kept
+ * and `status` stays the reported string; identity, path, range and file-set
+ * checks below remain exact.
+ */
 export const parseWakaruReports = async (context) => {
     const { execution, provenancePath } = context;
     try {

package/dist/javascript/recovery/WakaruVersion.js

@@ -0,0 +1,24 @@
+import { satisfies, valid } from "semver";
+import { WAKARU_ACCEPTED_RANGE, WAKARU_RELEASE } from "./WakaruRelease.js";
+/** Caller-facing accepted releases, naming the verified build. */
+export const wakaruReleaseLine = () => `Wakaru ${WAKARU_ACCEPTED_RANGE} (verified with ${WAKARU_RELEASE.version})`;
+/** Classify a `wakaru <version>` banner against the accepted release range. */
+export const admitWakaruVersion = (banner) => {
+    const token = banner.startsWith("wakaru ")
+        ? banner.slice("wakaru ".length)
+        : undefined;
+    if (token === undefined ||
+        valid(token) !== token ||
+        !satisfies(token, WAKARU_ACCEPTED_RANGE))
+        return {
+            status: "unsupported",
+            message: `Unsupported Wakaru version ${banner.length === 0 ? "missing" : banner}; accepted releases are ${wakaruReleaseLine()}`,
+        };
+    if (token === WAKARU_RELEASE.version)
+        return { status: "verified", version: token };
+    return {
+        status: "compatible",
+        version: token,
+        limitation: `This session uses Wakaru ${token}. The report parser is verified against ${WAKARU_RELEASE.version}; other ${WAKARU_ACCEPTED_RANGE} releases are accepted and the observed version is reported.`,
+    };
+};

package/dist/javascript/sourceMaps/SourceMapCommand.js

@@ -15,6 +15,13 @@ import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../../pro
 import { prepareProcessOwnershipInspection } from "../../process/ProcessOwnershipObservation.js";
 const OPERATION = "trace_web_source_location";
 const PROVIDER = "source-map-decoder";
+export class SourceMapCleanupFailure extends ProviderCleanupError {
+    cleanupOwner;
+    constructor(cleanupOwner, resources, diagnostics) {
+        super(PROVIDER, resources, diagnostics, { operation: OPERATION });
+        this.cleanupOwner = cleanupOwner;
+    }
+}
 /** Run a trusted codec command and release its process/root before returning output. */
 export const runSourceMapCommand = async (request, path, options, dependencies) => {
     try {
@@ -164,14 +171,20 @@ class OwnedCodec {
     }
     async close(previousError) {
         const failures = [];
+        let processReleased = this.#supervisor === undefined;
         if (this.#supervisor !== undefined) {
             const stopped = await this.#supervisor.stop();
             if (stopped.status === "incomplete")
                 failures.push(stopped.reason);
+            else {
+                processReleased = true;
+                this.#supervisor = undefined;
+            }
         }
-        if (this.#runtime !== undefined) {
+        if (processReleased && this.#runtime !== undefined) {
             try {
                 await this.#runtime.close();
+                this.#runtime = undefined;
             }
             catch (cause) {
                 failures.push(message(cause));
@@ -179,7 +192,7 @@ class OwnedCodec {
         }
         return failures.length === 0
             ? undefined
-            : new ProviderCleanupError(PROVIDER, [
+            : new SourceMapCleanupFailure(this, [
                 this.#runId,
                 ...(this.#runtime === undefined ? [] : [this.#runtime.path]),
             ], {
@@ -187,7 +200,7 @@ class OwnedCodec {
                 cleanup_failures: failures,
                 previous_error: previousError,
                 codec_pid: this.#supervisor?.launch.process.pid ?? null,
-            }, { operation: OPERATION });
+            });
     }
 }
 const message = (cause) => cause instanceof Error ? cause.message : String(cause);

package/dist/javascript/sourceMaps/SourceMapDecoder.js

@@ -3,16 +3,34 @@ import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
 import { err, ok } from "../../domain/result.js";
 import { WEB_SOURCE_MAP_LIMITS, } from "../../domain/webSourceLocation.js";
 import { sourceMapCodecInputSchema, sourceMapCodecReplySchema, } from "./SourceMapCodecProtocol.js";
-import { runSourceMapCommand, } from "./SourceMapCommand.js";
+import { SourceMapCleanupFailure, runSourceMapCommand, } from "./SourceMapCommand.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { jsonParts } from "../../domain/jsonSerialization.js";
 const OPERATION = "trace_web_source_location";
 /** Integrate the pinned upstream codec through an independently bounded owned process. */
 export class SourceMapDecoder {
     dependencies;
+    #tail = Promise.resolve();
+    #closing = false;
+    #closePromise;
+    #pendingCleanup;
     constructor(dependencies = {}) {
         this.dependencies = dependencies;
     }
     /** Return complete point evidence after process and private-root cleanup. */
-    async trace(input, options) {
+    trace(input, options) {
+        if (this.#closing)
+            return Promise.resolve(err(new ProviderCleanupError("source-map-decoder", [], { reason: "Provider is closing" }, { operation: OPERATION })));
+        const operation = this.#tail.then(() => this.#closing
+            ? err(new ProviderCleanupError("source-map-decoder", [], { reason: "Provider is closing" }, { operation: OPERATION }))
+            : this.#trace(input, options));
+        this.#tail = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    async #trace(input, options) {
+        const cleanupFailure = await this.#retryCleanup();
+        if (cleanupFailure !== undefined)
+            return err(cleanupFailure);
         if (options?.signal?.aborted)
             return err(new AnalysisCancelledError(OPERATION));
         const request = sourceMapCodecInputSchema.safeParse({
@@ -22,13 +40,27 @@ export class SourceMapDecoder {
         });
         if (!request.success)
             return err(new AnalysisInputError(OPERATION, { cause: request.error }));
-        const serialized = JSON.stringify(request.data);
-        if (Buffer.byteLength(input.text) > WEB_SOURCE_MAP_LIMITS.mapBytes ||
-            Buffer.byteLength(serialized) > WEB_SOURCE_MAP_LIMITS.outputBytes)
-            return err(new ArtifactOperationError(OPERATION, "limit", undefined, `${input.path}: Source-map input exceeds the 4 MiB map or 32 MiB encoded request budget.`));
+        const capacityFailure = () => new ArtifactOperationError(OPERATION, "limit", undefined, `${input.path}: Source-map input exceeds the 4 MiB map or 32 MiB encoded request budget.`);
+        if (Buffer.byteLength(input.text) > WEB_SOURCE_MAP_LIMITS.mapBytes)
+            return err(capacityFailure());
+        const encoded = [];
+        let encodedBytes = 0;
+        for (const part of jsonParts(request.data)) {
+            const bytes = Buffer.byteLength(part);
+            if (bytes > WEB_SOURCE_MAP_LIMITS.outputBytes - encodedBytes)
+                return err(capacityFailure());
+            encoded.push(part);
+            encodedBytes += bytes;
+        }
+        if (options?.signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION));
+        const serialized = encoded.join("");
         const response = await runSourceMapCommand(serialized, input.path, options, this.dependencies);
-        if (!response.ok)
+        if (!response.ok) {
+            if (response.error instanceof SourceMapCleanupFailure)
+                this.#pendingCleanup = response.error.cleanupOwner;
             return response;
+        }
         let value;
         try {
             value = JSON.parse(response.value);
@@ -47,6 +79,30 @@ export class SourceMapDecoder {
             return err(new AnalysisOutputError(OPERATION, "Codec reported a V8 heap limit exceeding its independent process budget."));
         return ok(reply.data.report);
     }
+    async close() {
+        this.#closing = true;
+        this.#closePromise ??= this.#tail
+            .then(async () => {
+            const failure = await this.#retryCleanup();
+            if (failure !== undefined)
+                throw failure;
+        })
+            .catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
+        return this.#closePromise;
+    }
+    async #retryCleanup() {
+        const pending = this.#pendingCleanup;
+        if (pending === undefined)
+            return undefined;
+        const failure = await pending.close(null);
+        if (failure !== undefined)
+            return failure;
+        this.#pendingCleanup = undefined;
+        return undefined;
+    }
 }
 const codecFailure = (path, reason, detail) => err(reason === "limit"
     ? new ArtifactOperationError(OPERATION, "limit", undefined, `${path}: ${detail}`)

package/dist/javascript/sourceMaps/SourceMapFormat.js

@@ -168,12 +168,23 @@ const inspectLeaf = (node, budget, options) => {
         throw new SourceMapFormatFailure("limit", "Source-map layout exceeds the 262144 segment/generated-row decoder budget.");
     return leaf;
 };
+/**
+ * Return the JSON view of source-map text without changing the source evidence.
+ * ECMA-426 §11.2.1 permits HTTP(S) responses to start with `)]}'`; the line
+ * through the first HTTP newline is transport framing, not map content. Local
+ * point tracing shares this parser and has historically accepted the same
+ * framing. https://tc39.es/ecma426/#sec-fetchsourcemap
+ */
+export const sourceMapJsonText = (text) => {
+    const withoutBom = text.replace(/^\uFEFF/u, "");
+    if (!withoutBom.startsWith(")]}'"))
+        return withoutBom;
+    const newline = withoutBom.search(/[\r\n]/u);
+    return newline === -1 ? "" : withoutBom.slice(newline);
+};
 /** Validate structure before allocation, retaining raw declarations and section boundaries. */
 export const inspectSourceMap = (text) => {
-    const withoutBom = text.replace(/^\uFEFF/u, "");
-    const jsonText = withoutBom.startsWith(")]}'")
-        ? withoutBom.slice(withoutBom.indexOf("\n") + 1)
-        : withoutBom;
+    const jsonText = sourceMapJsonText(text);
     const value = JSON.parse(jsonText);
     const inspected = inspectSourceMapValue(value);
     const normalized = inspected.format === "regular"