reverseport 0.0.0-stage → 1.2.0

package/dist/javascript/recovery/RecoveryFiles.js

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, opendir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { TextDecoder } from "node:util";
+import { normalizeArtifactPath } from "../../artifacts/ArtifactPaths.js";
+import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "../../domain/analysisErrorCore.js";
+import { RECOVERY_LIMITS } from "./WakaruRelease.js";
+const OPERATION = "recover_javascript_sources";
+/** Fingerprint exact selected or derived bytes. */
+export const recoveryDigest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** Read a stable regular file without retaining bytes during engine fingerprinting. */
+const scanRecoveryFile = async (path, maximum, consume, signal) => {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const hash = createHash("sha256");
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.size > maximum)
+            throw new AnalysisOutputError(OPERATION, `Expected a regular file no larger than ${String(maximum)} bytes: ${path}`);
+        let bytes = 0;
+        for await (const raw of handle.createReadStream({ autoClose: false })) {
+            checkRecoveryCancellation(signal);
+            const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+            bytes += chunk.length;
+            if (bytes > maximum)
+                throw new AnalysisOutputError(OPERATION, `File exceeds ${String(maximum)} bytes: ${path}`);
+            hash.update(chunk);
+            consume(chunk);
+        }
+        const after = await handle.stat();
+        const current = await lstat(path);
+        if (before.dev !== current.dev ||
+            before.ino !== current.ino ||
+            before.size !== bytes ||
+            before.mtimeMs !== after.mtimeMs ||
+            before.ctimeMs !== after.ctimeMs ||
+            before.size !== after.size)
+            throw new AnalysisOutputError(OPERATION, `File identity changed while reading: ${path}`);
+        return { sha256: hash.digest("hex"), bytes };
+    }
+    finally {
+        await handle.close();
+    }
+};
+/** Fingerprint a regular file incrementally with bounded memory. */
+export const fingerprintRecoveryFile = async (path, maximum, signal) => scanRecoveryFile(path, maximum, () => { }, signal);
+/** Read only a regular file through one handle with a bounded, stable identity. */
+export const readRecoveryFile = async (path, maximum, signal) => {
+    const chunks = [];
+    const result = await scanRecoveryFile(path, maximum, (chunk) => chunks.push(chunk), signal);
+    return Buffer.concat(chunks, result.bytes);
+};
+/** Snapshot one script within the remaining operation-wide input budget. */
+const snapshotRecoveryInput = async (path, snapshotPath, relativePath, maximum, signal) => {
+    if (!isAbsolute(path))
+        throw recoveryInputFailure("path", "Select an absolute JavaScript file path");
+    let bytes;
+    try {
+        bytes = await readRecoveryFile(path, maximum, signal);
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch (cause) {
+        if (cause instanceof AnalysisCancelledError)
+            throw cause;
+        throw recoveryInputFailure("path", `Cannot snapshot UTF-8 JavaScript input ${path}: ${recoveryFailureMessage(cause)}`, cause);
+    }
+    await mkdir(dirname(snapshotPath), { recursive: true, mode: 0o700 });
+    await writeFile(snapshotPath, bytes, { flag: "wx", mode: 0o600 });
+    return {
+        path,
+        snapshot_path: snapshotPath,
+        relative_path: relativePath,
+        sha256: recoveryDigest(bytes),
+        bytes: bytes.length,
+    };
+};
+/** Preserve each selected file and its relative input layout without concatenation. */
+export const snapshotRecoveryInputs = async (paths, directory, signal) => {
+    let commonDirectory = dirname(resolve(paths[0]));
+    for (const path of paths) {
+        while (true) {
+            const fromCommon = relative(commonDirectory, resolve(path));
+            if (fromCommon !== ".." &&
+                !fromCommon.startsWith(`..${sep}`) &&
+                !isAbsolute(fromCommon))
+                break;
+            const parent = dirname(commonDirectory);
+            if (parent === commonDirectory)
+                throw recoveryInputFailure("additional_paths", "Selected files must share a filesystem root");
+            commonDirectory = parent;
+        }
+    }
+    const snapshots = [];
+    let remaining = RECOVERY_LIMITS.inputBytes;
+    for (const path of paths) {
+        const relativePath = paths.length === 1
+            ? "bundle.js"
+            : relative(commonDirectory, resolve(path)).split(sep).join("/");
+        try {
+            if (normalizeArtifactPath(relativePath) !== relativePath)
+                throw new TypeError("Input names must already use NFC Unicode spelling");
+        }
+        catch (cause) {
+            throw recoveryInputFailure("path", `Cannot preserve selected input path in published artifacts: ${path}: ${recoveryFailureMessage(cause)}`, cause);
+        }
+        const snapshot = await snapshotRecoveryInput(path, join(directory, relativePath), relativePath, remaining, signal);
+        snapshots.push(snapshot);
+        remaining -= snapshot.bytes;
+    }
+    // The selected-input tuple guarantees a primary snapshot.
+    const [primary, ...additional] = snapshots;
+    if (primary === undefined)
+        throw recoveryInputFailure("path", "Select a JavaScript input");
+    return [primary, ...additional];
+};
+/** Inventory staging without following symlinks or publishing special files. */
+export const inventoryRecoveryFiles = async (root, signal) => {
+    const files = [];
+    let bytes = 0;
+    let entries = 0;
+    const visit = async (directory, prefix) => {
+        const metadata = await lstat(directory);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink())
+            throw new AnalysisOutputError(OPERATION, `Unsafe staging directory: ${directory}`);
+        const handle = await opendir(directory);
+        const children = [];
+        try {
+            for await (const entry of handle) {
+                checkRecoveryCancellation(signal);
+                entries++;
+                if (entries > RECOVERY_LIMITS.outputEntries)
+                    throw new AnalysisOutputError(OPERATION, "Recovery staging exceeds the 10000-entry resource limit");
+                children.push(entry.name);
+            }
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+        for (const name of children) {
+            checkRecoveryCancellation(signal);
+            const relativePath = prefix === "" ? name : `${prefix}/${name}`;
+            const path = join(directory, name);
+            const info = await lstat(path);
+            if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile()))
+                throw new AnalysisOutputError(OPERATION, `Recovery produced a symlink or special file: ${relativePath}`);
+            if (info.isDirectory())
+                await visit(path, relativePath);
+            else {
+                bytes += info.size;
+                if (bytes > RECOVERY_LIMITS.outputBytes)
+                    throw new AnalysisOutputError(OPERATION, "Recovery staging exceeds the 128 MiB resource limit");
+                files.push({ relativePath, path, bytes: info.size });
+            }
+        }
+    };
+    await visit(root, "");
+    return files;
+};
+/** Preserve actionable caller constraints in the ordinary error algebra. */
+export const recoveryInputFailure = (field, message, cause) => new AnalysisInputError(OPERATION, { cause }, [
+    { path: [field], reason: "invalid_value", message },
+]);
+/** Convert one caught boundary cause into diagnostic text without masking its type. */
+export const recoveryFailureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Cancellation remains distinct from malformed source or provider output. */
+export const checkRecoveryCancellation = (signal) => {
+    if (signal?.aborted === true)
+        throw new AnalysisCancelledError(OPERATION);
+};
+/** Keep both tool invocations within one operation's execution budget. */
+export const checkRecoveryDeadline = (deadline, signal) => {
+    checkRecoveryCancellation(signal);
+    if (Date.now() >= deadline)
+        throw new AnalysisTimeoutError(OPERATION, RECOVERY_LIMITS.timeoutMs);
+};

