space-data-module-sdk 0.8.22 → 0.8.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.8.22",
+  "version": "0.8.24",
   "license": "Apache-2.0",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",

package/src/compiler/compileModule.js

@@ -714,160 +714,159 @@ async function compileWithEmception(options = {}) {
     invokeSource,
     exportedSymbols,
     outputPath,
+    tempDir,
     compileOptions,
   } = options;
-  const tempDir = await mkdtemp(
-    path.join(os.tmpdir(), "space-data-module-sdk-compile-"),
-  );
   const resolvedOutputPath = path.resolve(
     outputPath ?? path.join(tempDir, "module.wasm"),
   );
 
-  try {
-    return await runWithEmceptionLock(async (emception) => {
-      const workDir = "/working/space-data-module-sdk-compile";
-      const runtimeIncludeDir = path.posix.join(workDir, "flatbuffers-runtime");
-      const sourcePath = path.posix.join(workDir, `module.${sourceExtension}`);
-      const manifestSourcePath = path.posix.join(workDir, "plugin-manifest-exports.cpp");
-      const invokeHeaderPath = path.posix.join(workDir, "space_data_module_invoke.h");
-      const invokeSourcePath = path.posix.join(workDir, "plugin-invoke-bridge.cpp");
-      const sourceObjectPath = path.posix.join(workDir, "module.o");
-      const linkObjectPath = path.posix.join(workDir, "module-link.o");
-      const manifestObjectPath = path.posix.join(workDir, "plugin-manifest-exports.o");
-      const invokeObjectPath = path.posix.join(workDir, "plugin-invoke-bridge.o");
-      const wasmOutputPath = path.posix.join(workDir, "module.wasm");
-
-      const { runtimeHeaders, schemaHeaders } = await getInvokeCppSupportFiles();
-      const args = buildCompilerArgs(exportedSymbols, compileOptions);
+  return runWithEmceptionLock(async (emception) => {
+    const workDir = "/working/space-data-module-sdk-compile";
+    const runtimeIncludeDir = path.posix.join(workDir, "flatbuffers-runtime");
+    const sourcePath = path.posix.join(workDir, `module.${sourceExtension}`);
+    const manifestSourcePath = path.posix.join(workDir, "plugin-manifest-exports.cpp");
+    const invokeHeaderPath = path.posix.join(workDir, "space_data_module_invoke.h");
+    const invokeSourcePath = path.posix.join(workDir, "plugin-invoke-bridge.cpp");
+    const sourceObjectPath = path.posix.join(workDir, "module.o");
+    const linkObjectPath = path.posix.join(workDir, "module-link.o");
+    const manifestObjectPath = path.posix.join(workDir, "plugin-manifest-exports.o");
+    const invokeObjectPath = path.posix.join(workDir, "plugin-invoke-bridge.o");
+    const wasmOutputPath = path.posix.join(workDir, "module.wasm");
 
-      try {
-        emception.FS.mkdirTree(workDir);
-        await writeFilesToEmception(emception, runtimeIncludeDir, runtimeHeaders);
-        await writeFilesToEmception(emception, workDir, schemaHeaders);
-        emception.writeFile(sourcePath, sourceCode);
-        emception.writeFile(manifestSourcePath, manifestSource);
-        emception.writeFile(invokeHeaderPath, invokeHeaderSource);
-        emception.writeFile(invokeSourcePath, invokeSource);
-
-        const commands = [
-          [
-            sourceCompilerCommand,
-            "-c",
-            sourcePath,
-            `-I${workDir}`,
-            `-I${runtimeIncludeDir}`,
-            ...buildSourceCompilerArgs(compileOptions),
-            "-o",
-            sourceObjectPath,
-          ],
-        ];
-
-        for (const command of commands) {
-          const result = emception.run(command.join(" "));
-          if (result.returncode !== 0) {
-            throw new Error(
-              `Compilation failed with ${command[0]} (emception): ${result.stderr || result.stdout}`,
-            );
-          }
-        }
-
-        const sourceObjectBytes = new Uint8Array(emception.readFile(sourceObjectPath));
-        const guestLink = deriveGuestLinkRenameArgs({
-          objectBytes: sourceObjectBytes,
-          pluginId: manifest?.pluginId,
-          methodIds: Array.isArray(manifest?.methods)
-            ? manifest.methods.map((method) => String(method?.methodId ?? ""))
-            : [],
-        });
+    const { runtimeHeaders, schemaHeaders } = await getInvokeCppSupportFiles();
+    const args = buildCompilerArgs(exportedSymbols, compileOptions);
 
-        const linkCompileCommand = [
+    try {
+      emception.FS.mkdirTree(workDir);
+      await writeFilesToEmception(emception, runtimeIncludeDir, runtimeHeaders);
+      await writeFilesToEmception(emception, workDir, schemaHeaders);
+      emception.writeFile(sourcePath, sourceCode);
+      emception.writeFile(manifestSourcePath, manifestSource);
+      emception.writeFile(invokeHeaderPath, invokeHeaderSource);
+      emception.writeFile(invokeSourcePath, invokeSource);
+
+      const commands = [
+        [
           sourceCompilerCommand,
           "-c",
           sourcePath,
           `-I${workDir}`,
           `-I${runtimeIncludeDir}`,
-          ...guestLink.renameArgs,
           ...buildSourceCompilerArgs(compileOptions),
           "-o",
-          linkObjectPath,
-        ];
-        const linkCompileResult = emception.run(linkCompileCommand.join(" "));
-        if (linkCompileResult.returncode !== 0) {
+          sourceObjectPath,
+        ],
+      ];
+
+      for (const command of commands) {
+        const result = emception.run(command.join(" "));
+        if (result.returncode !== 0) {
           throw new Error(
-            `Compilation failed with ${linkCompileCommand[0]} (emception): ${linkCompileResult.stderr || linkCompileResult.stdout}`,
+            `Compilation failed with ${command[0]} (emception): ${result.stderr || result.stdout}`,
           );
         }
+      }
 
-        const remainingCommands = [
-          [
-            "em++",
-            "-c",
-            manifestSourcePath,
-            "-std=c++17",
-            `-I${workDir}`,
-            `-I${runtimeIncludeDir}`,
-            "-o",
-            manifestObjectPath,
-          ],
-          [
-            "em++",
-            "-c",
-            invokeSourcePath,
-            "-std=c++17",
-            `-I${workDir}`,
-            `-I${runtimeIncludeDir}`,
-            "-o",
-            invokeObjectPath,
-          ],
-          [
-            "em++",
-            sourceObjectPath,
-            manifestObjectPath,
-            invokeObjectPath,
-            ...args,
-            "-o",
-            wasmOutputPath,
-          ],
-        ];
-        for (const command of remainingCommands) {
-          const result = emception.run(command.join(" "));
-          if (result.returncode !== 0) {
-            throw new Error(
-              `Compilation failed with ${command[0]} (emception): ${result.stderr || result.stdout}`,
-            );
-          }
-        }
+      const sourceObjectBytes = new Uint8Array(emception.readFile(sourceObjectPath));
+      const guestLink = deriveGuestLinkRenameArgs({
+        objectBytes: sourceObjectBytes,
+        pluginId: manifest?.pluginId,
+        methodIds: Array.isArray(manifest?.methods)
+          ? manifest.methods.map((method) => String(method?.methodId ?? ""))
+          : [],
+      });
+
+      const linkCompileCommand = [
+        sourceCompilerCommand,
+        "-c",
+        sourcePath,
+        `-I${workDir}`,
+        `-I${runtimeIncludeDir}`,
+        ...guestLink.renameArgs,
+        ...buildSourceCompilerArgs(compileOptions),
+        "-o",
+        linkObjectPath,
+      ];
+      const linkCompileResult = emception.run(linkCompileCommand.join(" "));
+      if (linkCompileResult.returncode !== 0) {
+        throw new Error(
+          `Compilation failed with ${linkCompileCommand[0]} (emception): ${linkCompileResult.stderr || linkCompileResult.stdout}`,
+        );
+      }
 
-        const wasmBytes = new Uint8Array(emception.readFile(wasmOutputPath));
-        const linkObjectBytes = new Uint8Array(emception.readFile(linkObjectPath));
-        await writeFile(resolvedOutputPath, wasmBytes);
-        return {
-          wasmBytes,
-          outputPath: resolvedOutputPath,
-          tempDir,
-          guestLink: {
-            format: "wasm-object",
-            language,
-            symbolPrefix: guestLink.prefix,
-            methodSymbols: guestLink.methodSymbols,
-            threadModel:
-              compileOptions.threadModel ?? ModuleThreadModel.SINGLE_THREAD,
-            capabilities: compileOptions.guestLinkCapabilities,
-            objectBytes: linkObjectBytes,
-          },
-        };
-      } finally {
-        try {
-          removeEmceptionDirectory(emception, workDir);
-        } catch {
-          // Best-effort cleanup only; the shared emception instance remains usable.
+      // The embedded manifest and the invoke bridge get the module source's
+      // own optimization flags. Without them both objects built at -O0 and
+      // every payload byte crossing the bridge (the std::vector copies of
+      // each request and response) cost hundreds of interpreted wasm
+      // instructions. The wasi path already compiles them this way.
+      const remainingCommands = [
+        [
+          "em++",
+          "-c",
+          manifestSourcePath,
+          "-std=c++17",
+          `-I${workDir}`,
+          `-I${runtimeIncludeDir}`,
+          ...buildSourceCompilerArgs(compileOptions),
+          "-o",
+          manifestObjectPath,
+        ],
+        [
+          "em++",
+          "-c",
+          invokeSourcePath,
+          "-std=c++17",
+          `-I${workDir}`,
+          `-I${runtimeIncludeDir}`,
+          ...buildSourceCompilerArgs(compileOptions),
+          "-o",
+          invokeObjectPath,
+        ],
+        [
+          "em++",
+          sourceObjectPath,
+          manifestObjectPath,
+          invokeObjectPath,
+          ...args,
+          "-o",
+          wasmOutputPath,
+        ],
+      ];
+      for (const command of remainingCommands) {
+        const result = emception.run(command.join(" "));
+        if (result.returncode !== 0) {
+          throw new Error(
+            `Compilation failed with ${command[0]} (emception): ${result.stderr || result.stdout}`,
+          );
         }
       }
-    });
-  } catch (error) {
-    await rm(tempDir, { recursive: true, force: true });
-    throw error;
-  }
+
+      const wasmBytes = new Uint8Array(emception.readFile(wasmOutputPath));
+      const linkObjectBytes = new Uint8Array(emception.readFile(linkObjectPath));
+      await writeFile(resolvedOutputPath, wasmBytes);
+      return {
+        wasmBytes,
+        outputPath: resolvedOutputPath,
+        guestLink: {
+          format: "wasm-object",
+          language,
+          symbolPrefix: guestLink.prefix,
+          methodSymbols: guestLink.methodSymbols,
+          threadModel:
+            compileOptions.threadModel ?? ModuleThreadModel.SINGLE_THREAD,
+          capabilities: compileOptions.guestLinkCapabilities,
+          objectBytes: linkObjectBytes,
+        },
+      };
+    } finally {
+      try {
+        removeEmceptionDirectory(emception, workDir);
+      } catch {
+        // Best-effort cleanup only; the shared emception instance remains usable.
+      }
+    }
+  });
 }
 
 async function ensureSystemCompilerAvailable(command) {
@@ -911,11 +910,9 @@ async function compileWithSystemEmscripten(options = {}) {
     invokeSource,
     exportedSymbols,
     outputPath,
+    tempDir,
     compileOptions,
   } = options;
-  const tempDir = await mkdtemp(
-    path.join(os.tmpdir(), "space-data-module-sdk-compile-"),
-  );
   const resolvedOutputPath = path.resolve(
     outputPath ?? path.join(tempDir, "module.wasm"),
   );
@@ -930,99 +927,95 @@ async function compileWithSystemEmscripten(options = {}) {
   const invokeObjectPath = path.join(tempDir, "plugin-invoke-bridge.o");
   const wasmOutputPath = path.join(tempDir, "module.wasm");
 
-  try {
-    await ensureSystemCompilerAvailable(sourceCompilerCommand);
-    await ensureSystemCompilerAvailable("em++");
-    const { runtimeHeaders, schemaHeaders } = await getInvokeCppSupportFiles();
-    const args = buildCompilerArgs(exportedSymbols, compileOptions);
-    await writeFilesToDirectory(runtimeIncludeDir, runtimeHeaders);
-    await writeFilesToDirectory(tempDir, schemaHeaders);
-    await writeFile(sourcePath, sourceCode);
-    await writeFile(manifestSourcePath, manifestSource);
-    await writeFile(invokeHeaderPath, invokeHeaderSource);
-    await writeFile(invokeSourcePath, invokeSource);
-
-    const sourceCompileArgs = [
-      "-c",
-      sourcePath,
-      `-I${tempDir}`,
-      `-I${runtimeIncludeDir}`,
-      ...buildSourceCompilerArgs(compileOptions),
-      "-o",
-      sourceObjectPath,
-    ];
-    await runSystemCompiler(sourceCompilerCommand, sourceCompileArgs);
-
-    const sourceObjectBytes = new Uint8Array(await readFile(sourceObjectPath));
-    const guestLink = deriveGuestLinkRenameArgs({
-      objectBytes: sourceObjectBytes,
-      pluginId: manifest?.pluginId,
-      methodIds: Array.isArray(manifest?.methods)
-        ? manifest.methods.map((method) => String(method?.methodId ?? ""))
-        : [],
-    });
+  await ensureSystemCompilerAvailable(sourceCompilerCommand);
+  await ensureSystemCompilerAvailable("em++");
+  const { runtimeHeaders, schemaHeaders } = await getInvokeCppSupportFiles();
+  const args = buildCompilerArgs(exportedSymbols, compileOptions);
+  await writeFilesToDirectory(runtimeIncludeDir, runtimeHeaders);
+  await writeFilesToDirectory(tempDir, schemaHeaders);
+  await writeFile(sourcePath, sourceCode);
+  await writeFile(manifestSourcePath, manifestSource);
+  await writeFile(invokeHeaderPath, invokeHeaderSource);
+  await writeFile(invokeSourcePath, invokeSource);
+
+  const sourceCompileArgs = [
+    "-c",
+    sourcePath,
+    `-I${tempDir}`,
+    `-I${runtimeIncludeDir}`,
+    ...buildSourceCompilerArgs(compileOptions),
+    "-o",
+    sourceObjectPath,
+  ];
+  await runSystemCompiler(sourceCompilerCommand, sourceCompileArgs);
+
+  const sourceObjectBytes = new Uint8Array(await readFile(sourceObjectPath));
+  const guestLink = deriveGuestLinkRenameArgs({
+    objectBytes: sourceObjectBytes,
+    pluginId: manifest?.pluginId,
+    methodIds: Array.isArray(manifest?.methods)
+      ? manifest.methods.map((method) => String(method?.methodId ?? ""))
+      : [],
+  });
 
-    const linkCompileArgs = [
-      "-c",
-      sourcePath,
-      `-I${tempDir}`,
-      `-I${runtimeIncludeDir}`,
-      ...guestLink.renameArgs,
-      ...buildSourceCompilerArgs(compileOptions),
-      "-o",
-      linkObjectPath,
-    ];
-    await runSystemCompiler(sourceCompilerCommand, linkCompileArgs);
-    await runSystemCompiler("em++", [
-      "-c",
-      manifestSourcePath,
-      "-std=c++17",
-      `-I${tempDir}`,
-      `-I${runtimeIncludeDir}`,
-      ...(usesPthreadCompileFlags(compileOptions) ? ["-pthread"] : []),
-      "-o",
-      manifestObjectPath,
-    ]);
-    await runSystemCompiler("em++", [
-      "-c",
-      invokeSourcePath,
-      "-std=c++17",
-      `-I${tempDir}`,
-      `-I${runtimeIncludeDir}`,
-      ...(usesPthreadCompileFlags(compileOptions) ? ["-pthread"] : []),
-      "-o",
-      invokeObjectPath,
-    ]);
-    await runSystemCompiler("em++", [
-      sourceObjectPath,
-      manifestObjectPath,
-      invokeObjectPath,
-      ...args,
-      "-o",
-      wasmOutputPath,
-    ]);
+  const linkCompileArgs = [
+    "-c",
+    sourcePath,
+    `-I${tempDir}`,
+    `-I${runtimeIncludeDir}`,
+    ...guestLink.renameArgs,
+    ...buildSourceCompilerArgs(compileOptions),
+    "-o",
+    linkObjectPath,
+  ];
+  await runSystemCompiler(sourceCompilerCommand, linkCompileArgs);
+  // Same optimization flags as the module source (see compileWithEmception).
+  // buildSourceCompilerArgs carries -pthread whenever usesPthreadCompileFlags.
+  await runSystemCompiler("em++", [
+    "-c",
+    manifestSourcePath,
+    "-std=c++17",
+    `-I${tempDir}`,
+    `-I${runtimeIncludeDir}`,
+    ...buildSourceCompilerArgs(compileOptions),
+    "-o",
+    manifestObjectPath,
+  ]);
+  await runSystemCompiler("em++", [
+    "-c",
+    invokeSourcePath,
+    "-std=c++17",
+    `-I${tempDir}`,
+    `-I${runtimeIncludeDir}`,
+    ...buildSourceCompilerArgs(compileOptions),
+    "-o",
+    invokeObjectPath,
+  ]);
+  await runSystemCompiler("em++", [
+    sourceObjectPath,
+    manifestObjectPath,
+    invokeObjectPath,
+    ...args,
+    "-o",
+    wasmOutputPath,
+  ]);
 
-    const wasmBytes = new Uint8Array(await readFile(wasmOutputPath));
-    const linkObjectBytes = new Uint8Array(await readFile(linkObjectPath));
-    await writeFile(resolvedOutputPath, wasmBytes);
-    return {
-      wasmBytes,
-      outputPath: resolvedOutputPath,
-      tempDir,
-      guestLink: {
-        format: "wasm-object",
-        language,
-        symbolPrefix: guestLink.prefix,
-        methodSymbols: guestLink.methodSymbols,
-        threadModel: compileOptions.threadModel,
-        capabilities: compileOptions.guestLinkCapabilities,
-        objectBytes: linkObjectBytes,
-      },
-    };
-  } catch (error) {
-    await rm(tempDir, { recursive: true, force: true });
-    throw error;
-  }
+  const wasmBytes = new Uint8Array(await readFile(wasmOutputPath));
+  const linkObjectBytes = new Uint8Array(await readFile(linkObjectPath));
+  await writeFile(resolvedOutputPath, wasmBytes);
+  return {
+    wasmBytes,
+    outputPath: resolvedOutputPath,
+    guestLink: {
+      format: "wasm-object",
+      language,
+      symbolPrefix: guestLink.prefix,
+      methodSymbols: guestLink.methodSymbols,
+      threadModel: compileOptions.threadModel,
+      capabilities: compileOptions.guestLinkCapabilities,
+      objectBytes: linkObjectBytes,
+    },
+  };
 }
 
 async function runWasiCompiler(command, args, options = {}) {
@@ -1061,6 +1054,7 @@ async function compileWithWasiThreads(options = {}) {
     invokeSource,
     exportedSymbols,
     outputPath,
+    tempDir,
     compileOptions,
   } = options;
   const toolchain = resolveWasiThreadsToolchain();
@@ -1068,9 +1062,6 @@ async function compileWithWasiThreads(options = {}) {
   const sourceDriver = isCpp ? toolchain.clangxx : toolchain.clang;
   const cppDriver = toolchain.clangxx;
 
-  const tempDir = await mkdtemp(
-    path.join(os.tmpdir(), "space-data-module-sdk-compile-"),
-  );
   const resolvedOutputPath = path.resolve(
     outputPath ?? path.join(tempDir, "module.wasm"),
   );
@@ -1085,98 +1076,92 @@ async function compileWithWasiThreads(options = {}) {
   const invokeObjectPath = path.join(tempDir, "plugin-invoke-bridge.o");
   const wasmOutputPath = path.join(tempDir, "module.wasm");
 
-  try {
-    const { runtimeHeaders, schemaHeaders } = await getInvokeCppSupportFiles();
-    const linkArgs = buildCompilerArgs(exportedSymbols, compileOptions);
-    await writeFilesToDirectory(runtimeIncludeDir, runtimeHeaders);
-    await writeFilesToDirectory(tempDir, schemaHeaders);
-    await writeFile(sourcePath, sourceCode);
-    await writeFile(manifestSourcePath, manifestSource);
-    await writeFile(invokeHeaderPath, invokeHeaderSource);
-    await writeFile(invokeSourcePath, invokeSource);
-
-    const includeArgs = [`-I${tempDir}`, `-I${runtimeIncludeDir}`];
-    const sourceCompilerArgs = buildSourceCompilerArgs(compileOptions);
-
-    await runWasiCompiler(sourceDriver, [
-      ...toolchain.toolchainArgs,
-      "-c",
-      sourcePath,
-      ...includeArgs,
-      ...(isCpp ? ["-std=c++17"] : []),
-      ...sourceCompilerArgs,
-      "-o",
-      sourceObjectPath,
-    ]);
+  const { runtimeHeaders, schemaHeaders } = await getInvokeCppSupportFiles();
+  const linkArgs = buildCompilerArgs(exportedSymbols, compileOptions);
+  await writeFilesToDirectory(runtimeIncludeDir, runtimeHeaders);
+  await writeFilesToDirectory(tempDir, schemaHeaders);
+  await writeFile(sourcePath, sourceCode);
+  await writeFile(manifestSourcePath, manifestSource);
+  await writeFile(invokeHeaderPath, invokeHeaderSource);
+  await writeFile(invokeSourcePath, invokeSource);
+
+  const includeArgs = [`-I${tempDir}`, `-I${runtimeIncludeDir}`];
+  const sourceCompilerArgs = buildSourceCompilerArgs(compileOptions);
+
+  await runWasiCompiler(sourceDriver, [
+    ...toolchain.toolchainArgs,
+    "-c",
+    sourcePath,
+    ...includeArgs,
+    ...(isCpp ? ["-std=c++17"] : []),
+    ...sourceCompilerArgs,
+    "-o",
+    sourceObjectPath,
+  ]);
 
-    const sourceObjectBytes = new Uint8Array(await readFile(sourceObjectPath));
-    const guestLink = deriveGuestLinkRenameArgs({
-      objectBytes: sourceObjectBytes,
-      pluginId: manifest?.pluginId,
-      methodIds: Array.isArray(manifest?.methods)
-        ? manifest.methods.map((method) => String(method?.methodId ?? ""))
-        : [],
-    });
+  const sourceObjectBytes = new Uint8Array(await readFile(sourceObjectPath));
+  const guestLink = deriveGuestLinkRenameArgs({
+    objectBytes: sourceObjectBytes,
+    pluginId: manifest?.pluginId,
+    methodIds: Array.isArray(manifest?.methods)
+      ? manifest.methods.map((method) => String(method?.methodId ?? ""))
+      : [],
+  });
 
-    await runWasiCompiler(sourceDriver, [
+  await runWasiCompiler(sourceDriver, [
+    ...toolchain.toolchainArgs,
+    "-c",
+    sourcePath,
+    ...includeArgs,
+    ...(isCpp ? ["-std=c++17"] : []),
+    ...guestLink.renameArgs,
+    ...sourceCompilerArgs,
+    "-o",
+    linkObjectPath,
+  ]);
+
+  for (const [srcPath, objPath] of [
+    [manifestSourcePath, manifestObjectPath],
+    [invokeSourcePath, invokeObjectPath],
+  ]) {
+    await runWasiCompiler(cppDriver, [
       ...toolchain.toolchainArgs,
       "-c",
-      sourcePath,
+      srcPath,
+      "-std=c++17",
       ...includeArgs,
-      ...(isCpp ? ["-std=c++17"] : []),
-      ...guestLink.renameArgs,
       ...sourceCompilerArgs,
       "-o",
-      linkObjectPath,
+      objPath,
     ]);
+  }
 
-    for (const [srcPath, objPath] of [
-      [manifestSourcePath, manifestObjectPath],
-      [invokeSourcePath, invokeObjectPath],
-    ]) {
-      await runWasiCompiler(cppDriver, [
-        ...toolchain.toolchainArgs,
-        "-c",
-        srcPath,
-        "-std=c++17",
-        ...includeArgs,
-        ...sourceCompilerArgs,
-        "-o",
-        objPath,
-      ]);
-    }
-
-    await runWasiCompiler(cppDriver, [
-      ...toolchain.toolchainArgs,
-      sourceObjectPath,
-      manifestObjectPath,
-      invokeObjectPath,
-      ...linkArgs,
-      "-o",
-      wasmOutputPath,
-    ]);
+  await runWasiCompiler(cppDriver, [
+    ...toolchain.toolchainArgs,
+    sourceObjectPath,
+    manifestObjectPath,
+    invokeObjectPath,
+    ...linkArgs,
+    "-o",
+    wasmOutputPath,
+  ]);
 
-    const wasmBytes = new Uint8Array(await readFile(wasmOutputPath));
-    const linkObjectBytes = new Uint8Array(await readFile(linkObjectPath));
-    await writeFile(resolvedOutputPath, wasmBytes);
-    return {
-      wasmBytes,
-      outputPath: resolvedOutputPath,
-      tempDir,
-      guestLink: {
-        format: "wasm-object",
-        language,
-        symbolPrefix: guestLink.prefix,
-        methodSymbols: guestLink.methodSymbols,
-        threadModel: compileOptions.threadModel,
-        capabilities: compileOptions.guestLinkCapabilities,
-        objectBytes: linkObjectBytes,
-      },
-    };
-  } catch (error) {
-    await rm(tempDir, { recursive: true, force: true });
-    throw error;
-  }
+  const wasmBytes = new Uint8Array(await readFile(wasmOutputPath));
+  const linkObjectBytes = new Uint8Array(await readFile(linkObjectPath));
+  await writeFile(resolvedOutputPath, wasmBytes);
+  return {
+    wasmBytes,
+    outputPath: resolvedOutputPath,
+    guestLink: {
+      format: "wasm-object",
+      language,
+      symbolPrefix: guestLink.prefix,
+      methodSymbols: guestLink.methodSymbols,
+      threadModel: compileOptions.threadModel,
+      capabilities: compileOptions.guestLinkCapabilities,
+      objectBytes: linkObjectBytes,
+    },
+  };
 }
 
 export async function compileModuleFromSource(options = {}) {
@@ -1234,9 +1219,6 @@ export async function compileModuleFromSource(options = {}) {
     ),
   ];
 
-  let wasmBytes;
-  let resolvedOutputPath = null;
-  let tempDir = null;
   const threadModel = resolveThreadModel({
     manifest,
     threadModel: options.threadModel,
@@ -1266,72 +1248,92 @@ export async function compileModuleFromSource(options = {}) {
     : useSystemEmscripten
       ? compileWithSystemEmscripten
       : compileWithEmception;
-  const result = await compileFunction({
-    manifest,
-    language: compiler.language,
-    sourceCompilerCommand: compiler.command,
-    sourceExtension: compiler.extension,
-    sourceCode,
-    manifestSource,
-    invokeHeaderSource,
-    invokeSource,
-    exportedSymbols,
-    outputPath: options.outputPath,
-    compileOptions,
-  });
-  wasmBytes = appendWasmCustomSection(
-    result.wasmBytes,
-    SDS_MANIFEST_SECTION_NAME,
-    encodePluginManifest(manifest),
+  // Scratch for the toolchain and, without an explicit outputPath, the home of
+  // the emitted artifact. Removed in finally on success, failure and throw.
+  // `keepTempDir: true` hands it to the caller on success instead
+  // (result.tempDir, freed by cleanupCompilation); a failed compile never
+  // hands anything off, so its dir is always removed.
+  const keepTempDir = options.keepTempDir === true;
+  const tempDir = await mkdtemp(
+    path.join(os.tmpdir(), "space-data-module-sdk-compile-"),
   );
-  resolvedOutputPath = result.outputPath;
-  await writeFile(resolvedOutputPath, wasmBytes);
-  tempDir = result.tempDir;
-
-  // Enforce the isomorphic-pthreads guardrail on the EMITTED artifact: a build
-  // that claims the pthreads thread model but did not emit a shared-memory /
-  // atomics wasm must FAIL the compile here rather than ship. See
-  // docs/isomorphic-pthreads.md.
-  let threadFeatures = null;
-  if (threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS) {
-    threadFeatures = assertPthreadArtifact(wasmBytes, {
-      source: resolvedOutputPath,
-    });
-  } else if (threadModel === ModuleThreadModel.WASI_SEQUENTIAL) {
-    // Mirror guard. The target is passed so that SDN_WASI_TARGET cannot be used
-    // to quietly build a plain wasm32-wasip1 object under the sequential model:
-    // it is a concurrency exemption, not a toolchain exemption.
-    threadFeatures = assertSequentialArtifact(wasmBytes, {
-      source: resolvedOutputPath,
-      target: resolveWasiThreadsToolchain().target,
+  let handedOff = false;
+  try {
+    const result = await compileFunction({
+      manifest,
+      language: compiler.language,
+      sourceCompilerCommand: compiler.command,
+      sourceExtension: compiler.extension,
+      sourceCode,
+      manifestSource,
+      invokeHeaderSource,
+      invokeSource,
+      exportedSymbols,
+      outputPath: options.outputPath,
+      tempDir,
+      compileOptions,
     });
-  }
+    const wasmBytes = appendWasmCustomSection(
+      result.wasmBytes,
+      SDS_MANIFEST_SECTION_NAME,
+      encodePluginManifest(manifest),
+    );
+    const resolvedOutputPath = result.outputPath;
+    await writeFile(resolvedOutputPath, wasmBytes);
 
-  // Validate the compiled artifact
-  const report = await validateArtifactWithStandards({
-    manifest,
-    wasmPath: resolvedOutputPath,
-    ...standardsOptions,
-  });
+    // Enforce the isomorphic-pthreads guardrail on the EMITTED artifact: a build
+    // that claims the pthreads thread model but did not emit a shared-memory /
+    // atomics wasm must FAIL the compile here rather than ship. See
+    // docs/isomorphic-pthreads.md.
+    let threadFeatures = null;
+    if (threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS) {
+      threadFeatures = assertPthreadArtifact(wasmBytes, {
+        source: resolvedOutputPath,
+      });
+    } else if (threadModel === ModuleThreadModel.WASI_SEQUENTIAL) {
+      // Mirror guard. The target is passed so that SDN_WASI_TARGET cannot be used
+      // to quietly build a plain wasm32-wasip1 object under the sequential model:
+      // it is a concurrency exemption, not a toolchain exemption.
+      threadFeatures = assertSequentialArtifact(wasmBytes, {
+        source: resolvedOutputPath,
+        target: resolveWasiThreadsToolchain().target,
+      });
+    }
 
-  return {
-    compiler: useWasiThreads
-      ? threadModel === ModuleThreadModel.WASI_SEQUENTIAL
-        ? "wasm32-wasi-clang++ (wasi-sequential)"
-        : "wasm32-wasi-clang++ (wasi-threads)"
-      : useSystemEmscripten
-        ? "em++ (system emscripten pthreads)"
-        : "em++ (emception)",
-    language: compiler.language,
-    threadModel,
-    outputPath: resolvedOutputPath,
-    tempDir,
-    wasmBytes,
-    guestLink: result.guestLink,
-    manifestWarnings: warnings,
-    threadFeatures,
-    report,
-  };
+    // Validate the compiled artifact
+    const report = await validateArtifactWithStandards({
+      manifest,
+      wasmPath: resolvedOutputPath,
+      ...standardsOptions,
+    });
+
+    handedOff = keepTempDir;
+    return {
+      compiler: useWasiThreads
+        ? threadModel === ModuleThreadModel.WASI_SEQUENTIAL
+          ? "wasm32-wasi-clang++ (wasi-sequential)"
+          : "wasm32-wasi-clang++ (wasi-threads)"
+        : useSystemEmscripten
+          ? "em++ (system emscripten pthreads)"
+          : "em++ (emception)",
+      language: compiler.language,
+      threadModel,
+      // Without an explicit outputPath the artifact lived in tempDir, which is
+      // gone unless the caller kept it.
+      outputPath:
+        options.outputPath != null || keepTempDir ? resolvedOutputPath : null,
+      tempDir: keepTempDir ? tempDir : null,
+      wasmBytes,
+      guestLink: result.guestLink,
+      manifestWarnings: warnings,
+      threadFeatures,
+      report,
+    };
+  } finally {
+    if (!handedOff) {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  }
 }
 
 export async function cleanupCompilation(result) {

package/src/compiler/emceptionNode.js

@@ -1,17 +1,41 @@
 import os from "node:os";
 import path from "node:path";
-import { cp, readFile, readdir, rm, writeFile } from "node:fs/promises";
-import { readFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import {
+  cp,
+  lstat,
+  mkdtemp,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { constants as fsConstants, createReadStream, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 
 const require = createRequire(import.meta.url);
+// Bump when the patched tree's layout or meaning changes. The patch transform's
+// own source text is part of the cache key as well (see
+// computeEmceptionIdentity), so editing patchEmceptionModuleSource cannot reuse
+// a tree patched by an older transform even if this string is left alone.
 const PATCH_VERSION = "space-data-module-sdk-emception-node-v1";
+const PATCH_KEY_TAG = "node-v1";
 const PATCH_MARKER_FILENAME = ".space-data-module-sdk-emception-patch";
-const EMCEPTION_PATCH_ROOT = path.join(
-  os.tmpdir(),
-  `space-data-module-sdk-emception-node-${process.pid}`,
+// One shared root per (patch, emception build) lives at
+// <tmpdir>/space-data-module-sdk-emception-<tag>-<version>-<fingerprint>-u<uid>.
+// Every process of every consumer run by that user reuses it. Builds happen in a sibling
+// staging dir that is renamed into place only once it is complete.
+const PATCHED_ROOT_PREFIX = "space-data-module-sdk-emception-";
+const STAGING_MARKER = ".staging-";
+const STALE_MARKER = ".stale-";
+const ORPHAN_NAME_PATTERN = new RegExp(
+  `^${PATCHED_ROOT_PREFIX.replaceAll("-", "\\-")}.+\\.(?:staging|stale)-(\\d+)-[A-Za-z0-9]+$`,
 );
+const RENAME_COLLISION_CODES = new Set(["ENOTEMPTY", "EEXIST", "EPERM", "EBUSY"]);
+const MAX_PUBLISH_ATTEMPTS = 4;
 const FILE_URL_FETCH_PATCH_FLAG =
   "__spaceDataModuleSdkFileUrlFetchPatched";
 
@@ -84,90 +108,335 @@ function installNodeRuntimeShims() {
   }
 }
 
-async function patchEmceptionModuleTree(rootDir) {
-  const entries = await readdir(rootDir, { withFileTypes: true });
+// Pure transform of one emception .mjs file. Its source text is hashed into
+// the cache key, so any edit here yields a fresh patched root.
+function patchEmceptionModuleSource(fileName, source) {
+  let patched = source.replaceAll(
+    'scriptDirectory=__dirname+"/"',
+    'scriptDirectory=(new URL(".", import.meta.url)).pathname',
+  );
+
+  if (fileName === "emception.mjs") {
+    patched = patched.replace(
+      "this.#fs = await new FileSystem();",
+      [
+        "this.#fs = await new FileSystem({",
+        "      locateFile: (file, scriptDirectory) => scriptDirectory + file,",
+        '      cache: "/tmp/emception-cache",',
+        "    });",
+      ].join("\n"),
+    );
+    patched = patched.replace(
+      "const config = {",
+      [
+        "const config = {",
+        "      locateFile: (file, scriptDirectory) => scriptDirectory + file,",
+      ].join("\n"),
+    );
+  }
+
+  if (fileName === "FileSystem.mjs") {
+    patched = patched.replace(
+      [
+        "        if (!this.exists(cache)) {",
+        "            this.persist(cache);",
+        "        }",
+        "        await this.pull();",
+      ].join("\n"),
+      [
+        '        if (typeof indexedDB !== "undefined") {',
+        "            if (!this.exists(cache)) {",
+        "                this.persist(cache);",
+        "            }",
+        "            await this.pull();",
+        "        }",
+      ].join("\n"),
+    );
+  }
+
+  return patched;
+}
+
+// Relative POSIX paths of every regular file under rootDir, sorted.
+async function listTreeFiles(rootDir, relativeDir = "") {
+  const entries = await readdir(path.join(rootDir, relativeDir), {
+    withFileTypes: true,
+  });
+  const files = [];
   for (const entry of entries) {
-    const fullPath = path.join(rootDir, entry.name);
+    const relativePath = relativeDir
+      ? path.posix.join(relativeDir, entry.name)
+      : entry.name;
     if (entry.isDirectory()) {
-      await patchEmceptionModuleTree(fullPath);
-      continue;
+      files.push(...(await listTreeFiles(rootDir, relativePath)));
+    } else if (entry.isFile()) {
+      files.push(relativePath);
     }
-    if (!entry.name.endsWith(".mjs")) {
+  }
+  return files.sort();
+}
+
+async function patchEmceptionModuleTree(rootDir, files) {
+  for (const relativePath of files) {
+    if (!relativePath.endsWith(".mjs")) {
       continue;
     }
-
-    let source = await readFile(fullPath, "utf8");
-    source = source.replaceAll(
-      'scriptDirectory=__dirname+"/"',
-      'scriptDirectory=(new URL(".", import.meta.url)).pathname',
+    const fullPath = path.join(rootDir, relativePath);
+    const source = await readFile(fullPath, "utf8");
+    const patched = patchEmceptionModuleSource(
+      path.posix.basename(relativePath),
+      source,
     );
-
-    if (entry.name === "emception.mjs") {
-      source = source.replace(
-        "this.#fs = await new FileSystem();",
-        [
-          "this.#fs = await new FileSystem({",
-          "      locateFile: (file, scriptDirectory) => scriptDirectory + file,",
-          '      cache: "/tmp/emception-cache",',
-          "    });",
-        ].join("\n"),
-      );
-      source = source.replace(
-        "const config = {",
-        [
-          "const config = {",
-          "      locateFile: (file, scriptDirectory) => scriptDirectory + file,",
-        ].join("\n"),
-      );
+    if (patched !== source) {
+      await writeFile(fullPath, patched, "utf8");
     }
+  }
+}
 
-    if (entry.name === "FileSystem.mjs") {
-      source = source.replace(
-        [
-          "        if (!this.exists(cache)) {",
-          "            this.persist(cache);",
-          "        }",
-          "        await this.pull();",
-        ].join("\n"),
-        [
-          '        if (typeof indexedDB !== "undefined") {',
-          "            if (!this.exists(cache)) {",
-          "                this.persist(cache);",
-          "            }",
-          "            await this.pull();",
-          "        }",
-        ].join("\n"),
+async function readEmceptionPackageVersion(sourceRoot) {
+  let directory = sourceRoot;
+  for (;;) {
+    try {
+      const packageJson = JSON.parse(
+        await readFile(path.join(directory, "package.json"), "utf8"),
       );
+      if (packageJson?.name === "sdn-emception") {
+        return String(packageJson.version ?? "unknown");
+      }
+    } catch {
+      // Keep walking up.
     }
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      return "unknown";
+    }
+    directory = parent;
+  }
+}
 
-    await writeFile(fullPath, source, "utf8");
+// The cache key: the patch version, the patch transform, the emception
+// package version, and a sha256 over every source file's path, size and
+// bytes. Two installs with the same version but different bytes never share
+// a root.
+async function computeEmceptionIdentity(sourceRoot) {
+  const version = await readEmceptionPackageVersion(sourceRoot);
+  const files = await listTreeFiles(sourceRoot);
+  const hash = createHash("sha256");
+  hash.update(`${PATCH_VERSION}\0${patchEmceptionModuleSource.toString()}\0`);
+  hash.update(`${version}\0`);
+  for (const relativePath of files) {
+    const fullPath = path.join(sourceRoot, relativePath);
+    const { size } = await stat(fullPath);
+    hash.update(`${relativePath}\0${size}\0`);
+    for await (const chunk of createReadStream(fullPath)) {
+      hash.update(chunk);
+    }
+    hash.update("\0");
   }
+  const fingerprint = hash.digest("hex");
+  const safeVersion = version.replace(/[^A-Za-z0-9._]/g, "_");
+  // Per user: where the tmp dir is shared (Linux /tmp), users never collide.
+  const uid = currentUid();
+  return {
+    version,
+    fingerprint,
+    files,
+    key: `${PATCH_KEY_TAG}-${safeVersion}-${fingerprint.slice(0, 16)}${uid === null ? "" : `-u${uid}`}`,
+  };
 }
 
-async function preparePatchedEmceptionRoot() {
-  if (!patchedEmceptionRootPromise) {
-    patchedEmceptionRootPromise = (async () => {
-      const sourceRoot = path.dirname(require.resolve("sdn-emception"));
-      const markerPath = path.join(EMCEPTION_PATCH_ROOT, PATCH_MARKER_FILENAME);
-      let marker = null;
-      try {
-        marker = await readFile(markerPath, "utf8");
-      } catch {
-        marker = null;
+// The content check on reuse. The marker is written last inside the staging
+// dir, so a published root always has one; this also catches a root whose
+// files were later deleted or truncated (tmp cleaners purge by age).
+async function isPatchedRootValid(rootDir, identity) {
+  // The root is imported as code, so it must be a real directory that this
+  // user owns and nobody else can write. Anything else is never trusted.
+  try {
+    const rootStat = await lstat(rootDir);
+    if (!rootStat.isDirectory()) {
+      return false;
+    }
+    const uid = currentUid();
+    if (uid !== null && (rootStat.uid !== uid || (rootStat.mode & 0o022) !== 0)) {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+  let marker;
+  try {
+    marker = JSON.parse(
+      await readFile(path.join(rootDir, PATCH_MARKER_FILENAME), "utf8"),
+    );
+  } catch {
+    return false;
+  }
+  if (
+    marker?.patchVersion !== PATCH_VERSION ||
+    marker.emceptionVersion !== identity.version ||
+    marker.fingerprint !== identity.fingerprint ||
+    !Array.isArray(marker.files) ||
+    marker.files.length !== identity.files.length
+  ) {
+    return false;
+  }
+  for (let index = 0; index < marker.files.length; index += 1) {
+    const [relativePath, size] = marker.files[index] ?? [];
+    if (relativePath !== identity.files[index]) {
+      return false;
+    }
+    try {
+      const entry = await stat(path.join(rootDir, relativePath));
+      if (!entry.isFile() || entry.size !== size) {
+        return false;
       }
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+function currentUid() {
+  return typeof process.getuid === "function" ? process.getuid() : null;
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
 
-      if (marker?.trim() !== PATCH_VERSION) {
-        await rm(EMCEPTION_PATCH_ROOT, { recursive: true, force: true });
-        await cp(sourceRoot, EMCEPTION_PATCH_ROOT, { recursive: true });
-        await patchEmceptionModuleTree(EMCEPTION_PATCH_ROOT);
-        await writeFile(markerPath, `${PATCH_VERSION}\n`, "utf8");
+// Staging and stale dirs carry their creator's pid. A process that died
+// mid-build leaves one behind; nothing else would ever remove it.
+async function removeOrphanedBuildDirs(cacheRoot) {
+  let names;
+  try {
+    names = await readdir(cacheRoot);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const match = ORPHAN_NAME_PATTERN.exec(name);
+    if (!match) {
+      continue;
+    }
+    const pid = Number(match[1]);
+    if (pid === process.pid || isProcessAlive(pid)) {
+      continue;
+    }
+    const uid = currentUid();
+    if (uid !== null) {
+      const entry = await lstat(path.join(cacheRoot, name)).catch(() => null);
+      if (!entry || entry.uid !== uid) {
+        continue;
       }
+    }
+    await rm(path.join(cacheRoot, name), { recursive: true, force: true }).catch(
+      () => {},
+    );
+  }
+}
 
-      return EMCEPTION_PATCH_ROOT;
-    })().catch((error) => {
-      patchedEmceptionRootPromise = null;
+// rename(2) of a directory is atomic: the root either does not exist or is
+// complete. Losing the race to another process is success when its root
+// passes the content check.
+async function publishPatchedRoot(stagingDir, finalDir, identity) {
+  let lastError = null;
+  for (let attempt = 0; attempt < MAX_PUBLISH_ATTEMPTS; attempt += 1) {
+    try {
+      await rename(stagingDir, finalDir);
+      return;
+    } catch (error) {
+      if (!RENAME_COLLISION_CODES.has(error?.code)) {
+        throw error;
+      }
+      lastError = error;
+    }
+    if (await isPatchedRootValid(finalDir, identity)) {
+      return;
+    }
+    // What sits at finalDir is incomplete. Move it aside in one rename so no
+    // reader ever sees it half-deleted, then retry.
+    const staleDir = `${finalDir}${STALE_MARKER}${process.pid}-${randomBytes(4).toString("hex")}`;
+    try {
+      await rename(finalDir, staleDir);
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        continue;
+      }
       throw error;
+    }
+    await rm(staleDir, { recursive: true, force: true });
+  }
+  throw new Error(
+    `Could not publish the patched emception root at ${finalDir}.`,
+    { cause: lastError },
+  );
+}
+
+/**
+ * Returns the shared patched emception root under `cacheRoot` (default
+ * `os.tmpdir()`), building it first if it is missing or fails the content
+ * check. Safe to call from any number of processes at once.
+ */
+export async function preparePatchedEmceptionRoot(options = {}) {
+  const cacheRoot = options.cacheRoot ?? os.tmpdir();
+  const sourceRoot =
+    options.sourceRoot ?? path.dirname(require.resolve("sdn-emception"));
+  const identity = await computeEmceptionIdentity(sourceRoot);
+  const finalDir = path.join(cacheRoot, `${PATCHED_ROOT_PREFIX}${identity.key}`);
+  if (await isPatchedRootValid(finalDir, identity)) {
+    return finalDir;
+  }
+
+  await removeOrphanedBuildDirs(cacheRoot);
+  const stagingDir = await mkdtemp(
+    `${finalDir}${STAGING_MARKER}${process.pid}-`,
+  );
+  try {
+    // Copy-on-write clone where the filesystem supports it (APFS, btrfs);
+    // a plain copy elsewhere.
+    await cp(sourceRoot, stagingDir, {
+      recursive: true,
+      mode: fsConstants.COPYFILE_FICLONE,
     });
+    await patchEmceptionModuleTree(stagingDir, identity.files);
+    const files = [];
+    for (const relativePath of identity.files) {
+      const { size } = await stat(path.join(stagingDir, relativePath));
+      files.push([relativePath, size]);
+    }
+    await writeFile(
+      path.join(stagingDir, PATCH_MARKER_FILENAME),
+      `${JSON.stringify({
+        patchVersion: PATCH_VERSION,
+        emceptionVersion: identity.version,
+        fingerprint: identity.fingerprint,
+        files,
+      })}\n`,
+      "utf8",
+    );
+    await publishPatchedRoot(stagingDir, finalDir, identity);
+  } finally {
+    // A no-op after a successful rename; removes the copy after a lost race
+    // or a failure.
+    await rm(stagingDir, { recursive: true, force: true });
+  }
+  return finalDir;
+}
+
+function getPatchedEmceptionRoot() {
+  if (!patchedEmceptionRootPromise) {
+    patchedEmceptionRootPromise = preparePatchedEmceptionRoot().catch(
+      (error) => {
+        patchedEmceptionRootPromise = null;
+        throw error;
+      },
+    );
   }
 
   return patchedEmceptionRootPromise;
@@ -181,7 +450,7 @@ class EmceptionController {
     if (!this.#instancePromise) {
       this.#instancePromise = (async () => {
         installNodeRuntimeShims();
-        const patchedRoot = await preparePatchedEmceptionRoot();
+        const patchedRoot = await getPatchedEmceptionRoot();
         const moduleUrl = pathToFileURL(path.join(patchedRoot, "emception.mjs")).href;
         const { default: Emception } = await import(moduleUrl);
         const emception = new Emception({

package/src/index.d.ts

@@ -978,7 +978,16 @@ export interface CompilationResult {
   compiler: string;
   language: string;
   threadModel: ModuleThreadModelName;
+  /**
+   * The explicit `outputPath`, or the artifact inside `tempDir` when the
+   * caller passed `keepTempDir: true`. `null` otherwise: the compile's temp
+   * dir has already been removed, so use `wasmBytes`.
+   */
   outputPath: string | null;
+  /**
+   * Non-null only with `keepTempDir: true`. The caller owns it and frees it
+   * with `cleanupCompilation(result)`.
+   */
   tempDir: string | null;
   wasmBytes: Uint8Array;
   guestLink: GuestLinkArtifact | null;
@@ -1054,6 +1063,13 @@ export function compileModuleFromSource(options: {
   language?: string;
   threadModel?: ModuleThreadModelName;
   outputPath?: string;
+  /**
+   * Keep the compile's temp dir (toolchain scratch, intermediate objects, and
+   * the artifact when no `outputPath` is given) after a successful compile.
+   * Default `false`: it is removed before the promise settles, on success and
+   * on failure. A failed compile always removes it.
+   */
+  keepTempDir?: boolean;
   importedMemory?: boolean;
   sharedMemory?: boolean;
   initialMemoryBytes?: number;