space-data-module-sdk 0.8.6 → 0.8.8

package/src/{testing → host}/browserModuleHarness.js

@@ -1,9 +1,17 @@
 /**
- * Browser-side module harness.
+ * Browser module host — the browser leg of the tri-runtime contract.
  *
- * Loads the same standalone WASI .wasm artifact that WasmEdge runs,
- * instantiating it in the browser with the WASI shim + optional space_data_module_host
- * bridge. Matches the createModuleHarness() API surface.
+ * Loads the same standalone WASI .wasm artifact that native WasmEdge and the
+ * Docker WasmEdge container run, instantiating it in the browser with the WASI
+ * shim + optional space_data_module_host bridge. Matches the
+ * createModuleHarness() API surface.
+ *
+ * This is PRODUCTION runtime surface, published as
+ * `space-data-module-sdk/host/browser-module`. It lived under `src/testing/`
+ * until 2026-08-07, which made every browser consumer import a test-harness
+ * subpath to load a module and let the Node harnesses next door reach a browser
+ * bundle (`orbpro-engine-bundle-ships-node-builtins`). Nothing browser-facing
+ * lives under `src/testing/` any more.
  *
  * Supports two invoke paths:
  *   1. "direct" — call plugin_invoke_stream(ptr, len, &outLen) and read
@@ -12,19 +20,19 @@
  *      stdout for the response bytes.
  */
 