package/dist/javascript/recovery/WakaruCommand.js

@@ -0,0 +1,137 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+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";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { cleanupOwnedProcessGroup } from "../../process/ProcessOwnership.js";
+import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../../process/ProviderProcess.js";
+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 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;
+    if (process.platform !== "linux" ||
+        process.arch !== "x64" ||
+        configured === undefined ||
+        !isAbsolute(configured))
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, WAKARU_REQUIREMENT, { userMessage: WAKARU_REQUIREMENT });
+    try {
+        const command = await realpath(configured);
+        await access(command, constants.R_OK | constants.X_OK);
+        const fingerprint = await fingerprintRecoveryFile(command, RECOVERY_LIMITS.outputBytes);
+        const limiter = environment.REA_JAVASCRIPT_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
+        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) {
+        const reason = `Configured Wakaru or util-linux prlimit is unavailable: ${recoveryFailureMessage(cause)}`;
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, reason, {
+            cause,
+            userMessage: reason,
+        });
+    }
+};
+/** Run one bounded command and verify cleanup before consuming its output. */
+export const runWakaruCommand = async (context) => {
+    checkRecoveryDeadline(context.deadline, context.signal);
+    const runId = `rea-wakaru-${randomUUID()}`;
+    const spawned = await (context.launcher ?? spawnOwnedProviderProcess)({
+        command: context.limiter,
+        arguments: [
+            `--as=${String(RECOVERY_LIMITS.addressSpaceBytes)}`,
+            `--fsize=${String(RECOVERY_LIMITS.outputBytes)}`,
+            "--core=0",
+            "--cpu=120",
+            "--",
+            context.command,
+            ...context.arguments,
+        ],
+        expectedCommand: null,
+        runId,
+        cwd: context.cwd,
+        hostEnvironment: context.environment,
+        ...(context.signal === undefined ? {} : { signal: context.signal }),
+        env: { TMPDIR: context.cwd, RAYON_NUM_THREADS: "1", NO_COLOR: "1" },
+    }).catch((cause) => {
+        if (context.signal?.aborted === true)
+            throw new AnalysisCancelledError(OPERATION);
+        throw new ProviderAdapterError("wakaru", OPERATION, {
+            cause,
+            diagnostics: {
+                reason: "Failed to launch configured Wakaru through util-linux prlimit",
+                command: context.command,
+                detail: recoveryFailureMessage(cause),
+            },
+        });
+    });
+    let oversized = false;
+    const supervisor = new ProviderProcessSupervisor({
+        ...spawned,
+        ownsProcessLifetime: true,
+        cleanup: spawned.cleanup ?? (() => cleanupOwnedProcessGroup(spawned.ownership)),
+    }, {
+        onDiagnostic: (event) => {
+            if (event.type === "output" &&
+                event.totalBytes > RECOVERY_LIMITS.reportBytes)
+                oversized = true;
+        },
+    });
+    let failure;
+    try {
+        while (!(await supervisor.waitForOutputClose(100))) {
+            checkRecoveryDeadline(context.deadline, context.signal);
+            if (oversized)
+                throw new AnalysisOutputError(OPERATION, "Wakaru diagnostic stream exceeds 8 MiB");
+            if (context.staging !== undefined)
+                await inventoryRecoveryFiles(context.staging, context.signal);
+        }
+        checkRecoveryDeadline(context.deadline, context.signal);
+        if (oversized)
+            throw new AnalysisOutputError(OPERATION, "Wakaru diagnostic stream exceeds 8 MiB");
+    }
+    catch (cause) {
+        failure = cause;
+    }
+    const stopped = await supervisor.stop();
+    const snapshot = supervisor.snapshot();
+    if (stopped.status === "incomplete")
+        throw new WakaruCleanupFailure(supervisor, runId, context.cwd, stopped.reason, failure, snapshot);
+    if (failure !== undefined)
+        throw failure;
+    if (context.signal?.aborted === true)
+        throw new AnalysisCancelledError(OPERATION);
+    return {
+        exit_code: snapshot.exitCode ?? null,
+        signal: snapshot.signal ?? null,
+        stdout: snapshot.stdout.text,
+        stderr: snapshot.stderr.text,
+        command: context.command,
+        arguments: [...context.arguments],
+        resource_limiter: context.limiter,
+    };
+};

