fix(javascript): isolate source analysis and retain bounded partial evidence (#1651)

* refactor(javascript): validate transferable file projections

* test(javascript): consume decoded module and static facts

* fix(javascript): isolate source analysis and retain bounded partial evidence

* test(javascript): verify cleanup retention and repeated source paths

src/javascript/analysis/JavaScriptAnalysisWorker.ts

@@ -0,0 +1,726 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { fileURLToPath } from "node:url";
+import { getHeapStatistics } from "node:v8";
+import { z } from "zod";
+import type { JavaScriptArtifactFile } from "../../domain/javascript/javascriptArtifactFiles.js";
+import type { JavaScriptStaticAnalysis } from "../../domain/javascript/javascriptStaticAnalysisTypes.js";
+import { estimateJavaScriptStaticApplicationProjection } from "../../domain/javascript/javascriptApplicationProjectionResources.js";
+import type { JavaScriptModuleSemanticIr } from "../../domain/javascript/javascriptModuleSemanticIr.js";
+import type { JavaScriptSemanticFileProjection } from "../../domain/javascript/javascriptSemanticFileProjection.js";
+import type {
+  JavaScriptAnalyzedSource,
+  JavaScriptSourceAnalysisFailure,
+  JavaScriptSourceAnalysisLimits,
+} from "../../domain/javascript/javascriptSourceAnalysis.js";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import {
+  AnalysisCancelledError,
+  AnalysisTimeoutError,
+  AnalysisOutputError,
+  AnalysisResourceConstraintError,
+  AnalysisCapabilityUnavailableError,
+} from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { ok, err, type Result } from "../../domain/result.js";
+import {
+  PrivateRuntimeRoot,
+  PrivateRuntimeRootUnavailableError,
+} from "../../process/PrivateRuntimeRoot.js";
+import {
+  ProviderProcessSupervisor,
+  spawnOwnedProviderProcess,
+} from "../../process/ProviderProcess.js";
+import { cleanupOwnedProcessGroup } from "../../process/ProcessOwnership.js";
+import { prepareProcessOwnershipInspection } from "../../process/ProcessOwnershipObservation.js";
+import {
+  ProviderStartupDeadline,
+  waitForAbortableDelay,
+} from "../../process/ProviderDeadline.js";
+import {
+  readJavaScriptAnalysisTransfer,
+  JAVASCRIPT_ANALYSIS_TRANSFER_RECORD_BYTES,
+  javaScriptTransferRetentionBytes,
+} from "./JavaScriptAnalysisTransfer.js";
+import { javaScriptWorkerStaticAnalysisSchema } from "./JavaScriptAnalysisWorkerSchemas.js";
+import {
+  JAVASCRIPT_ANALYSIS_WORKER_DEFAULTS as DEFAULTS,
+  javaScriptWorkerMessageSchema,
+  javaScriptWorkerRequestSchema,
+  javaScriptWorkerAdmissionSchema,
+  type JavaScriptWorkerMessage,
+} from "./JavaScriptAnalysisWorkerProtocol.js";
+
+const OPERATION = "analyze_javascript_application";
+const PROVIDER = "javascript-static-analysis";
+const MIB = 1024 * 1024;
+const pendingCleanup = new Set<JavaScriptAnalysisWorker>();
+
+/** One sequential owned worker, retained between source files and closed after analysis. */
+export class JavaScriptAnalysisWorker {
+  readonly #runId = `rea-javascript-analysis-${randomUUID()}`;
+  #root: PrivateRuntimeRoot | undefined;
+  #supervisor: ProviderProcessSupervisor | undefined;
+  #ready = false;
+  #heapLimitBytes = 0;
+  #frames: JavaScriptWorkerMessage[] = [];
+  #pending = "";
+  #decoder = new StringDecoder("utf8");
+  #protocolFailure: string | undefined;
+  #phase = "startup";
+  #lastFailure: AnalysisError | undefined;
+  #estimatedRetainedBytes = 0;
+  #applicationProjectionFailure: AnalysisResourceConstraintError | undefined;
+  #parentCapacityExhausted = false;
+  #retainedStaticBytes = 0;
+  #sourcesRemaining: number | undefined;
+  readonly #resultBudgetBytes: number;
+  readonly #onStdout = (chunk: Buffer | string): void => {
+    try {
+      this.#pending +=
+        typeof chunk === "string" ? chunk : this.#decoder.write(chunk);
+      let newline: number;
+      while ((newline = this.#pending.indexOf("\n")) >= 0) {
+        const line = this.#pending.slice(0, newline);
+        this.#pending = this.#pending.slice(newline + 1);
+        if (
+          Buffer.byteLength(line) > DEFAULTS.protocolBytes ||
+          this.#frames.length >= 16
+        )
+          throw new RangeError(
+            "JavaScript worker exceeded its control-frame budget",
+          );
+        const raw: unknown = JSON.parse(line);
+        this.#frames.push(javaScriptWorkerMessageSchema.parse(raw));
+      }
+      if (Buffer.byteLength(this.#pending) > DEFAULTS.protocolBytes)
+        throw new RangeError(
+          "JavaScript worker control frame is unterminated or oversized",
+        );
+    } catch (cause: unknown) {
+      this.#protocolFailure = message(cause);
+    }
+  };
+
+  constructor(
+    readonly limits: JavaScriptSourceAnalysisLimits = DEFAULTS,
+    readonly launcher: typeof spawnOwnedProviderProcess = spawnOwnedProviderProcess,
+    sourceCount?: number,
+  ) {
+    if (
+      !Number.isSafeInteger(limits.heapMb) ||
+      limits.heapMb < 128 ||
+      limits.heapMb > 16_384 ||
+      !Number.isSafeInteger(limits.timeoutMs) ||
+      limits.timeoutMs <= 0 ||
+      limits.timeoutMs > 2_147_483_647
+    )
+      throw new RangeError(
+        "JavaScript worker requires valid heap and execution limits",
+      );
+    if (
+      sourceCount !== undefined &&
+      (!Number.isSafeInteger(sourceCount) || sourceCount < 0)
+    )
+      throw new RangeError(
+        "JavaScript worker source count must be a nonnegative safe integer",
+      );
+    this.#sourcesRemaining = sourceCount;
+    // Reserve host-side control, schema/Evidence work and a maximum record's
+    // transient copies. Admission also accounts for retained earlier files.
+    this.#resultBudgetBytes = Math.max(
+      0,
+      Math.floor(
+        (getHeapStatistics().heap_size_limit -
+          process.memoryUsage().heapUsed -
+          24 * JAVASCRIPT_ANALYSIS_TRANSFER_RECORD_BYTES) /
+          2,
+      ),
+    );
+  }
+
+  /** Analyze inert source; hard worker failure does not terminate this process. */
+  async analyze(
+    file: JavaScriptArtifactFile,
+    nodeBudget: number,
+    signal?: AbortSignal,
+  ): Promise<
+    Result<JavaScriptAnalyzedSource, JavaScriptSourceAnalysisFailure>
+  > {
+    let javascript: JavaScriptStaticAnalysis | null = null;
+    let module: JavaScriptModuleSemanticIr | null = null;
+    let projection: JavaScriptSemanticFileProjection | null = null;
+    const id = randomUUID();
+    this.#applicationProjectionFailure = undefined;
+    this.#parentCapacityExhausted = false;
+    if (this.#sourcesRemaining !== undefined)
+      this.#sourcesRemaining = Math.max(0, this.#sourcesRemaining - 1);
+    let deadline: ProviderStartupDeadline | undefined;
+    let result: Result<
+      JavaScriptAnalyzedSource,
+      JavaScriptSourceAnalysisFailure
+    >;
+    try {
+      if (signal?.aborted === true) throw new AnalysisCancelledError(OPERATION);
+      if (!file.text.included || file.kind !== "javascript")
+        throw new TypeError(
+          "JavaScript analysis worker requires included JavaScript text",
+        );
+      // Host ownership preparation is outside the parser execution deadline.
+      await prepareProcessOwnershipInspection(signal);
+      for (const owner of pendingCleanup) await owner.close();
+      deadline = new ProviderStartupDeadline(this.limits.timeoutMs, signal);
+      await this.#start(deadline);
+      const root = this.#root;
+      const supervisor = this.#supervisor;
+      if (root === undefined || supervisor === undefined)
+        throw new TypeError("JavaScript worker resources were not acquired");
+      if (this.#frames.length !== 0 || this.#pending !== "")
+        throw new AnalysisOutputError(
+          OPERATION,
+          "JavaScript worker has unsolicited or incomplete control frames",
+        );
+      supervisor.resetOutput();
+      this.#phase = "source-transfer";
+      await writeFile(join(root.path, `${id}.source`), file.text.value, {
+        flag: "wx",
+        mode: 0o600,
+        signal: deadline.signal,
+      });
+      const { text: _text, ...metadata } = file;
+      let offeredResultBudget = 0;
+      const request = javaScriptWorkerRequestSchema.parse({
+        id,
+        node_budget: nodeBudget,
+        text_sha256: createHash("sha256").update(file.text.value).digest("hex"),
+        file: metadata,
+      });
+      const frame = `${JSON.stringify(request)}\n`;
+      if (Buffer.byteLength(frame) > DEFAULTS.protocolBytes)
+        throw new AnalysisResourceConstraintError(
+          OPERATION,
+          "transport",
+          `Source identity for ${file.path} exceeds the worker request byte budget`,
+          { worker_request_bytes: DEFAULTS.protocolBytes },
+        );
+      const stdin = supervisor.launch.process.stdin;
+      if (stdin === undefined || stdin === null)
+        throw new TypeError("JavaScript worker has no writable request stream");
+      await new Promise<void>((resolve, reject) =>
+        stdin.write(frame, (error) =>
+          error === null || error === undefined ? resolve() : reject(error),
+        ),
+      );
+      for (;;) {
+        const response = await this.#next(deadline, file.path);
+        if (response.kind === "ready" || response.id !== id)
+          throw new AnalysisOutputError(
+            OPERATION,
+            "JavaScript worker response names a different source job",
+          );
+        if (response.kind === "phase") {
+          this.#phase = response.phase;
+          continue;
+        }
+        if (response.kind === "static") {
+          if (javascript !== null)
+            throw new AnalysisOutputError(
+              OPERATION,
+              "JavaScript worker emitted a duplicate static checkpoint",
+            );
+          javascript = await this.#readCheckpoint(id, file.path, response);
+          if (this.#parentCapacityExhausted)
+            throw new AnalysisResourceConstraintError(
+              OPERATION,
+              "memory",
+              `The parent's result capacity was exhausted after retaining static facts for ${file.path}; remaining sources were not analyzed`,
+              {
+                ...this.#limits(),
+                parent_result_budget_bytes: this.#resultBudgetBytes,
+                parent_result_budget_exhausted: true,
+              },
+            );
+          offeredResultBudget =
+            this.#applicationProjectionFailure !== undefined &&
+            this.#sourcesRemaining !== undefined &&
+            this.#sourcesRemaining > 0
+              ? 0
+              : this.#remainingResultBudget();
+          const admission = javaScriptWorkerAdmissionSchema.parse({
+            id,
+            semantic_result_budget_bytes: offeredResultBudget,
+          });
+          await new Promise<void>((resolve, reject) =>
+            stdin.write(`${JSON.stringify(admission)}\n`, (error) =>
+              error === null || error === undefined ? resolve() : reject(error),
+            ),
+          );
+          continue;
+        }
+        if (response.kind === "failure") {
+          if (response.reason === "resource") {
+            result = err({
+              javascript,
+              module,
+              projection,
+              error: new AnalysisResourceConstraintError(
+                OPERATION,
+                response.resource ?? "memory",
+                `${file.path}: ${response.message}`,
+                { ...this.#limits(), ...response.limits },
+              ),
+            });
+            break;
+          }
+          throw new AnalysisOutputError(
+            OPERATION,
+            `${file.path} during ${this.#phase}: ${response.message}`,
+          );
+        }
+        if (javascript === null)
+          throw new AnalysisOutputError(
+            OPERATION,
+            "JavaScript worker completed before a static checkpoint",
+          );
+        if (response.descriptor === null) {
+          result = ok({ javascript, module: null, projection: null });
+          break;
+        }
+        const descriptor = response.descriptor;
+        // JSON bytes alone omit object/array overhead and the later graph/Evidence
+        // sealing/serialization copies. Reserve a conservative expansion budget.
+        const moduleEstimate = javaScriptTransferRetentionBytes(
+          descriptor.module_bytes,
+          descriptor.module_records,
+        );
+        const graphEstimate = javaScriptTransferRetentionBytes(
+          descriptor.graph_bytes,
+          descriptor.graph_records,
+        );
+        const remaining = Math.min(
+          offeredResultBudget,
+          this.#remainingResultBudget(),
+        );
+        if (moduleEstimate > remaining) {
+          result = err({
+            javascript,
+            module: null,
+            projection: null,
+            error: new AnalysisResourceConstraintError(
+              OPERATION,
+              "memory",
+              `Completed module facts for ${file.path} exceed the parent's remaining result budget; static facts were retained`,
+              {
+                ...this.#limits(),
+                parent_result_budget_bytes: this.#resultBudgetBytes,
+                module_transfer_bytes: descriptor.module_bytes,
+              },
+            ),
+          });
+          break;
+        }
+        const retainGraph = moduleEstimate + graphEstimate <= remaining;
+        this.#phase = "result-admission";
+        const decoded = await readJavaScriptAnalysisTransfer(
+          join(root.path, `${id}.records`),
+          descriptor,
+          file,
+          deadline.signal,
+          retainGraph,
+        );
+        module = decoded.module;
+        projection = decoded.projection;
+        this.#estimatedRetainedBytes +=
+          moduleEstimate + (retainGraph ? graphEstimate : 0);
+        result = retainGraph
+          ? ok({ javascript, module, projection: decoded.projection })
+          : err({
+              javascript,
+              module,
+              projection,
+              error: new AnalysisResourceConstraintError(
+                OPERATION,
+                "memory",
+                `Semantic graph for ${file.path} exceeds the parent's remaining result budget; static and module facts were retained`,
+                {
+                  ...this.#limits(),
+                  parent_result_budget_bytes: this.#resultBudgetBytes,
+                  graph_transfer_bytes: descriptor.graph_bytes,
+                  graph_records: descriptor.graph_records,
+                },
+              ),
+            });
+        break;
+      }
+    } catch (cause: unknown) {
+      const error = this.#failure(cause, file.path, deadline);
+      this.#lastFailure = error;
+      // Complete checkpoints remain readable after a child crash or cancellation.
+      const cleanup = await this.#stop(error);
+      if (
+        cleanup === undefined &&
+        javascript === null &&
+        this.#root !== undefined
+      ) {
+        try {
+          javascript = await this.#readCheckpoint(id, file.path);
+        } catch (checkpointCause: unknown) {
+          void checkpointCause;
+        }
+      }
+      result = err({ error: cleanup ?? error, javascript, module, projection });
+    } finally {
+      deadline?.dispose();
+    }
+    if (result.ok) this.#lastFailure = undefined;
+    else if (!(result.error.error instanceof ProviderCleanupError))
+      this.#lastFailure = result.error.error;
+    // Child stop must be verified before temporary files are released. On
+    // cleanup uncertainty, close retains this owner for a later retry.
+    if (this.#root !== undefined && !pendingCleanup.has(this)) {
+      try {
+        for (const suffix of ["source", "static.json", "records"])
+          await rm(join(this.#root.path, `${id}.${suffix}`), { force: true });
+      } catch (cause: unknown) {
+        pendingCleanup.add(this);
+        return err({
+          javascript,
+          module,
+          projection,
+          error: this.#cleanupError(message(cause)),
+        });
+      }
+    }
+    if (this.#applicationProjectionFailure !== undefined)
+      return result.ok
+        ? ok({
+            ...result.value,
+            applicationProjectionFailure: this.#applicationProjectionFailure,
+          })
+        : err({
+            ...result.error,
+            applicationProjectionFailure: this.#applicationProjectionFailure,
+          });
+    return result;
+  }
+
+  /** Verify process cleanup, then release the private runtime; failed close is retryable. */
+  async close(): Promise<void> {
+    const failure = await this.#stop();
+    if (failure !== undefined) throw failure;
+    if (this.#root !== undefined) {
+      try {
+        await this.#root.close();
+        this.#root = undefined;
+      } catch (cause: unknown) {
+        pendingCleanup.add(this);
+        throw this.#cleanupError(message(cause));
+      }
+    }
+    pendingCleanup.delete(this);
+  }
+
+  async #start(deadline: ProviderStartupDeadline): Promise<void> {
+    if (this.#supervisor !== undefined && this.#ready) return;
+    this.#phase = "startup";
+    this.#heapLimitBytes = 0;
+    this.#root ??= await PrivateRuntimeRoot.create({
+      prefix: "rea-javascript-analysis-",
+    });
+    const environment: NodeJS.ProcessEnv = {
+      ...process.env,
+      UV_THREADPOOL_SIZE: "1",
+    };
+    delete environment.NODE_OPTIONS;
+    const spawned = await this.launcher({
+      command: process.execPath,
+      arguments: [
+        `--max-old-space-size=${String(this.limits.heapMb)}`,
+        "--max-semi-space-size=8",
+        "--v8-pool-size=1",
+        "--expose-gc",
+        "--stack_size=2048",
+        fileURLToPath(import.meta.resolve("#javascript-analysis-worker")),
+      ],
+      runId: `${this.#runId}-${randomUUID()}`,
+      cwd: this.#root.path,
+      hostEnvironment: environment,
+      stdin: "pipe",
+      signal: deadline.signal,
+    });
+    this.#supervisor = new ProviderProcessSupervisor(
+      {
+        ...spawned,
+        ownsProcessLifetime: true,
+        cleanup:
+          spawned.cleanup ??
+          (() => cleanupOwnedProcessGroup(spawned.ownership)),
+      },
+      { captureStdout: false, maxDiagnosticBytes: 256 * 1024 },
+    );
+    spawned.process.stdout?.on("data", this.#onStdout);
+    const ready = await this.#next(deadline, "worker startup");
+    if (ready.kind !== "ready")
+      throw new AnalysisOutputError(
+        OPERATION,
+        "JavaScript worker emitted facts before its startup handshake",
+      );
+    this.#heapLimitBytes = ready.heap_limit_bytes;
+    this.#ready = true;
+  }
+
+  async #next(
+    deadline: ProviderStartupDeadline,
+    path: string,
+  ): Promise<JavaScriptWorkerMessage> {
+    for (;;) {
+      if (deadline.interruption === "cancelled")
+        throw new AnalysisCancelledError(OPERATION);
+      if (deadline.interruption === "timeout")
+        throw new AnalysisTimeoutError(OPERATION, this.limits.timeoutMs);
+      if (this.#protocolFailure !== undefined)
+        throw new AnalysisOutputError(OPERATION, this.#protocolFailure);
+      const frame = this.#frames.shift();
+      if (frame !== undefined) return frame;
+      const snapshot = this.#supervisor?.snapshot();
+      if (
+        snapshot !== undefined &&
+        (snapshot.exitCode !== undefined || snapshot.signal !== undefined)
+      ) {
+        // Exit is not complete output: let any final control frame drain first.
+        if (!(await this.#supervisor?.waitForOutputClose(10))) continue;
+        if (this.#frames.length !== 0) continue;
+        const drained = this.#supervisor?.snapshot() ?? snapshot;
+        throw /heap out of memory|heap limit|allocation failed/iu.test(
+          drained.stderr.text,
+        )
+          ? new AnalysisResourceConstraintError(
+              OPERATION,
+              "memory",
+              `Owned JavaScript worker exhausted its heap while analyzing ${path} during ${this.#phase}`,
+              this.#limits(),
+              { capturedOutput: this.#captured() },
+            )
+          : new ProviderAdapterError(PROVIDER, OPERATION, {
+              capturedOutput: this.#captured(),
+              diagnostics: {
+                source_path: path,
+                phase: this.#phase,
+                exit_code: drained.exitCode ?? null,
+                signal: drained.signal ?? null,
+              },
+            });
+      }
+      await waitForAbortableDelay(10, deadline.signal);
+    }
+  }
+
+  async #readCheckpoint(
+    id: string,
+    sourcePath: string,
+    expected?: { readonly bytes: number; readonly sha256: string },
+  ): Promise<JavaScriptStaticAnalysis> {
+    if (this.#root === undefined)
+      throw new TypeError("JavaScript checkpoint has no owned runtime");
+    const path = join(this.#root.path, `${id}.static.json`);
+    const bytes = (await stat(path)).size;
+    if (
+      bytes > DEFAULTS.checkpointBytes ||
+      (expected !== undefined && expected.bytes !== bytes)
+    )
+      throw new AnalysisOutputError(
+        OPERATION,
+        "JavaScript static checkpoint byte count exceeds or differs from its declared budget",
+      );
+    if (
+      bytes * 16 + 4 * MIB >
+      getHeapStatistics().heap_size_limit -
+        process.memoryUsage().heapUsed -
+        64 * MIB
+    )
+      throw new AnalysisResourceConstraintError(
+        OPERATION,
+        "memory",
+        "The parent's remaining heap cannot safely decode the completed JavaScript static checkpoint",
+        { ...this.#limits(), checkpoint_bytes: bytes },
+      );
+    const text = await readFile(path, "utf8");
+    if (
+      expected !== undefined &&
+      createHash("sha256").update(text).digest("hex") !== expected.sha256
+    )
+      throw new AnalysisOutputError(
+        OPERATION,
+        "JavaScript static checkpoint digest does not match",
+      );
+    const value: unknown = JSON.parse(text);
+    const facts = javaScriptWorkerStaticAnalysisSchema.parse(value);
+    const remaining = this.#remainingTotalResultBudget();
+    const retainedBytes = bytes * 6;
+    this.#parentCapacityExhausted = retainedBytes > remaining;
+    this.#estimatedRetainedBytes += retainedBytes;
+    this.#retainedStaticBytes += retainedBytes;
+    const expandedBytes = estimateJavaScriptStaticApplicationProjection(
+      facts,
+      bytes,
+      sourcePath,
+    );
+    if (expandedBytes <= this.#remainingResultBudget())
+      this.#estimatedRetainedBytes += expandedBytes;
+    else
+      this.#applicationProjectionFailure = new AnalysisResourceConstraintError(
+        OPERATION,
+        "memory",
+        `Expanded application relationships for ${sourcePath} exceed the parent's result budget; complete static facts were retained on the file node`,
+        {
+          parent_result_budget_bytes: this.#resultBudgetBytes,
+          application_projection_required_bytes: expandedBytes,
+        },
+      );
+    return facts;
+  }
+
+  #limits() {
+    return {
+      worker_old_space_mb: this.limits.heapMb,
+      ...(this.#heapLimitBytes === 0
+        ? {}
+        : { worker_heap_limit_bytes: this.#heapLimitBytes }),
+      worker_timeout_ms: this.limits.timeoutMs,
+    };
+  }
+  #remainingResultBudget(): number {
+    // Future sources need their compact observations before current modules
+    // consume capacity with expanded relationships. A final or sole source
+    // can use the unused reserve as well.
+    const staticReserve =
+      this.#sourcesRemaining !== undefined && this.#sourcesRemaining > 0
+        ? Math.max(
+            0,
+            Math.floor((this.#resultBudgetBytes * 4) / 5) -
+              this.#retainedStaticBytes,
+          )
+        : 0;
+    return Math.max(0, this.#remainingTotalResultBudget() - staticReserve);
+  }
+  #remainingTotalResultBudget(): number {
+    return Math.max(
+      0,
+      Math.min(
+        this.#resultBudgetBytes - this.#estimatedRetainedBytes,
+        getHeapStatistics().heap_size_limit -
+          process.memoryUsage().heapUsed -
+          24 * JAVASCRIPT_ANALYSIS_TRANSFER_RECORD_BYTES,
+      ),
+    );
+  }
+  #captured() {
+    const snapshot = this.#supervisor?.snapshot();
+    return {
+      stdout: "",
+      stderr: snapshot?.stderr.text ?? "",
+      truncated: snapshot?.diagnosticTruncated ?? false,
+      stderr_bytes: snapshot?.stderr.observedBytes ?? 0,
+      exit_code: snapshot?.exitCode ?? null,
+      signal: snapshot?.signal ?? null,
+    };
+  }
+  #failure(
+    cause: unknown,
+    path: string,
+    deadline: ProviderStartupDeadline | undefined,
+  ): AnalysisError {
+    if (deadline?.interruption === "cancelled")
+      return new AnalysisCancelledError(OPERATION, {
+        capturedOutput: this.#captured(),
+      });
+    if (deadline?.interruption === "timeout")
+      return new AnalysisTimeoutError(OPERATION, this.limits.timeoutMs, {
+        capturedOutput: this.#captured(),
+      });
+    if (cause instanceof AnalysisError) return cause;
+    if (
+      cause instanceof z.ZodError ||
+      cause instanceof TypeError ||
+      cause instanceof SyntaxError
+    )
+      return new AnalysisOutputError(
+        OPERATION,
+        `${path} during ${this.#phase}: ${message(cause)}`,
+        { cause, capturedOutput: this.#captured() },
+      );
+    return cause instanceof PrivateRuntimeRootUnavailableError
+      ? new AnalysisCapabilityUnavailableError(
+          PROVIDER,
+          OPERATION,
+          cause.message,
+          { cause },
+        )
+      : new ProviderAdapterError(PROVIDER, OPERATION, {
+          cause,
+          capturedOutput: this.#captured(),
+          diagnostics: {
+            source_path: path,
+            phase: this.#phase,
+            message: message(cause),
+          },
+        });
+  }
+  #cleanupError(
+    reason: string,
+    original: AnalysisError | undefined = this.#lastFailure,
+  ): ProviderCleanupError {
+    return new ProviderCleanupError(
+      PROVIDER,
+      [this.#runId, ...(this.#root === undefined ? [] : [this.#root.path])],
+      {
+        reason,
+        worker_pid: this.#supervisor?.launch.process.pid ?? null,
+        ...(original === undefined
+          ? {}
+          : {
+              execution_failure: {
+                tag: original._tag,
+                message: original.message,
+                captured_output: {
+                  stdout: original.capturedOutput?.stdout ?? "",
+                  stderr: original.capturedOutput?.stderr ?? "",
+                  truncated: original.capturedOutput?.truncated ?? false,
+                },
+              },
+            }),
+      },
+      {
+        operation: OPERATION,
+        ...(original === undefined ? {} : { cause: original }),
+      },
+    );
+  }
+  async #stop(
+    original: AnalysisError | undefined = this.#lastFailure,
+  ): Promise<ProviderCleanupError | undefined> {
+    if (this.#supervisor !== undefined) {
+      const supervisor = this.#supervisor;
+      const stopped = await supervisor.stop();
+      if (stopped.status === "incomplete") {
+        pendingCleanup.add(this);
+        return this.#cleanupError(stopped.reason, original);
+      }
+      supervisor.launch.process.stdout?.off("data", this.#onStdout);
+      supervisor.dispose();
+      this.#supervisor = undefined;
+    }
+    this.#ready = false;
+    this.#frames = [];
+    this.#pending = "";
+    this.#decoder = new StringDecoder("utf8");
+    this.#protocolFailure = undefined;
+    return undefined;
+  }
+}
+
+const message = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause);