feat(javascript): recover readable modules with Wakaru (#848)

* feat(javascript): recover readable modules with Wakaru

Integrate pinned upstream source behind a typed optional recovery port,
preserve source identity and producer provenance, and publish verified
artifacts for existing JavaScript analysis through CLI and MCP.

Add focused real-tool CI with genuine bundler fixtures and bounded
resource, cancellation, cleanup, schema and packaged-artifact checks.

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(javascript): align recovery catalog and browser verification

Share canonical Wakaru provider identity, describe CLI mode options, and
format the new workflow test. Disconnect the real page transport after
its observation readiness progress instead of a fixed delay.

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* refactor(javascript): consume the investigation evidence writer

Verify that the SDK recovery handler records complete Evidence through the newly shared investigation owner.

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)

* chore(test): account for isolated recovery fixture compilers

* fix(javascript): validate recovery paths before acquiring the engine

Return field-specific invalid_format diagnostics for relative paths and verify compiled CLI/MCP parity even when the optional engine is unavailable.

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)

Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

src/javascript/recovery/RecoveryFiles.ts

@@ -0,0 +1,201 @@
+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: Uint8Array): string =>
+  createHash("sha256").update(bytes).digest("hex");
+
+/** Read a stable regular file without retaining bytes during engine fingerprinting. */
+const scanRecoveryFile = async (
+  path: string,
+  maximum: number,
+  consume: (chunk: Buffer) => void,
+  signal?: AbortSignal,
+) => {
+  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: string,
+  maximum: number,
+  signal?: AbortSignal,
+) => scanRecoveryFile(path, maximum, () => {}, signal);
+
+/** Read only a regular file through one handle with a bounded, stable identity. */
+export const readRecoveryFile = async (
+  path: string,
+  maximum: number,
+  signal?: AbortSignal,
+): Promise<Buffer> => {
+  const chunks: Buffer[] = [];
+  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: string,
+  snapshotPath: string,
+  signal?: AbortSignal,
+) => {
+  if (!isAbsolute(path))
+    throw recoveryInputFailure(
+      "path",
+      "Select an absolute JavaScript file path",
+    );
+  let bytes: Buffer;
+  try {
+    bytes = await readRecoveryFile(path, RECOVERY_LIMITS.inputBytes, signal);
+    new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch (cause: unknown) {
+    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: string,
+  signal?: AbortSignal,
+): Promise<
+  readonly { relativePath: string; path: string; bytes: number }[]
+> => {
+  const files: { relativePath: string; path: string; bytes: number }[] = [];
+  let bytes = 0;
+  let entries = 0;
+  const visit = async (directory: string, prefix: string): Promise<void> => {
+    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: string,
+  message: string,
+  cause?: unknown,
+): AnalysisInputError =>
+  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: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause);
+
+/** Cancellation remains distinct from malformed source or provider output. */
+export const checkRecoveryCancellation = (signal?: AbortSignal): void => {
+  if (signal?.aborted === true) throw new AnalysisCancelledError(OPERATION);
+};
+
+/** Keep both tool invocations within one operation's execution budget. */
+export const checkRecoveryDeadline = (
+  deadline: number,
+  signal?: AbortSignal,
+): void => {
+  checkRecoveryCancellation(signal);
+  if (Date.now() >= deadline)
+    throw new AnalysisTimeoutError(OPERATION, RECOVERY_LIMITS.timeoutMs);
+};

src/javascript/recovery/WakaruCommand.test.ts

@@ -0,0 +1,38 @@
+import { expect, it } from "vitest";
+import { runWakaruCommand } from "./WakaruCommand.js";
+
+it("rejects an exhausted shared execution budget before launching the next command", async () => {
+  await expect(
+    runWakaruCommand({
+      command: "/selected/wakaru",
+      limiter: "/usr/bin/prlimit",
+      arguments: ["--version"],
+      cwd: "/tmp/unused",
+      environment: {},
+      deadline: Date.now() - 1,
+      launcher: async () => {
+        throw new Error("An expired budget must not launch");
+      },
+    }),
+  ).rejects.toMatchObject({
+    _tag: "AnalysisTimeoutError",
+    operation: "recover_javascript_sources",
+  });
+});
+
+it("preserves caller cancellation before acquiring an expired execution budget", async () => {
+  await expect(
+    runWakaruCommand({
+      command: "/selected/wakaru",
+      limiter: "/usr/bin/prlimit",
+      arguments: ["--version"],
+      cwd: "/tmp/unused",
+      environment: {},
+      deadline: Date.now() - 1,
+      signal: AbortSignal.abort(),
+      launcher: async () => {
+        throw new Error("A cancelled request must not launch");
+      },
+    }),
+  ).rejects.toMatchObject({ _tag: "AnalysisCancelledError" });
+});

src/javascript/recovery/WakaruCommand.ts

@@ -0,0 +1,176 @@
+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,
+  type OwnedProviderProcessSpawnOptions,
+  type SpawnedOwnedProviderProcess,
+} from "../../process/ProviderProcess.js";
+import {
+  checkRecoveryDeadline,
+  inventoryRecoveryFiles,
+  fingerprintRecoveryFile,
+  recoveryFailureMessage,
+} from "./RecoveryFiles.js";
+import { RECOVERY_LIMITS } from "./WakaruRelease.js";
+
+const OPERATION = "recover_javascript_sources";
+
+/** Inject the owned process launcher while retaining production protocol parsing. */
+export type WakaruLauncher = (
+  options: OwnedProviderProcessSpawnOptions,
+) => Promise<SpawnedOwnedProviderProcess>;
+
+/** Resolve and fingerprint explicitly configured tools; acquire nothing at startup. */
+export const resolveWakaruCommand = async (
+  environment: Readonly<Record<string, string | undefined>>,
+) => {
+  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: unknown) {
+    throw new AnalysisCapabilityUnavailableError(
+      "wakaru",
+      OPERATION,
+      `Configured Wakaru or util-linux prlimit is unavailable: ${recoveryFailureMessage(cause)}`,
+      { cause },
+    );
+  }
+};
+
+type WakaruCommandContext = {
+  command: string;
+  limiter: string;
+  arguments: readonly string[];
+  cwd: string;
+  deadline: number;
+  environment: Readonly<Record<string, string | undefined>>;
+  signal?: AbortSignal;
+  launcher?: WakaruLauncher;
+  staging?: string;
+};
+
+/** Run one bounded command and verify cleanup before consuming its output. */
+export const runWakaruCommand = async (context: WakaruCommandContext) => {
+  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: unknown) => {
+    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: unknown;
+  try {
+    while (!(await supervisor.waitForExit(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: unknown) {
+    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,
+  };
+};

src/javascript/recovery/WakaruExecution.ts

@@ -0,0 +1,170 @@
+import { join } from "node:path";
+import {
+  createAnalysisExecution,
+  type ExecutionOptions,
+} from "../../application/AnalysisProvider.js";
+import type { SafeOutputTree } from "../../artifacts/SafeOutputTree.js";
+import {
+  AnalysisCapabilityUnavailableError,
+  AnalysisOutputError,
+} from "../../domain/analysisErrorCore.js";
+import type { JavaScriptRecoveryInput } from "../../domain/javascriptRecovery.js";
+import { jsonValueSchema } from "../../domain/jsonValue.js";
+import {
+  fingerprintRecoveryFile,
+  inventoryRecoveryFiles,
+  readRecoveryFile,
+  recoveryDigest,
+  type snapshotRecoveryInput,
+} from "./RecoveryFiles.js";
+import {
+  runWakaruCommand,
+  type resolveWakaruCommand,
+  type WakaruLauncher,
+} 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",
+} as const;
+
+type RecoveryWorkspace = {
+  root: string;
+  tree: SafeOutputTree;
+  input: JavaScriptRecoveryInput;
+  source: Awaited<ReturnType<typeof snapshotRecoveryInput>>;
+  engine: Awaited<ReturnType<typeof resolveWakaruCommand>>;
+  environment: Readonly<Record<string, string | undefined>>;
+  launcher: WakaruLauncher | undefined;
+  options: ExecutionOptions | undefined;
+  deadline: number;
+};
+
+/** Consume the pinned producer representation in a private workspace. */
+const executeWakaruRecovery = async (context: RecoveryWorkspace) => {
+  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: RecoveryWorkspace) => {
+  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" as const,
+        path: module.artifact.path,
+      })),
+    ],
+    limitations: result.limitations,
+  });
+};

src/javascript/recovery/WakaruProvider.ts

@@ -0,0 +1,127 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { JavaScriptRecoveryPort } from "../../application/JavaScriptRecoveryPort.js";
+import {
+  type AnalysisExecution,
+  type ExecutionOptions,
+} from "../../application/AnalysisProvider.js";
+import { SafeOutputTree } from "../../artifacts/SafeOutputTree.js";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import type { JavaScriptRecoveryInput } from "../../domain/javascriptRecovery.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { err, ok, type Result } from "../../domain/result.js";
+import {
+  checkRecoveryCancellation,
+  checkRecoveryDeadline,
+  recoveryFailureMessage,
+  recoveryInputFailure,
+  snapshotRecoveryInput,
+} from "./RecoveryFiles.js";
+import { resolveWakaruCommand, type WakaruLauncher } 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 implements JavaScriptRecoveryPort {
+  constructor(
+    readonly environment: Readonly<
+      Record<string, string | undefined>
+    > = process.env,
+    readonly launcher?: WakaruLauncher,
+  ) {}
+
+  /** Recover one script using validated upstream reports and verified output bytes. */
+  async recover(
+    input: JavaScriptRecoveryInput,
+    options?: ExecutionOptions,
+  ): Promise<Result<AnalysisExecution, AnalysisError>> {
+    let root: string | undefined;
+    let tree: SafeOutputTree | undefined;
+    let failure: unknown;
+    let execution: AnalysisExecution | undefined;
+    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: unknown) => {
+          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: unknown) {
+      failure = cause;
+    }
+    if (failure !== undefined) {
+      const residuals: string[] = [];
+      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);
+  }
+}

src/javascript/recovery/WakaruPublication.ts

@@ -0,0 +1,181 @@
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import type { SafeOutputTree } from "../../artifacts/SafeOutputTree.js";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import {
+  javascriptRecoveryResultSchema,
+  type JavaScriptRecoveryInput,
+  type JavaScriptRecoveryResult,
+} from "../../domain/javascriptRecovery.js";
+import { readRecoveryFile, recoveryDigest } from "./RecoveryFiles.js";
+import {
+  recoveryRanges,
+  validateRecoverySourceMap,
+  type parseWakaruReports,
+} from "./WakaruReport.js";
+import {
+  RECOVERY_LIMITATIONS,
+  RECOVERY_LIMITS,
+  WAKARU_RELEASE,
+} from "./WakaruRelease.js";
+import type {
+  resolveWakaruCommand,
+  runWakaruCommand,
+} from "./WakaruCommand.js";
+
+type PublicationContext = {
+  tree: SafeOutputTree;
+  staging: string;
+  input: JavaScriptRecoveryInput;
+  source: {
+    path: string;
+    snapshot_path: string;
+    sha256: string;
+    bytes: number;
+  };
+  engine: Awaited<ReturnType<typeof resolveWakaruCommand>>;
+  parsed: Awaited<ReturnType<typeof parseWakaruReports>>;
+  execution: Awaited<ReturnType<typeof runWakaruCommand>>;
+  signal?: AbortSignal;
+};
+type PublishedFile = JavaScriptRecoveryResult["manifest"];
+type RecoveryWriter = (path: string, bytes: Buffer) => Promise<PublishedFile>;
+
+/** Write validated artifacts to one exclusively owned, rollback-capable tree. */
+export const publishWakaruArtifacts = async (
+  context: PublicationContext,
+): Promise<JavaScriptRecoveryResult> => {
+  const { tree, source, parsed, staging, signal } = context;
+  const write = async (path: string, bytes: Buffer) => {
+    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: JavaScriptRecoveryResult["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" as const,
+          },
+    runtime_equivalence: "unknown" as const,
+    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: PublicationContext,
+  module: PublicationContext["parsed"]["report"]["modules"][number],
+  write: RecoveryWriter,
+): Promise<JavaScriptRecoveryResult["modules"][number]> => {
+  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: JavaScriptRecoveryResult["modules"][number]["source_map"] =
+    null;
+  const map = await readRecoveryFile(
+    mapPath,
+    RECOVERY_LIMITS.outputBytes,
+    signal,
+  ).catch((cause: unknown) => {
+    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",
+    },
+  };
+};

src/javascript/recovery/WakaruRelease.ts

@@ -0,0 +1,32 @@
+/** 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",
+} as const;
+
+/** Exact provider identity shared by executions and the generated catalog. */
+export const WAKARU_PROVIDER_IDENTITY = {
+  id: "wakaru",
+  name: "Wakaru",
+  version: WAKARU_RELEASE.version,
+} as const;
+
+/** 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,
+} as const;
+
+/** 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.",
+] as const;

src/javascript/recovery/WakaruReport.ts

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import {
+  normalizeArtifactPath,
+  ArtifactPathRegistry,
+} from "../../artifacts/ArtifactPaths.js";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import type { JavaScriptRecoveryResult } from "../../domain/javascriptRecovery.js";
+import { readRecoveryFile, recoveryFailureMessage } from "./RecoveryFiles.js";
+import { RECOVERY_LIMITS } from "./WakaruRelease.js";
+import type { runWakaruCommand } from "./WakaruCommand.js";
+
+const warningSchema = z.strictObject({
+  filename: z.string(),
+  kind: z.string(),
+  is_error: z.boolean(),
+  message: z.string(),
+});
+const reportSchema = z.strictObject({
+  detected_formats: z.array(z.string()),
+  safety: z.string(),
+  modules: z.array(
+    z.strictObject({
+      filename: z.string().min(1),
+      kind: z.literal("javascript"),
+      status: z.literal("decompiled"),
+    }),
+  ),
+  warnings: z.array(warningSchema),
+  total: z.number().int().nonnegative(),
+  failed: z.number().int().nonnegative(),
+  elapsed_ms: z.number().int().nonnegative(),
+});
+const rangeSchema = z.tuple([
+  z.number().int().nonnegative(),
+  z.number().int().nonnegative(),
+]);
+const provenanceSchema = z.strictObject({
+  format: z.string(),
+  strategy: z.string(),
+  modules: z.record(
+    z.string(),
+    z.strictObject({
+      input: z.string(),
+      ranges: z.array(rangeSchema),
+      extraction: z.string(),
+      context_ranges: z.array(rangeSchema).optional(),
+    }),
+  ),
+});
+
+const OPERATION = "recover_javascript_sources";
+
+type ReportContext = {
+  execution: Awaited<ReturnType<typeof runWakaruCommand>>;
+  provenancePath: string;
+  snapshotPath: string;
+  sourceBytes: Buffer;
+  files: readonly { relativePath: string }[];
+};
+
+/** Parse exact pinned producer JSON before projecting provider-neutral artifacts. */
+export const parseWakaruReports = async (context: ReportContext) => {
+  const { execution, provenancePath } = context;
+
+  try {
+    if (execution.exit_code !== 0 && execution.exit_code !== 1)
+      throw new TypeError(
+        "Wakaru did not complete recovery (expected exit 0 or a reported partial exit 1)",
+      );
+    const report = reportSchema.parse(JSON.parse(execution.stdout));
+    const provenance = provenanceSchema.parse(
+      JSON.parse(
+        (
+          await readRecoveryFile(provenancePath, RECOVERY_LIMITS.reportBytes)
+        ).toString("utf8"),
+      ),
+    );
+    if (report.total !== report.modules.length || report.failed > report.total)
+      throw new TypeError("Reported module totals disagree");
+    if (
+      execution.exit_code === 1 &&
+      report.failed === 0 &&
+      !report.warnings.some((warning) => warning.is_error)
+    )
+      throw new TypeError(
+        "Wakaru exited 1 without a reported partial recovery reason",
+      );
+    validateModuleSet(report, provenance, context);
+    return {
+      report,
+      provenance,
+      status:
+        report.failed > 0 ||
+        report.warnings.some((warning) => warning.is_error) ||
+        execution.exit_code === 1
+          ? ("partial" as const)
+          : ("complete" as const),
+    };
+  } catch (cause: unknown) {
+    throw new ProviderAdapterError("wakaru", OPERATION, {
+      cause,
+      diagnostics: {
+        reason: `Unusable Wakaru recovery report: ${recoveryFailureMessage(cause)}`,
+        exit_code: execution.exit_code,
+        signal: execution.signal,
+        stdout: execution.stdout,
+        stderr: execution.stderr,
+      },
+    });
+  }
+};
+
+const validateModuleSet = (
+  report: z.output<typeof reportSchema>,
+  provenance: z.output<typeof provenanceSchema>,
+  context: ReportContext,
+): void => {
+  const { files, snapshotPath, sourceBytes } = context;
+  const registry = new ArtifactPathRegistry();
+  const expected = new Set(["provenance.json"]);
+  const observed = new Set(files.map((file) => file.relativePath));
+  for (const module of report.modules) {
+    const path = normalizeArtifactPath(module.filename);
+    if (path !== module.filename || !/\.(?:js|mjs|cjs)$/u.test(path))
+      throw new TypeError(`Unsupported module path: ${module.filename}`);
+    registry.add(path, "file");
+    if (!observed.has(path))
+      throw new TypeError(`Missing reported module file: ${path}`);
+    expected.add(path);
+    if (observed.has(`${path}.map`)) expected.add(`${path}.map`);
+    const entry = provenance.modules[path];
+    if (entry === undefined || entry.input !== snapshotPath)
+      throw new TypeError(
+        `Module provenance does not bind the selected input snapshot: ${path}`,
+      );
+    validateRanges(
+      [...entry.ranges, ...(entry.context_ranges ?? [])],
+      sourceBytes,
+      path,
+    );
+  }
+  if (Object.keys(provenance.modules).length !== report.modules.length)
+    throw new TypeError("Provenance and reported module sets disagree");
+  for (const path of observed)
+    if (!expected.has(path))
+      throw new TypeError(`Unreported recovery artifact: ${path}`);
+};
+
+const validateRanges = (
+  ranges: readonly [number, number][],
+  bytes: Buffer,
+  filename: string,
+): void => {
+  for (const [start, end] of ranges) {
+    if (
+      start > end ||
+      end > bytes.length ||
+      !utf8Boundary(bytes, start) ||
+      !utf8Boundary(bytes, end)
+    )
+      throw new TypeError(
+        `Invalid half-open UTF-8 byte range [${String(start)},${String(end)}) for ${filename}`,
+      );
+  }
+};
+
+const utf8Boundary = (bytes: Buffer, offset: number): boolean => {
+  const value = bytes[offset];
+  return value === undefined || (value & 0xc0) !== 0x80;
+};
+
+/** Translate extraction byte ranges without claiming rewritten line positions. */
+export const recoveryRanges = (
+  ranges: readonly [number, number][],
+): JavaScriptRecoveryResult["modules"][number]["provenance"]["byte_ranges"] =>
+  ranges.map(([start, end]) => ({ start, end }));
+
+/** Validate a source map's representation; preserve its unverified mapping bytes. */
+export const validateRecoverySourceMap = (
+  bytes: Buffer,
+  filename: string,
+): void => {
+  const schema = z.object({
+    version: z.literal(3),
+    sources: z.array(z.string()),
+    names: z.array(z.string()),
+    mappings: z.string(),
+  });
+  try {
+    schema.parse(JSON.parse(bytes.toString("utf8")));
+  } catch (cause: unknown) {
+    throw new AnalysisOutputError(
+      OPERATION,
+      `Invalid emitted source map for ${filename}: ${recoveryFailureMessage(cause)}`,
+      { cause },
+    );
+  }
+};