rea-agents 4.0.1 → 5.0.0

package/dist/{browser → inspector}/V8InspectorEndpoint.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
-import { BrowserObservationError, } from "../domain/errors.js";
-import { parseCdpEndpointValue, readCdpJson } from "./CdpEndpoint.js";
+import { BrowserObservationError } from "../domain/browserObservationError.js";
+import {} from "../domain/browserObservationErrors.js";
+import { parseCdpEndpointValue, readCdpJson } from "../browser/CdpEndpoint.js";
 const versionSchema = z
     .object({
     Browser: z.string().min(1),

package/dist/{browser → inspector}/V8InspectorProvider.js

@@ -1,17 +1,17 @@
-import { javascriptRuntimeObservationSchema, javascriptRuntimeTargetListSchema, } from "../domain/javascriptRuntimeObservation.js";
-import { AnalysisError, BrowserObservationError, ProviderAdapterError, } from "../domain/errors.js";
+import { javascriptRuntimeObservationSchema, javascriptRuntimeTargetListSchema, } from "../domain/javascript/javascriptRuntimeObservation.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { BrowserObservationError } from "../domain/browserObservationError.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import {} from "../domain/browserObservationErrors.js";
 import { err, ok } from "../domain/result.js";
-import { numberValue, recordValue, stringValue, delayWithCancellation, } from "./CdpCaptureValues.js";
-import { CdpConnection } from "./CdpConnection.js";
-import { authorizeRuntimeTargetLocation } from "./JavaScriptRuntimeScope.js";
+import { numberValue, recordValue, cdpStringValue, delayWithCancellation, } from "../browser/CdpCaptureValues.js";
+import { CdpConnection } from "../browser/CdpConnection.js";
+import { authorizeRuntimeTargetLocation, inspectorExclusionKey, } from "./JavaScriptRuntimeScope.js";
 import { createInspectorExclusionCounts, describeInspectorTargetLimitations, finalizeInspectorCapture, } from "./V8InspectorCaptureProjection.js";
 import { discoverV8Inspector, } from "./V8InspectorEndpoint.js";
 /** Public identity committed by passive V8 Inspector observations. */
-export const V8_INSPECTOR_PROVIDER_IDENTITY = Object.freeze({
-    id: "rea-v8-inspector",
-    name: "REA passive Node/Electron V8 Inspector provider",
-    version: "1",
-});
+export { V8_INSPECTOR_PROVIDER_IDENTITY } from "./providerIdentity.js";
+import { V8_INSPECTOR_PROVIDER_IDENTITY } from "./providerIdentity.js";
 /** Attach-only provider; sends only Runtime.enable and Debugger.enable. */
 export class V8InspectorProvider {
     identity() {
@@ -28,7 +28,7 @@ export class V8InspectorProvider {
                     product: discovery.runtime.product,
                 });
                 if (!decision.allowed) {
-                    excluded[decision.reason] += 1;
+                    excluded[inspectorExclusionKey(decision.reason)] += 1;
                     continue;
                 }
                 if (decision.location.kind === "builtin") {
@@ -104,6 +104,8 @@ export class V8InspectorProvider {
 }
 export const closeInspectorConnection = async (connection, signal) => {
     const closing = connection.close();
+    // best-effort cleanup: the race below observes the close; this only prevents
+    // unhandled rejection when the caller abandons the close via cancellation.
     void closing.catch(() => undefined);
     // CdpConnection.close has its own one second transport bound. Do not make a
     // cancelled caller wait for that fallback.
@@ -191,7 +193,7 @@ const ingestEvent = (event, input, state) => {
 const ingestScript = (event, input, state) => {
     state.scriptsObserved += 1;
     const value = recordValue(event.params);
-    const rawUrl = stringValue(value?.url);
+    const rawUrl = cdpStringValue(value?.url);
     if (rawUrl === undefined || rawUrl === "") {
         state.invalidScripts += 1;
         retainEvent(state, 0);
@@ -200,7 +202,7 @@ const ingestScript = (event, input, state) => {
     const draft = {
         rawUrl,
         executionContextKey: contextKey(value?.executionContextId),
-        cdpHash: stringValue(value?.hash) ?? null,
+        cdpHash: cdpStringValue(value?.hash) ?? null,
         length: nonnegativeInteger(value?.length),
         isModule: value?.isModule === true,
     };
@@ -227,7 +229,7 @@ const ingestContext = (event, input, state) => {
         return;
     }
     const origin = event.method === "Runtime.executionContextCreated"
-        ? (stringValue(runtimeContext?.origin) ?? null)
+        ? (cdpStringValue(runtimeContext?.origin) ?? null)
         : null;
     const draft = {
         contextKey: key,

package/dist/inspector/providerIdentity.js

@@ -0,0 +1,6 @@
+/** Identity available without loading the V8InspectorProvider implementation. */
+export const V8_INSPECTOR_PROVIDER_IDENTITY = Object.freeze({
+    id: "rea-v8-inspector",
+    name: "REA passive Node/Electron V8 Inspector provider",
+    version: "1",
+});

package/dist/javascript/recovery/RecoveryFiles.js

@@ -0,0 +1,122 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readdir, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { TextDecoder } from "node:util";
+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 caller-selected UTF-8 script before invoking the engine. */
+export const snapshotRecoveryInput = async (path, snapshotPath, signal) => {
+    if (!isAbsolute(path))
+        throw recoveryInputFailure("path", "Select an absolute JavaScript file path");
+    let bytes;
+    try {
+        bytes = await readRecoveryFile(path, RECOVERY_LIMITS.inputBytes, 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 writeFile(snapshotPath, bytes, { flag: "wx", mode: 0o600 });
+    return {
+        path,
+        snapshot_path: snapshotPath,
+        sha256: recoveryDigest(bytes),
+        bytes: bytes.length,
+    };
+};
+/** 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}`);
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            checkRecoveryCancellation(signal);
+            entries++;
+            const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+            const path = join(directory, entry.name);
+            const info = await lstat(path);
+            if (entries > RECOVERY_LIMITS.outputEntries)
+                throw new AnalysisOutputError(OPERATION, "Recovery staging exceeds the 10000-entry resource limit");
+            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,116 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, realpath } 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";
+/** 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, "Provide an absolute REA_WAKARU_COMMAND pointing to Wakaru 1.13.0 on Linux x64; no tool is installed by REA");
+    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);
+        return { command, limiter, ...fingerprint };
+    }
+    catch (cause) {
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, `Configured Wakaru or util-linux prlimit is unavailable: ${recoveryFailureMessage(cause)}`, { cause });
+    }
+};
+/** 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,
+        env: { TMPDIR: context.cwd, RAYON_NUM_THREADS: "1", NO_COLOR: "1" },
+    }).catch((cause) => {
+        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();
+    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,
+        });
+    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,100 @@
+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, recoveryDigest, } from "./RecoveryFiles.js";
+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";
+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, source, 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"],
+    });
+    if (version.exit_code !== 0 ||
+        version.stdout.trim() !== `wakaru ${WAKARU_RELEASE.version}`)
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, `This adapter requires Wakaru ${WAKARU_RELEASE.version}; reported version: ${version.stdout.trim()}; exit: ${String(version.exit_code)}; stderr: ${version.stderr}`);
+    const run = await runWakaruCommand({
+        ...commandContext,
+        staging,
+        arguments: [
+            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 snapshot = await readRecoveryFile(source.snapshot_path, RECOVERY_LIMITS.inputBytes, options?.signal);
+    const parsed = await parseWakaruReports({
+        execution: run,
+        provenancePath: join(staging, "provenance.json"),
+        snapshotPath: source.snapshot_path,
+        sourceBytes: snapshot,
+        files,
+    });
+    return { version, 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 result = await publishWakaruArtifacts({
+        tree,
+        staging,
+        input,
+        source,
+        engine,
+        parsed,
+        execution: run,
+        ...(options?.signal === undefined ? {} : { signal: options.signal }),
+    });
+    if (recoveryDigest(await readRecoveryFile(input.path, RECOVERY_LIMITS.inputBytes, options?.signal)) !== source.sha256)
+        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, {
+        rawResult: jsonValueSchema.parse({
+            version,
+            execution: run,
+            report: parsed.report,
+            provenance: parsed.provenance,
+        }),
+        subject: {
+            path: source.path,
+            sha256: source.sha256,
+            format: "javascript",
+        },
+        locations: [
+            { kind: "artifact-path", path: source.path },
+            ...result.modules.map((module) => ({
+                kind: "artifact-path",
+                path: module.artifact.path,
+            })),
+        ],
+        limitations: result.limitations,
+    });
+};

package/dist/javascript/recovery/WakaruProvider.js

@@ -0,0 +1,96 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {} from "../../application/AnalysisProvider.js";
+import { SafeOutputTree } from "../../artifacts/SafeOutputTree.js";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.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 { 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. */
+export class WakaruProvider {
+    environment;
+    launcher;
+    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) {
+        let root;
+        let tree;
+        let failure;
+        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 source = await snapshotRecoveryInput(input.path, join(inputs, "bundle.js"), options?.signal);
+            tree = await SafeOutputTree.create(input.output_directory).catch((cause) => {
+                throw recoveryInputFailure("output_directory", `Cannot create new recovery directory ${input.output_directory}: ${recoveryFailureMessage(cause)}`, cause);
+            });
+            execution = await prepareWakaruExecution({
+                root,
+                tree,
+                input,
+                source,
+                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) {
+            failure = cause;
+        }
+        if (failure !== undefined) {
+            const residuals = [];
+            try {
+                await tree?.rollback();
+            }
+            catch {
+                if (tree !== undefined)
+                    residuals.push(tree.outputRoot);
+            }
+            if (root !== undefined &&
+                !(failure instanceof AnalysisError && failure.cleanupIncomplete)) {
+                try {
+                    await rm(root, { recursive: true, force: true });
+                }
+                catch {
+                    residuals.push(root);
+                }
+            }
+            if (residuals.length > 0)
+                return err(new ProviderCleanupError("wakaru", residuals, {
+                    previous_error: recoveryFailureMessage(failure),
+                }));
+            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);
+    }
+}

package/dist/javascript/recovery/WakaruPublication.js

@@ -0,0 +1,102 @@
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { javascriptRecoveryResultSchema, } from "../../domain/javascript/javascriptRecovery.js";
+import { readRecoveryFile, recoveryDigest } from "./RecoveryFiles.js";
+import { recoveryRanges, validateRecoverySourceMap, } from "./WakaruReport.js";
+import { RECOVERY_LIMITATIONS, RECOVERY_LIMITS, WAKARU_RELEASE, } from "./WakaruRelease.js";
+/** Write validated artifacts to one exclusively owned, rollback-capable tree. */
+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);
+        return {
+            path: join(tree.outputRoot, file.relativePath),
+            sha256: file.sha256,
+            bytes: file.bytesWritten,
+        };
+    };
+    const snapshot = await readRecoveryFile(source.snapshot_path, RECOVERY_LIMITS.inputBytes, signal);
+    if (recoveryDigest(snapshot) !== source.sha256)
+        throw new AnalysisOutputError("recover_javascript_sources", "The input snapshot changed during recovery");
+    const publishedCopy = await write("inputs/bundle.js", snapshot);
+    const modules = [];
+    for (const module of parsed.report.modules) {
+        modules.push(await publishModule(context, module, write));
+    }
+    const report = await write("reports/stdout.json", Buffer.from(context.execution.stdout));
+    const provenance = await write("reports/provenance.json", await readRecoveryFile(join(staging, "provenance.json"), RECOVERY_LIMITS.reportBytes, signal));
+    const details = {
+        source: { ...source, published_copy: publishedCopy },
+        engine: {
+            id: "wakaru",
+            version: WAKARU_RELEASE.version,
+            executable: {
+                path: context.engine.command,
+                sha256: context.engine.sha256,
+                bytes: context.engine.bytes,
+            },
+            audited_source_revision: WAKARU_RELEASE.revision,
+            executed_source_revision: null,
+        },
+        options: {
+            extraction_mode: context.input.extraction_mode,
+            rewrite_level: context.input.rewrite_level,
+        },
+        status: parsed.status,
+        detected_formats: parsed.report.detected_formats,
+        reported_safety: parsed.report.safety,
+        reported_strategy: parsed.provenance.strategy,
+        reported_format: parsed.provenance.format,
+        total: parsed.report.total,
+        failed: parsed.report.failed,
+        modules,
+        warnings: parsed.report.warnings,
+        report,
+        provenance,
+        analysis_input: modules.length === 0
+            ? null
+            : {
+                input_path: join(tree.outputRoot, "modules"),
+                format: "directory",
+            },
+        runtime_equivalence: "unknown",
+        limitations: [...RECOVERY_LIMITATIONS],
+    };
+    const manifest = await write("manifest.json", Buffer.from(`${JSON.stringify(details, null, 2)}\n`));
+    return javascriptRecoveryResultSchema.parse({ ...details, manifest });
+};
+const publishModule = async (context, module, write) => {
+    const { staging, source, parsed, signal } = context;
+    const artifact = await write(`modules/${module.filename}`, await readRecoveryFile(join(staging, module.filename), RECOVERY_LIMITS.outputBytes, signal));
+    const mapPath = join(staging, `${module.filename}.map`);
+    let sourceMap = null;
+    const map = await readRecoveryFile(mapPath, RECOVERY_LIMITS.outputBytes, signal).catch((cause) => {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return null;
+        throw cause;
+    });
+    if (map !== null) {
+        validateRecoverySourceMap(map, module.filename);
+        sourceMap = await write(`modules/${module.filename}.map`, map);
+    }
+    const provenance = parsed.provenance.modules[module.filename];
+    if (provenance === undefined)
+        throw new AnalysisOutputError("recover_javascript_sources", `Missing module provenance: ${module.filename}`);
+    return {
+        reported_filename: module.filename,
+        reported_status: module.status,
+        artifact,
+        source_map: sourceMap,
+        provenance: {
+            reported_input: provenance.input,
+            original_path: source.path,
+            original_sha256: source.sha256,
+            extraction: provenance.extraction,
+            byte_ranges: recoveryRanges(provenance.ranges),
+            context_byte_ranges: recoveryRanges(provenance.context_ranges ?? []),
+            range_semantics: "half-open-utf8-bytes",
+        },
+    };
+};

package/dist/javascript/recovery/WakaruRelease.js

@@ -0,0 +1,29 @@
+/** Unchanged upstream source pin; executed bytes are identified separately. */
+export const WAKARU_RELEASE = {
+    version: "1.13.0",
+    revision: "6070266d24b32951fa2fe1d2dad5b4313bd5c81b",
+    repository: "https://github.com/pionxzh/wakaru",
+};
+/** Exact provider identity shared by executions and the generated catalog. */
+export const WAKARU_PROVIDER_IDENTITY = {
+    id: "wakaru",
+    name: "Wakaru",
+    version: WAKARU_RELEASE.version,
+};
+/** Per-operation resource bounds for the verified Linux adapter. */
+export const RECOVERY_LIMITS = {
+    inputBytes: 64 * 1024 * 1024,
+    outputBytes: 128 * 1024 * 1024,
+    outputEntries: 10000,
+    reportBytes: 8 * 1024 * 1024,
+    addressSpaceBytes: 1024 * 1024 * 1024,
+    timeoutMs: 120000,
+};
+/** Public limitations for transformations and extraction provenance. */
+export const RECOVERY_LIMITATIONS = [
+    "Recovered sources are derived artifacts; original variable names and runtime equivalence are not established.",
+    "Extraction ranges refer to half-open UTF-8 byte offsets in the original input, not rewritten line positions or whole-bundle coverage.",
+    "Emitted source maps are preserved as reported by the engine; their mapping accuracy is not independently established.",
+    "Inspection mode may produce non-executable regions. No input or recovered application code is executed.",
+    "Linux adapter: one worker, 1 GiB address-space ceiling, 120-second deadline, 64 MiB input, 128 MiB output, 10000 output entries and 8 MiB per diagnostic/report stream. Resource limits are per operation, not aggregate host containment.",
+];