space-data-module-sdk 0.8.3 → 0.8.5

package/src/compiler/compileModule.js

@@ -27,6 +27,14 @@ import {
   getInvokeCppSchemaHeaders,
 } from "./flatcSupport.js";
 import { runWithEmceptionLock } from "./emceptionNode.js";
+import {
+  assertPthreadArtifact,
+  assertPthreadFlagsPresent,
+  assertSequentialArtifact,
+  assertSequentialFlagsAbsent,
+  PTHREAD_FINAL_LINK_FLAGS,
+} from "./pthreadArtifactGuard.js";
+import { resolveWasiThreadsToolchain } from "./wasiThreadsToolchain.js";
 import { encodePluginManifest, toEmbeddedPluginManifest } from "../manifest/index.js";
 import {
   DefaultInvokeExports,
@@ -48,8 +56,10 @@ import {
   SDS_GUEST_LINK_METADATA_ENTRY_ID,
   SDS_GUEST_LINK_OBJECT_ENTRY_ID,
   SDS_GUEST_LINK_SECTION_NAME,
+  SDS_MANIFEST_SECTION_NAME,
 } from "../bundle/constants.js";
 import {
+  appendWasmCustomSection,
   decodeUnsignedLeb128,
   parseWasmModuleSections,
 } from "../bundle/wasm.js";
@@ -64,12 +74,51 @@ import { getWasmWallet } from "../utils/wasmCrypto.js";
 
 const C_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const execFileAsync = promisify(execFile);
+const EMSCRIPTEN_MEMORY_GROWTH_NOTIFY_SHIM = `
+extern "C" __attribute__((weak)) void emscripten_notify_memory_growth(int) {}
+`;
 
 export const ModuleThreadModel = Object.freeze({
   SINGLE_THREAD: "single-thread",
   EMSCRIPTEN_PTHREADS: "emscripten-pthreads",
+  // Inherently-sequential guests that must still be built by the sanctioned
+  // clang wasm32-wasip1-threads toolchain. NOT an optimisation and NOT
+  // inferable: see resolveThreadModel + assertSequentialArtifact.
+  WASI_SEQUENTIAL: "wasi-sequential",
 });
 
+// The wasi-sequential model is a DECLARATION, never a deduction. A module that
+// selects it is asserting "this guest can never spawn a thread", which the
+// emitted artifact is then held to by assertSequentialArtifact. Because that
+// assertion is a permanent architectural claim about the guest, the manifest
+// must carry a machine-readable reason for it.
+const SEQUENTIAL_JUSTIFICATION_MIN_LENGTH = 24;
+const SEQUENTIAL_JUSTIFICATION_KINDS = Object.freeze([
+  // The algorithm carries state from item k-1 into item k (e.g. a stateful codec).
+  "inherently-sequential-algorithm",
+  // The guest is a pure transform with no work to fan out.
+  "pure-transform",
+  // Threading exists, but only ACROSS independent invocations, driven by the caller.
+  "caller-level-parallelism",
+]);
+
+function resolveGuestLinkCapabilities(manifest, explicitCapabilities) {
+  const source = Array.isArray(explicitCapabilities)
+    ? explicitCapabilities
+    : (Array.isArray(manifest?.capabilities) ? manifest.capabilities : []);
+  const capabilities = [];
+  const seen = new Set();
+  for (const capability of source) {
+    const id = String(
+      typeof capability === "string" ? capability : capability?.capability ?? "",
+    ).trim();
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    capabilities.push(id);
+  }
+  return capabilities;
+}
+
 function selectCompiler(language) {
   const normalized = String(language ?? "c").trim().toLowerCase();
   if (normalized === "c++" || normalized === "cpp" || normalized === "cxx") {
@@ -90,28 +139,180 @@ function ensureExportableMethodIds(manifest) {
   }
 }
 
+function usesPthreadCompileFlags(options = {}) {
+  return (
+    options.threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS ||
+    options.sharedMemory === true
+  );
+}
+
+// wasm-ld's default main stack is 64 KiB. That is far too small for guests with
+// large caller-allocated frames: the vendored CCSDS 124 reference codec has a
+// MEASURED worst-case call chain of ~631 KB on wasm32
+// (ccsds124_decompress -> _packet_internal 335,888 B -> bit_insert 262,144 B)
+// and traps with "memory access out of bounds" on its first input under the
+// default.
+//
+// This must be an explicit, validated number rather than a default anyone can
+// drift off: the stack size is a link-time constant baked into the single
+// artifact, so pinning it is what makes the overflow boundary identical in
+// every runtime.
+const MIN_STACK_SIZE_BYTES = 64 * 1024;
+const MAX_STACK_SIZE_BYTES = 1024 * 1024 * 1024;
+
+function resolveStackSize(stackSize) {
+  if (stackSize === undefined || stackSize === null) {
+    return null;
+  }
+  if (typeof stackSize !== "number" || !Number.isInteger(stackSize)) {
+    throw new Error(
+      `stackSize must be an integer number of bytes, got ${JSON.stringify(stackSize)}.`,
+    );
+  }
+  if (stackSize < MIN_STACK_SIZE_BYTES || stackSize > MAX_STACK_SIZE_BYTES) {
+    throw new Error(
+      `stackSize ${stackSize} is out of range — expected ${MIN_STACK_SIZE_BYTES}..${MAX_STACK_SIZE_BYTES} bytes.`,
+    );
+  }
+  if (stackSize % 16 !== 0) {
+    throw new Error(
+      `stackSize ${stackSize} must be a multiple of 16 (wasm stack alignment).`,
+    );
+  }
+  return stackSize;
+}
+
 function buildCompilerArgs(exportedSymbols, options = {}) {
   const linkerExports = exportedSymbols.map(
     (symbol) => "-Wl,--export=" + symbol,
   );
-  const extraArgs = [];
-  const threadArgs = [];
-  if (options.threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS) {
-    threadArgs.push("-pthread");
+  // wasi-sequential: the SAME clang toolchain and the same target as the
+  // pthreads model, but WITHOUT the wasi-threads contract. It must own an
+  // unshared memory: an artifact that imports env.memory while exporting no
+  // wasi_thread_start is an incomplete wasi-threads contract, and WasmEdge
+  // refuses to instantiate it ("unknown import: env.memory"). Held to that
+  // shape by assertSequentialArtifact.
+  if (options.threadModel === ModuleThreadModel.WASI_SEQUENTIAL) {
+    const sequentialArgs = ["-O3", "-mbulk-memory"];
+    if (options.noEntry === true) {
+      sequentialArgs.push("-mexec-model=reactor");
+    }
+    const sequentialStackSize = resolveStackSize(options.stackSize);
+    if (sequentialStackSize !== null) {
+      sequentialArgs.push(`-Wl,-z,stack-size=${sequentialStackSize}`);
+    }
+    if (options.allowUndefinedImports === true) {
+      sequentialArgs.push("-Wl,--allow-undefined");
+    }
+    sequentialArgs.push(...linkerExports);
+    // Defensive invariant, mirroring assertPthreadFlagsPresent: a future edit
+    // that reuses PTHREAD_FINAL_LINK_FLAGS here must fail at flag time, not
+    // ship a "sequential" guest that needs cross-origin isolation to load.
+    assertSequentialFlagsAbsent(sequentialArgs, { threadModel: options.threadModel });
+    return sequentialArgs;
   }
-  if (options.allowUndefinedImports === true) {
-    extraArgs.push("-s", "ERROR_ON_UNDEFINED_SYMBOLS=0", "-Wl,--allow-undefined");
-  }
-  const args = [
-    "-O2",
-    ...threadArgs,
-    "-s",
-    "STANDALONE_WASM=1",
-    ...extraArgs,
-    ...linkerExports,
-  ];
+
+  const isPthreads = options.threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS;
+  if (isPthreads) {
+    // Non-bypassable enforced pthreads final-LINK flag set (source of truth:
+    // PTHREAD_FINAL_LINK_FLAGS). These are wasi-threads (wasm-ld) flags, NOT
+    // Emscripten -s settings: they import a shared memory and select the
+    // atomics/bulk-memory features so the artifact is a wasi-threads wasm
+    // (imports wasi.thread-spawn, exports wasi_thread_start) that threads in
+    // both the browser (via a SharedArrayBuffer/Worker shim) and WasmEdge. The
+    // toolchain args (--target/--sysroot/-resource-dir) are prepended by
+    // compileWithWasiThreads. The emitted wasm is validated by
+    // assertPthreadArtifact() in compileModuleFromSource.
+    const pthreadArgs = ["-O3"];
+    if (options.noEntry === true) {
+      // No command surface → emit a wasi REACTOR: exports `_initialize` (which
+      // runs global constructors + WASI init) and NO `_start`. This makes the
+      // artifact directly invocable exactly like the single-thread build. Plain
+      // `-Wl,--no-entry` is wrong for wasi-clang: it still links crt1-command,
+      // whose `_start` traps (unreachable) at the missing user `main`, leaving
+      // the module uninitialized and un-invocable for the direct surface.
+      pthreadArgs.push("-mexec-model=reactor");
+    }
+    pthreadArgs.push(...PTHREAD_FINAL_LINK_FLAGS);
+    const pthreadStackSize = resolveStackSize(options.stackSize);
+    if (pthreadStackSize !== null) {
+      pthreadArgs.push(`-Wl,-z,stack-size=${pthreadStackSize}`);
+    }
+    if (options.allowUndefinedImports === true) {
+      pthreadArgs.push("-Wl,--allow-undefined");
+    }
+    pthreadArgs.push(...linkerExports);
+    // Defensive invariant: the pthreads model must never lose a mandated flag.
+    assertPthreadFlagsPresent(pthreadArgs, { threadModel: options.threadModel });
+    return pthreadArgs;
+  }
+  // Single-thread / Emscripten-shared-memory-browser path (emception or system
+  // emscripten). Uses Emscripten -s settings.
+  const args = ["-O3"];
   if (options.noEntry === true) {
-    args.splice(1, 0, "--no-entry");
+    args.push("--no-entry");
+  }
+  // Bulk-memory ops: memcpy/memset in module code lower to native
+  // memory.copy/memory.fill instead of byte loops — WITHOUT this, large
+  // aligned-stream frames crawl (~10 MB/s) under interpreted hosts
+  // (loop C.5 wirespeed gate). Baseline wasm feature, supported by every
+  // target host (WasmEdge + all browsers).
+  args.push("-mbulk-memory");
+  if (usesPthreadCompileFlags(options)) {
+    args.push("-pthread");
+  }
+  args.push("-s", "STANDALONE_WASM=1");
+  if (options.importedMemory === true) {
+    args.push("-s", "IMPORTED_MEMORY=1");
+  }
+  if (options.sharedMemory === true) {
+    args.push("-s", "SHARED_MEMORY=1");
+  }
+  if (options.allowUndefinedImports === true) {
+    args.push("-s", "ERROR_ON_UNDEFINED_SYMBOLS=0", "-Wl,--allow-undefined");
+  }
+  args.push("-s", "ALLOW_MEMORY_GROWTH=1");
+  args.push(...linkerExports);
+  return args;
+}
+
+function buildSourceCompilerArgs(options = {}) {
+  const isPthreads = options.threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS;
+  // -mbulk-memory: see buildCompilerArgs — memcpy/memset become native
+  // memory.copy/memory.fill (loop C.5).
+  const args = ["-O3", "-mbulk-memory", "-DNDEBUG"];
+  if (options.threadModel === ModuleThreadModel.WASI_SEQUENTIAL) {
+    // -fno-exceptions for the same reason as the pthreads model: the wasi
+    // libc++ is built without exception support, so the generated C++ invoke
+    // bridge otherwise fails to link on __cxa_allocate_exception.
+    //
+    // But deliberately NO -matomics and NO -pthread: a sequential guest must
+    // not emit atomics, or the artifact acquires the shared-memory shape that
+    // assertSequentialArtifact rejects.
+    args.push("-fno-exceptions");
+    for (const define of Array.isArray(options.defines) ? options.defines : []) {
+      const text = String(define ?? "").trim();
+      if (/^[A-Za-z_][A-Za-z0-9_]*(=[^\s]*)?$/.test(text)) {
+        args.push(`-D${text}`);
+      }
+    }
+    return args;
+  }
+  if (isPthreads) {
+    // wasi-threads object compile: enable atomics and disable C++ exceptions
+    // (the wasi-threads libc++ is built without exception support, so throwing
+    // code otherwise fails to link on __cxa_throw / __cxa_allocate_exception).
+    args.push("-matomics", "-fno-exceptions", "-pthread");
+  } else if (usesPthreadCompileFlags(options)) {
+    args.push("-pthread");
+  }
+  // Caller-supplied preprocessor defines (e.g. SDN_FLATSQL_LINKED=1 for the
+  // engine-linked guest-link object variant, loop C.7). NAME or NAME=VALUE.
+  for (const define of Array.isArray(options.defines) ? options.defines : []) {
+    const text = String(define ?? "").trim();
+    if (/^[A-Za-z_][A-Za-z0-9_]*(=[^\s]*)?$/.test(text)) {
+      args.push(`-D${text}`);
+    }
   }
   return args;
 }
@@ -127,11 +328,58 @@ function normalizeThreadModel(value) {
   if (normalized === ModuleThreadModel.EMSCRIPTEN_PTHREADS) {
     return ModuleThreadModel.EMSCRIPTEN_PTHREADS;
   }
+  if (normalized === ModuleThreadModel.WASI_SEQUENTIAL) {
+    return ModuleThreadModel.WASI_SEQUENTIAL;
+  }
   throw new Error(
-    `Unsupported threadModel "${value}". Expected "${ModuleThreadModel.SINGLE_THREAD}" or "${ModuleThreadModel.EMSCRIPTEN_PTHREADS}".`,
+    `Unsupported threadModel "${value}". Expected one of ` +
+      `"${ModuleThreadModel.SINGLE_THREAD}", "${ModuleThreadModel.EMSCRIPTEN_PTHREADS}", ` +
+      `"${ModuleThreadModel.WASI_SEQUENTIAL}".`,
   );
 }
 
+/**
+ * The wasi-sequential model must be justified in the manifest, in a
+ * machine-readable form, or the compile fails. "It happens not to thread today"
+ * is not a reason — the guest is being permanently exempted from the threading
+ * contract, and a future edit that adds a thread must fail loudly rather than
+ * silently re-shape the artifact.
+ *
+ * manifest.sequentialJustification = { kind, detail }
+ */
+function assertSequentialJustification(manifest) {
+  const justification = manifest?.sequentialJustification;
+  const declare =
+    'Declare manifest.sequentialJustification = { "kind": <one of ' +
+    `${JSON.stringify(SEQUENTIAL_JUSTIFICATION_KINDS)}>, "detail": "<why this guest can never spawn a thread>" }.`;
+
+  if (justification === undefined || justification === null) {
+    throw new Error(
+      `threadModel "${ModuleThreadModel.WASI_SEQUENTIAL}" requires an explicit justification. ${declare}`,
+    );
+  }
+  if (typeof justification !== "object" || Array.isArray(justification)) {
+    throw new Error(
+      `manifest.sequentialJustification must be an object, got ${Array.isArray(justification) ? "an array" : typeof justification}. ${declare}`,
+    );
+  }
+  const kind = String(justification.kind ?? "").trim();
+  if (!SEQUENTIAL_JUSTIFICATION_KINDS.includes(kind)) {
+    throw new Error(
+      `manifest.sequentialJustification.kind ${JSON.stringify(kind)} is not recognised. ` +
+        `Expected one of ${JSON.stringify(SEQUENTIAL_JUSTIFICATION_KINDS)}.`,
+    );
+  }
+  const detail = String(justification.detail ?? "").trim();
+  if (detail.length < SEQUENTIAL_JUSTIFICATION_MIN_LENGTH) {
+    throw new Error(
+      `manifest.sequentialJustification.detail must be a substantive explanation ` +
+        `(at least ${SEQUENTIAL_JUSTIFICATION_MIN_LENGTH} characters), got ${detail.length}. ${declare}`,
+    );
+  }
+  return { kind, detail };
+}
+
 function resolveThreadModel({ manifest, threadModel } = {}) {
   const explicit = normalizeThreadModel(threadModel);
   if (explicit) {
@@ -142,26 +390,59 @@ function resolveThreadModel({ manifest, threadModel } = {}) {
         .map((target) => String(target ?? "").trim().toLowerCase())
         .filter(Boolean)
     : [];
-  if (runtimeTargets.includes(RuntimeTarget.BROWSER)) {
-    return ModuleThreadModel.SINGLE_THREAD;
-  }
+
+  // BROWSER MUST NOT IMPLY EMCC.
+  //
+  // This test used to run BEFORE the wasmedge test and return SINGLE_THREAD,
+  // which routes to Emscripten. The effect was that the MORE isomorphic a
+  // module declared itself to be, the worse it was treated: a manifest saying
+  // runtimeTargets ["browser","wasmedge"] matched on "browser" first and was
+  // silently compiled by emcc, even though it had explicitly asked to run under
+  // WasmEdge. Targeting a browser says nothing about whether a guest threads —
+  // it is a deployment fact, not a concurrency fact — so it must never select a
+  // toolchain.
   if (runtimeTargets.includes(RuntimeTarget.WASMEDGE)) {
     return ModuleThreadModel.EMSCRIPTEN_PTHREADS;
   }
+  if (runtimeTargets.includes(RuntimeTarget.BROWSER)) {
+    throw new Error(
+      "Cannot infer a thread model from runtimeTargets [browser]: targeting a " +
+        "browser does not say whether the guest threads, and it must never imply " +
+        "the Emscripten toolchain. Declare threadModel explicitly — " +
+        `"${ModuleThreadModel.EMSCRIPTEN_PTHREADS}" (real wasi-threads), ` +
+        `"${ModuleThreadModel.WASI_SEQUENTIAL}" (clang wasi, provably never spawns a thread; ` +
+        "requires manifest.sequentialJustification), or " +
+        `"${ModuleThreadModel.SINGLE_THREAD}" (legacy Emscripten).`,
+    );
+  }
   return ModuleThreadModel.SINGLE_THREAD;
 }
 
-function requiresSystemEmscripten(threadModel) {
-  return threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS;
+function requiresSystemEmscripten(threadModel, options = {}) {
+  return (
+    threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS ||
+    options.sharedMemory === true
+  );
 }
 
-function guestLinkSymbolPrefix(pluginId) {
+// Guest-link symbols are namespaced by the FULL lowercase-hex encoding of the
+// pluginId's UTF-8 bytes. Hex encoding is injective, so distinct pluginIds always
+// map to distinct prefixes. Do NOT truncate: a prior `.slice(0, 24)` (12 bytes)
+// collided real plugin ids that share a 12-byte stem — e.g. `com.orbpro.iss-source`
+// and `com.orbpro.intelsat-source` both truncated to hex("com.orbpro.i")
+// (`636f6d2e6f726270726f2e69`), which would silently merge/clash their symbols at
+// `wasm-ld -r` compose time. Wasm symbol names have no meaningful length limit, so
+// the full hex is safe. The emitted prefix (and the per-method `methodSymbols`) is
+// recorded in the guest-link metadata; that metadata is the AUTHORITATIVE source
+// consumers read at compose time (see src/flow/flowCompiler.js) — consumers must
+// never re-derive the prefix from pluginId, which keeps already-committed artifacts
+// (including any that carry a legacy truncated prefix) compatible.
+export function guestLinkSymbolPrefix(pluginId) {
   const normalized = String(pluginId ?? "module");
-  const ascii = Array.from(new TextEncoder().encode(normalized))
+  const hex = Array.from(new TextEncoder().encode(normalized))
     .map((byte) => byte.toString(16).padStart(2, "0"))
-    .join("")
-    .slice(0, 24);
-  return `sdm_guest_${ascii}_`;
+    .join("");
+  return `sdm_guest_${hex}_`;
 }
 
 function parseStrongDefinedIdentifiers(nmOutput = "") {
@@ -345,6 +626,9 @@ function createGuestLinkBundleEntries(guestLink) {
         methodIds: Object.keys(guestLink.methodSymbols ?? {}),
         language: guestLink.language,
         threadModel: guestLink.threadModel ?? ModuleThreadModel.SINGLE_THREAD,
+        ...(Array.isArray(guestLink.capabilities)
+          ? { capabilities: [...guestLink.capabilities] }
+          : {}),
       },
       description: "Guest-link metadata for monolithic flow linking.",
     },
@@ -448,6 +732,8 @@ async function compileWithEmception(options = {}) {
             "-c",
             sourcePath,
             `-I${workDir}`,
+            `-I${runtimeIncludeDir}`,
+            ...buildSourceCompilerArgs(compileOptions),
             "-o",
             sourceObjectPath,
           ],
@@ -476,7 +762,9 @@ async function compileWithEmception(options = {}) {
           "-c",
           sourcePath,
           `-I${workDir}`,
+          `-I${runtimeIncludeDir}`,
           ...guestLink.renameArgs,
+          ...buildSourceCompilerArgs(compileOptions),
           "-o",
           linkObjectPath,
         ];
@@ -541,6 +829,7 @@ async function compileWithEmception(options = {}) {
             methodSymbols: guestLink.methodSymbols,
             threadModel:
               compileOptions.threadModel ?? ModuleThreadModel.SINGLE_THREAD,
+            capabilities: compileOptions.guestLinkCapabilities,
             objectBytes: linkObjectBytes,
           },
         };
@@ -634,9 +923,8 @@ async function compileWithSystemEmscripten(options = {}) {
       "-c",
       sourcePath,
       `-I${tempDir}`,
-      ...(compileOptions.threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS
-        ? ["-pthread"]
-        : []),
+      `-I${runtimeIncludeDir}`,
+      ...buildSourceCompilerArgs(compileOptions),
       "-o",
       sourceObjectPath,
     ];
@@ -655,10 +943,9 @@ async function compileWithSystemEmscripten(options = {}) {
       "-c",
       sourcePath,
       `-I${tempDir}`,
-      ...(compileOptions.threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS
-        ? ["-pthread"]
-        : []),
+      `-I${runtimeIncludeDir}`,
       ...guestLink.renameArgs,
+      ...buildSourceCompilerArgs(compileOptions),
       "-o",
       linkObjectPath,
     ];
@@ -669,9 +956,7 @@ async function compileWithSystemEmscripten(options = {}) {
       "-std=c++17",
       `-I${tempDir}`,
       `-I${runtimeIncludeDir}`,
-      ...(compileOptions.threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS
-        ? ["-pthread"]
-        : []),
+      ...(usesPthreadCompileFlags(compileOptions) ? ["-pthread"] : []),
       "-o",
       manifestObjectPath,
     ]);
@@ -681,9 +966,7 @@ async function compileWithSystemEmscripten(options = {}) {
       "-std=c++17",
       `-I${tempDir}`,
       `-I${runtimeIncludeDir}`,
-      ...(compileOptions.threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS
-        ? ["-pthread"]
-        : []),
+      ...(usesPthreadCompileFlags(compileOptions) ? ["-pthread"] : []),
       "-o",
       invokeObjectPath,
     ]);
@@ -709,6 +992,161 @@ async function compileWithSystemEmscripten(options = {}) {
         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;
+  }
+}
+
+async function runWasiCompiler(command, args, options = {}) {
+  try {
+    await execFileAsync(command, args, {
+      cwd: options.cwd,
+      maxBuffer: 32 * 1024 * 1024,
+    });
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error(
+        `Compilation failed: wasi-threads driver "${command}" was not found on PATH.`,
+      );
+    }
+    const stderr = typeof error?.stderr === "string" ? error.stderr.trim() : "";
+    const stdout = typeof error?.stdout === "string" ? error.stdout.trim() : "";
+    const detail = stderr || stdout || error?.message || "unknown error";
+    throw new Error(`Compilation failed with ${command} (wasi-threads): ${detail}`);
+  }
+}
+
+// Builds the isomorphic-pthreads artifact with the wasi-threads toolchain
+// (clang --target=wasm32-wasip1-threads). Emits a wasi-threads wasm (imports
+// wasi.thread-spawn, exports wasi_thread_start over an imported shared memory)
+// that threads under WasmEdge and, via a SharedArrayBuffer/Worker shim, the
+// browser — NOT an Emscripten Web-Worker build. See wasiThreadsToolchain.js and
+// docs/isomorphic-pthreads.md.
+async function compileWithWasiThreads(options = {}) {
+  const {
+    manifest,
+    language,
+    sourceExtension,
+    sourceCode,
+    manifestSource,
+    invokeHeaderSource,
+    invokeSource,
+    exportedSymbols,
+    outputPath,
+    compileOptions,
+  } = options;
+  const toolchain = resolveWasiThreadsToolchain();
+  const isCpp = String(language ?? "").toLowerCase().startsWith("c++");
+  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"),
+  );
+  const runtimeIncludeDir = path.join(tempDir, "flatbuffers-runtime");
+  const sourcePath = path.join(tempDir, `module.${sourceExtension}`);
+  const manifestSourcePath = path.join(tempDir, "plugin-manifest-exports.cpp");
+  const invokeHeaderPath = path.join(tempDir, "space_data_module_invoke.h");
+  const invokeSourcePath = path.join(tempDir, "plugin-invoke-bridge.cpp");
+  const sourceObjectPath = path.join(tempDir, "module.o");
+  const linkObjectPath = path.join(tempDir, "module-link.o");
+  const manifestObjectPath = path.join(tempDir, "plugin-manifest-exports.o");
+  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 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, [
+      ...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",
+        srcPath,
+        "-std=c++17",
+        ...includeArgs,
+        ...sourceCompilerArgs,
+        "-o",
+        objPath,
+      ]);
+    }
+
+    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,
       },
     };