-import { createBrowserWasiShim, WasiExitError } from "../host/wasiShim.js";
+import { createBrowserWasiShim, WasiExitError } from "./wasiShim.js";
 import {
   createWasiThreadSpawn,
   isWasiThreadsModule,
-} from "../host/wasiThreadHost.js";
-import { createBrowserHost } from "../host/browserHost.js";
+} from "./wasiThreadHost.js";
+import { createBrowserHost } from "./browserHost.js";
 import { getWasmWallet } from "../utils/wasmCrypto.js";
 import {
   createHostcallBridge,
   createAsyncHostDispatcher,
   createHostSyncDispatcher,
   DEFAULT_HOSTCALL_IMPORT_MODULE,
-} from "../host/abi.js";
+} from "./abi.js";
 import {
   DefaultInvokeExports,
   DefaultManifestExports,
@@ -41,33 +49,12 @@ import {
   resolveModuleSignaturePolicy,
   verifyModuleArtifact,
 } from "../bundle/signing.js";
-import { extractPublicationRecordCollection } from "../transport/records.js";
+// Artifact byte reduction is an ARTIFACT concern shared by all three runtimes,
+// so it lives on `space-data-module-sdk/bundle`. Re-exported here because a
+// caller loading a module in the browser needs it in the same breath.
+import { toLoadableWasmBytes } from "../bundle/artifactBytes.js";
 
-/**
- * Reduce a module artifact to the bytes a wasm engine can compile.
- *
- * Signed/published artifacts carry an appended publication record collection
- * (MBL bundle with the sds.signature entry, PNM/REC trailers). Wasm engines
- * reject those trailing bytes ("unknown section code"), so the canonical
- * module payload must be extracted before compile. ENC-protected payloads
- * cannot be loaded here — decryption is a host concern.
- *
- * @param {Uint8Array} bytes - raw artifact bytes
- * @returns {Uint8Array} compilable wasm bytes
- */
-export function toLoadableWasmBytes(bytes) {
-  const publication = extractPublicationRecordCollection(bytes);
-  if (!publication) {
-    return bytes;
-  }
-  if (publication.enc) {
-    throw new ModuleSignatureError(
-      "encrypted_artifact",
-      "Module artifact payload is ENC-protected; decrypt it before loading.",
-    );
-  }
-  return publication.payloadBytes;
-}
+export { toLoadableWasmBytes };
 
 const STANDALONE_SHARED_MEMORY_ENV_STUBS = Object.freeze({
   _emscripten_init_main_thread_js: () => 0,
@@ -196,6 +183,37 @@ const DEFAULT_IMPORTED_MEMORY_MAXIMUM_BYTES = 2 * 1024 * 1024 * 1024;
 const DEFAULT_DIRECT_INVOKE_REQUEST_ARENA_BYTES = 64 * 1024;
 const SHARED_ARRAY_BUFFER_TAG = "[object SharedArrayBuffer]";
 
+/**
+ * Overwrite a plaintext wasm buffer in place. Best-effort by contract: a
+ * detached (transferred) buffer, a frozen typed array, or a runtime without
+ * writable views must not turn a successful module load into a thrown error.
+ *
+ * @param {Uint8Array|ArrayBuffer|ArrayBufferView|null|undefined} bytes
+ * @returns {number} bytes actually overwritten
+ */
+export function zeroWasmBytes(bytes) {
+  if (!bytes) {
+    return 0;
+  }
+  try {
+    const view =
+      bytes instanceof Uint8Array
+        ? bytes
+        : bytes instanceof ArrayBuffer
+          ? new Uint8Array(bytes)
+          : ArrayBuffer.isView(bytes)
+            ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+            : null;
+    if (!view || view.byteLength === 0) {
+      return 0;
+    }
+    view.fill(0);
+    return view.byteLength;
+  } catch {
+    return 0;
+  }
+}
+
 export function isSharedArrayBufferLike(value) {
   return (
     value !== null &&
@@ -408,6 +426,11 @@ async function instantiateBrowserModule(options = {}) {
 export async function createBrowserModuleHarness(options = {}) {
   let wasmSource = options.wasmSource;
   const signaturePolicy = resolveModuleSignaturePolicy(options);
+  // Bytes THIS function materializes itself (Response/URL fetch, or the
+  // ArrayBuffer/array copy taken for signature verification) — never a
+  // caller-owned buffer, which this function neither created nor may safely
+  // scrub. Zeroed below once the module is compiled.
+  let ownedArtifactBytes = null;
   if (signaturePolicy) {
     if (wasmSource instanceof WebAssembly.Module) {
       throw new ModuleSignatureError(
@@ -434,8 +457,20 @@ export async function createBrowserModuleHarness(options = {}) {
     }
     await verifyModuleArtifact(artifactBytes, signaturePolicy);
     wasmSource = artifactBytes;
+    ownedArtifactBytes = artifactBytes;
   }
   const wasmModule = await compileWasmModule(wasmSource);
+  // Plaintext hygiene (wasm-plaintext-memory-hygiene): nothing needs the
+  // source bytes past this point. Scrub whatever THIS function materialized
+  // itself, then drop every local/options reference to the source — a
+  // caller-supplied Uint8Array/ArrayBuffer must not outlive this call by
+  // being pinned via closure over `options` for the harness's entire
+  // lifetime (the returned harness closes over `options` for many other,
+  // unrelated fields).
+  zeroWasmBytes(ownedArtifactBytes);
+  ownedArtifactBytes = null;
+  wasmSource = null;
+  options.wasmSource = null;
   const moduleImports = WebAssembly.Module.imports(wasmModule);
   const needsHostBridge = moduleImports.some(
     (entry) => entry.module === DEFAULT_HOSTCALL_IMPORT_MODULE,

package/src/host/index.js

@@ -7,3 +7,9 @@ export * from "./isomorphicLoader.js";
 export * from "./abi.js";
 export * from "./sabHostcallChannel.js";
 export * from "./timerDriver.js";
+export * from "./providerAccessAbi.js";
+export * from "./providerAccess.js";
+export * from "./providerAccessFixtureAdapter.js";
+export * from "./providerAccessEngineAdapter.js";
+export * from "./providerAccessTileStoreAdapter.js";
+export * from "./terrainSourceSeam.js";

package/src/host/isomorphicLoader.js

@@ -1,43 +1,39 @@
 /**
- * Isomorphic module loader.
+ * Isomorphic module loader — NODE/WasmEdge leg (the `default` condition).
  *
  * Unified entry point that detects the runtime environment and artifact
  * profile, then loads the module through the appropriate path:
- *   - Browser: createBrowserModuleHarness (WASI shim + optional space_data_module_host)
- *   - Node/WasmEdge: createModuleHarness (subprocess)
+ *   - Browser (jsdom/embedded window under Node): createBrowserModuleHarness
+ *   - Node/WasmEdge: createModuleHarness (subprocess) or the WasmEdge command
+ *     harness below
  *
- * The same compiled .wasm artifact works in both environments.
+ * The same compiled .wasm artifact works in every environment; only HOW it is
+ * launched differs, and that difference is absorbed here — never in a guest.
+ *
+ * A browser resolves `./host/isomorphic` to `isomorphicLoaderBrowser.js`
+ * instead, via the package's `browser` export condition. The two legs share
+ * `isomorphicLoaderCore.js` so the runtime-independent half cannot drift. The
+ * split is what keeps a browser bundle from statically resolving the
+ * node:child_process/os/path/fs imports below
+ * (`module-sdk-browser-entry-node-builtins`).
  */
 
 import {
   createBrowserModuleHarness,
-  detectArtifactProfile,
   toLoadableWasmBytes,
-} from "../testing/browserModuleHarness.js";
-import { createAsyncHostDispatcher } from "./abi.js";
+} from "./browserModuleHarness.js";
 import {
   resolveModuleSignaturePolicy,
   verifyModuleArtifact,
 } from "../bundle/signing.js";
+import { attachHostDispatch, inspectModule } from "./isomorphicLoaderCore.js";
+
+export { inspectModule, attachHostDispatch };
 
 const isBrowser =
   typeof globalThis.window !== "undefined" &&
   typeof globalThis.document !== "undefined";
 
-function attachHostDispatch(harness, host) {
-  if (!host || typeof host !== "object") {
-    return harness;
-  }
-  const dispatchHost = createAsyncHostDispatcher(host);
-  return {
-    ...harness,
-    host,
-    async callHost(operation, params = {}) {
-      return dispatchHost(operation, params);
-    },
-  };
-}
-
 async function createWasmEdgeCommandHarness(options = {}) {
   const [
     { spawn },
@@ -269,27 +265,3 @@ export async function loadModule(options = {}) {
     options.host ?? null,
   );
 }
-
-/**
- * Inspect a WASM module's artifact profile without instantiating it.
- *
- * @param {Uint8Array|ArrayBuffer|WebAssembly.Module} source
- * @returns {Promise<{profile: string, exports: string[], imports: Array}>}
- */
-export async function inspectModule(source) {
-  let wasmModule;
-  if (source instanceof WebAssembly.Module) {
-    wasmModule = source;
-  } else {
-    const bytes =
-      source instanceof ArrayBuffer ? new Uint8Array(source) : source;
-    // Tolerate signed/published artifacts (appended publication records).
-    wasmModule = await WebAssembly.compile(toLoadableWasmBytes(bytes));
-  }
-
-  const profile = detectArtifactProfile(wasmModule);
-  const exports = WebAssembly.Module.exports(wasmModule).map((e) => e.name);
-  const imports = WebAssembly.Module.imports(wasmModule);
-
-  return { profile, exports, imports };
-}

package/src/host/isomorphicLoaderBrowser.js

@@ -0,0 +1,47 @@
+/**
+ * Isomorphic module loader — BROWSER leg.
+ *
+ * The target of the `browser` export condition on
+ * `space-data-module-sdk/host/isomorphic`, and the loader re-exported by the
+ * package's own `browser` entry (`src/browser.js`).
+ *
+ * Same public surface as the Node leg — `loadModule` and `inspectModule` — and
+ * for a browser it does EXACTLY what the Node leg's `isBrowser` branch did
+ * before the split: hand the artifact to `createBrowserModuleHarness`. What it
+ * does not carry is the WasmEdge subprocess path, because a browser can never
+ * take it and a bundler resolves it anyway.
+ *
+ * Asking this leg for a server runtime is a defect, not a fallback: it throws.
+ * A caller that legitimately needs both is running under Node and resolves the
+ * Node leg through the same subpath.
+ */
+
+import { createBrowserModuleHarness } from "./browserModuleHarness.js";
+import { resolveModuleSignaturePolicy } from "../bundle/signing.js";
+import { attachHostDispatch, inspectModule } from "./isomorphicLoaderCore.js";
+
+export { inspectModule, attachHostDispatch };
+
+/**
+ * Load a WASM module in the browser.
+ *
+ * @param {Object} options - see the Node leg for the full option list; the
+ *   browser leg accepts the same object and honours the browser-relevant keys.
+ * @returns {Promise<Object>} Harness with invoke(), readManifest(), destroy().
+ */
+export async function loadModule(options = {}) {
+  // Resolved for the same reason the Node leg resolves it: an invalid policy is
+  // a caller error that must surface identically in every runtime, before any
+  // artifact work happens.
+  resolveModuleSignaturePolicy(options);
+
+  const runtimeKind = options.runtimeKind;
+  if (typeof runtimeKind === "string" && runtimeKind !== "browser") {
+    throw new Error(
+      `The browser isomorphic loader cannot run runtimeKind "${runtimeKind}"; ` +
+        "that artifact must be loaded from a Node/WasmEdge host.",
+    );
+  }
+
+  return createBrowserModuleHarness(options);
+}

package/src/host/isomorphicLoaderCore.js

@@ -0,0 +1,58 @@
+/**
+ * Isomorphic loader — the runtime-independent half.
+ *
+ * Everything here is byte-identical work that every runtime does: reduce the
+ * artifact, compile it, read its profile/exports/imports, attach the host
+ * dispatcher. `isomorphicLoader.js` (Node/WasmEdge) and
+ * `isomorphicLoaderBrowser.js` (browser) both build on this, so the two legs of
+ * `./host/isomorphic` cannot drift apart on the parts that must not differ.
+ *
+ * The split exists because a browser BUNDLER resolves every branch statically:
+ * one file holding both legs put node:child_process/os/path/fs into every
+ * browser bundle of the SDK's own `browser` export condition
+ * (`module-sdk-browser-entry-node-builtins`). The runtime difference is now
+ * absorbed by the package's export conditions — a host-shim concern — instead
+ * of by a runtime check inside one file.
+ */
+
+import { detectArtifactProfile } from "./browserModuleHarness.js";
+import { createAsyncHostDispatcher } from "./abi.js";
+import { toLoadableWasmBytes } from "../bundle/artifactBytes.js";
+
+export function attachHostDispatch(harness, host) {
+  if (!host || typeof host !== "object") {
+    return harness;
+  }
+  const dispatchHost = createAsyncHostDispatcher(host);
+  return {
+    ...harness,
+    host,
+    async callHost(operation, params = {}) {
+      return dispatchHost(operation, params);
+    },
+  };
+}
+
+/**
+ * Inspect a WASM module's artifact profile without instantiating it.
+ *
+ * @param {Uint8Array|ArrayBuffer|WebAssembly.Module} source
+ * @returns {Promise<{profile: string, exports: string[], imports: Array}>}
+ */
+export async function inspectModule(source) {
+  let wasmModule;
+  if (source instanceof WebAssembly.Module) {
+    wasmModule = source;
+  } else {
+    const bytes =
+      source instanceof ArrayBuffer ? new Uint8Array(source) : source;
+    // Tolerate signed/published artifacts (appended publication records).
+    wasmModule = await WebAssembly.compile(toLoadableWasmBytes(bytes));
+  }
+
+  const profile = detectArtifactProfile(wasmModule);
+  const exports = WebAssembly.Module.exports(wasmModule).map((e) => e.name);
+  const imports = WebAssembly.Module.imports(wasmModule);
+
+  return { profile, exports, imports };
+}

package/src/host/nodeBuiltinSpecifier.js

@@ -0,0 +1,43 @@
+/**
+ * Opaque Node builtin specifiers for isomorphic host shims.
+ *
+ * A host shim that serves BOTH runtimes needs a Node-only branch that is dead
+ * in a browser. Writing that branch as a literal `import("node:worker_threads")`
+ * does not work: esbuild/vite/rollup resolve dynamic imports STATICALLY, so a
+ * branch that can never run still fails — or, worse, is emitted as an external
+ * `node:` specifier that the browser then tries to FETCH, which is how the
+ * whole OrbPro gallery went dark (`orbpro-engine-bundle-ships-node-builtins`).
+ *
+ * Assembling the specifier at runtime keeps it opaque to the bundler. This is
+ * host-shim code absorbing a runtime difference, which is the only place the
+ * tri-runtime contract allows a difference to be absorbed; no guest module ever
+ * gains a runtime check.
+ *
+ * Use it ONLY behind a runtime check that is false in a browser, and only in
+ * `src/host/**` — a module that needs a Node builtin unconditionally belongs on
+ * a Node-only subpath instead.
+ */
+
+// Split so no bundler's `node:`-prefix scanner sees a literal here either.
+const NODE_BUILTIN_PREFIX = "no" + "de:";
+
+/**
+ * @param {string} name - builtin name without the `node:` prefix
+ * @returns {string} the specifier, assembled at runtime
+ */
+export function nodeBuiltinSpecifier(name) {
+  return NODE_BUILTIN_PREFIX + name;
+}
+
+/**
+ * Import a Node builtin from an isomorphic host shim.
+ *
+ * @param {string} name - builtin name without the `node:` prefix
+ * @returns {Promise<any>} the builtin's module namespace
+ */
+export async function importNodeBuiltin(name) {
+  const specifier = nodeBuiltinSpecifier(name);
+  return import(/* @vite-ignore */ /* webpackIgnore: true */ specifier);
+}
+
+export { NODE_BUILTIN_PREFIX };