package/dist/javascript/recovery/WakaruExecution.js

@@ -0,0 +1,115 @@
+import { join } from "node:path";
+import { createAnalysisExecution, } from "../../application/AnalysisProvider.js";
+import { AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
+import { jsonValueSchema } from "../../domain/jsonValue.js";
+import { fingerprintRecoveryFile, inventoryRecoveryFiles, readRecoveryFile, } from "./RecoveryFiles.js";
+import { runWakaruCommand, } from "./WakaruCommand.js";
+import { parseWakaruReports } from "./WakaruReport.js";
+import { publishWakaruArtifacts } from "./WakaruPublication.js";
+import { RECOVERY_LIMITS, WAKARU_PROVIDER_IDENTITY } from "./WakaruRelease.js";
+import { admitWakaruVersion } from "./WakaruVersion.js";
+const OPERATION = "recover_javascript_sources";
+const MODES = {
+    structural: "strict",
+    heuristic: "auto",
+    inspection: "inspect",
+};
+/** Consume the pinned producer representation in a private workspace. */
+const executeWakaruRecovery = async (context) => {
+    const { root, input, sources, engine, environment, launcher, options } = context;
+    const staging = join(root, "modules");
+    const commandContext = {
+        ...engine,
+        cwd: root,
+        deadline: context.deadline,
+        environment: environment,
+        ...(options?.signal === undefined ? {} : { signal: options.signal }),
+        ...(launcher === undefined ? {} : { launcher: launcher }),
+    };
+    const version = await runWakaruCommand({
+        ...commandContext,
+        arguments: ["--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 = `${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({
+        ...commandContext,
+        staging,
+        arguments: [
+            ...sources.map((source) => source.snapshot_path),
+            `--unpack=${MODES[input.extraction_mode]}`,
+            `--level=${input.rewrite_level}`,
+            "--provenance",
+            "--emit-source-map",
+            "--json",
+            "-o",
+            staging,
+        ],
+    });
+    const files = await inventoryRecoveryFiles(staging, options?.signal);
+    const snapshots = new Map();
+    for (const source of sources)
+        snapshots.set(source.snapshot_path, await readRecoveryFile(source.snapshot_path, source.bytes, options?.signal));
+    const parsed = await parseWakaruReports({
+        execution: run,
+        provenancePath: join(staging, "provenance.json"),
+        snapshots,
+        files,
+    });
+    return { version, admitted, run, parsed };
+};
+/** Publish validated recovery and retain exact source and engine bindings. */
+export const prepareWakaruExecution = async (context) => {
+    const { root, tree, input, sources, engine, options } = context;
+    const [source] = sources;
+    const staging = join(root, "modules");
+    const { version, admitted, run, parsed } = await executeWakaruRecovery(context);
+    const result = await publishWakaruArtifacts({
+        tree,
+        staging,
+        input,
+        sources,
+        engine,
+        admitted,
+        parsed,
+        execution: run,
+        ...(options?.signal === undefined ? {} : { signal: options.signal }),
+    });
+    for (const selected of sources) {
+        const current = await fingerprintRecoveryFile(selected.path, RECOVERY_LIMITS.inputBytes, options?.signal);
+        if (current.sha256 !== selected.sha256 || current.bytes !== selected.bytes)
+            throw new AnalysisOutputError(OPERATION, `Original input changed during recovery: ${selected.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, version: admitted.version }, {
+        rawResult: jsonValueSchema.parse({
+            version,
+            execution: run,
+            report: parsed.report,
+            provenance: parsed.provenance,
+        }),
+        subject: {
+            path: source.path,
+            sha256: source.sha256,
+            format: "javascript",
+        },
+        locations: [
+            ...sources.map((selected) => ({
+                kind: "artifact-path",
+                path: selected.path,
+            })),
+            ...result.modules.map((module) => ({
+                kind: "artifact-path",
+                path: module.artifact.path,
+            })),
+        ],
+        limitations: result.limitations,
+    });
+};

package/dist/javascript/recovery/WakaruProvider.js

@@ -0,0 +1,218 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+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, snapshotRecoveryInputs, } from "./RecoveryFiles.js";
+import { resolveWakaruCommand, WakaruCleanupFailure, } from "./WakaruCommand.js";
+import { prepareWakaruExecution } from "./WakaruExecution.js";
+import { RECOVERY_LIMITS } from "./WakaruRelease.js";
+const OPERATION = "recover_javascript_sources";
+/** 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 selected scripts using validated reports and verified output bytes. */
+    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 failed;
+        let execution;
+        const deadline = Date.now() + RECOVERY_LIMITS.timeoutMs;
+        try {
+            checkRecoveryCancellation(options?.signal);
+            const engine = await resolveWakaruCommand(this.environment);
+            root = await mkdtemp(join(tmpdir(), "rea-wakaru-"));
+            const inputs = join(root, "inputs");
+            const staging = join(root, "modules");
+            await mkdir(inputs, { mode: 0o700 });
+            await mkdir(staging, { mode: 0o700 });
+            const sources = await snapshotRecoveryInputs([input.path, ...(input.additional_paths ?? [])], inputs, options?.signal);
+            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,
+                input,
+                sources,
+                engine,
+                environment: this.environment,
+                launcher: this.launcher,
+                options,
+                deadline,
+            });
+            checkRecoveryDeadline(deadline, options?.signal);
+            await rm(root, { recursive: true, force: true });
+            root = undefined;
+            checkRecoveryDeadline(deadline, options?.signal);
+            await tree.commit();
+        }
+        catch (cause) {
+            failed = { cause };
+        }
+        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 (cause) {
+                if (tree !== undefined) {
+                    failedTree = tree;
+                    residuals.push(tree.outputRoot);
+                    cleanupFailures.push({
+                        resource: tree.outputRoot,
+                        reason: recoveryFailureMessage(cause),
+                    });
+                }
+            }
+            if (cleanupOwner !== undefined)
+                residuals.push(cleanupOwner.launch.ownership?.runId ?? "wakaru-worker");
+            if (root !== undefined && cleanupOwner === undefined) {
+                const failedRoot = root;
+                try {
+                    await rm(failedRoot, { recursive: true, force: true });
+                    root = undefined;
+                }
+                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, {
+                    ...(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, {
+                    cause: failure,
+                    diagnostics: { reason: recoveryFailureMessage(failure) },
+                }));
+        }
+        return execution === undefined
+            ? 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;
+    }
+}