@@ -727,7 +1165,14 @@ export async function compileModuleFromSource(options = {}) {
 
   ensureExportableMethodIds(manifest);
 
-  const validation = await validateArtifactWithStandards({ manifest });
+  const standardsOptions = {
+    catalog: options.catalog,
+    standardsRoot: options.standardsRoot,
+  };
+  const validation = await validateArtifactWithStandards({
+    manifest,
+    ...standardsOptions,
+  });
   if (!validation.ok) {
     const error = new Error("Manifest validation failed.");
     error.report = validation;
@@ -737,17 +1182,20 @@ export async function compileModuleFromSource(options = {}) {
   const compiler = selectCompiler(options.language);
   const invokeSurfaces = resolveInvokeSurfaces(manifest);
   const includeCommandMain = invokeSurfaces.includes(InvokeSurface.COMMAND);
-  const { manifest: embeddedManifest, warnings } = toEmbeddedPluginManifest(
-    manifest,
-  );
+  const { warnings } = toEmbeddedPluginManifest(manifest);
   const manifestSource = generateEmbeddedManifestSource({
-    manifest: embeddedManifest,
-  });
-  const invokeHeaderSource = generateInvokeSupportHeader();
-  const invokeSource = generateInvokeSupportSource({
+    // Embed the canonical raw PLG shape so fields that do not exist in the
+    // legacy PMAN object model (notably schemaVersion) remain byte-identical
+    // to the signed custom-section manifest.
     manifest,
-    includeCommandMain,
   });
+  const invokeHeaderSource = generateInvokeSupportHeader();
+  const invokeSource =
+    EMSCRIPTEN_MEMORY_GROWTH_NOTIFY_SHIM +
+    generateInvokeSupportSource({
+      manifest,
+      includeCommandMain,
+    });
 
   const exportedSymbols = [
     "plugin_get_manifest_flatbuffer",
@@ -774,10 +1222,27 @@ export async function compileModuleFromSource(options = {}) {
     ...options,
     noEntry: includeCommandMain !== true,
     threadModel,
+    guestLinkCapabilities: resolveGuestLinkCapabilities(
+      manifest,
+      options.guestLinkCapabilities,
+    ),
   };
-  const compileFunction = requiresSystemEmscripten(threadModel)
-    ? compileWithSystemEmscripten
-    : compileWithEmception;
+  if (threadModel === ModuleThreadModel.WASI_SEQUENTIAL) {
+    // Fails the compile when the manifest has not justified the exemption.
+    assertSequentialJustification(manifest);
+  }
+  // BOTH wasi models use the sanctioned clang wasm32-wasip1-threads toolchain.
+  // The difference is the link shape and which artifact guard applies.
+  const useWasiThreads =
+    threadModel === ModuleThreadModel.EMSCRIPTEN_PTHREADS ||
+    threadModel === ModuleThreadModel.WASI_SEQUENTIAL;
+  const useSystemEmscripten =
+    !useWasiThreads && requiresSystemEmscripten(threadModel, compileOptions);
+  const compileFunction = useWasiThreads
+    ? compileWithWasiThreads
+    : useSystemEmscripten
+      ? compileWithSystemEmscripten
+      : compileWithEmception;
   const result = await compileFunction({
     manifest,
     language: compiler.language,
@@ -791,20 +1256,49 @@ export async function compileModuleFromSource(options = {}) {
     outputPath: options.outputPath,
     compileOptions,
   });
-  wasmBytes = result.wasmBytes;
+  wasmBytes = appendWasmCustomSection(
+    result.wasmBytes,
+    SDS_MANIFEST_SECTION_NAME,
+    encodePluginManifest(manifest),
+  );
   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,
+    });
+  }
+
   // Validate the compiled artifact
   const report = await validateArtifactWithStandards({
     manifest,
     wasmPath: resolvedOutputPath,
+    ...standardsOptions,
   });
 
   return {
-    compiler: requiresSystemEmscripten(threadModel)
-      ? "em++ (system emscripten pthreads)"
-      : "em++ (emception)",
+    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,
@@ -812,6 +1306,7 @@ export async function compileModuleFromSource(options = {}) {
     wasmBytes,
     guestLink: result.guestLink,
     manifestWarnings: warnings,
+    threadFeatures,
     report,
   };
 }
@@ -892,6 +1387,10 @@ export async function protectModuleArtifact(options = {}) {
     manifestHashHex,
     authorization: signedAuthorization,
   };
+  const publicationNoticeOptions = {
+    publishTimestamp: options.publishTimestamp,
+    publishTimestampMs: options.publishTimestampMs,
+  };
 
   let singleFileBundle = null;
   let singleFileBundleRecords = null;
@@ -928,6 +1427,7 @@ export async function protectModuleArtifact(options = {}) {
     const encryptedBaseBytes = base64ToBytes(encryptedBase.protectedBlobBase64);
     const parsedEncryptedBase = extractPublicationRecordCollection(encryptedBaseBytes);
     publicationNotice = await createPublicationNotice({
+      ...publicationNoticeOptions,
       payloadBytes: parsedEncryptedBase.payloadBytes,
       artifactId,
       programId,
@@ -958,6 +1458,7 @@ export async function protectModuleArtifact(options = {}) {
     });
   } else {
     publicationNotice = await createPublicationNotice({
+      ...publicationNoticeOptions,
       payloadBytes: bundleBytes,
       artifactId,
       programId,