space-data-module-sdk 0.8.8 → 0.8.10

package/src/testing/parityGateBrowserProbe.js

@@ -0,0 +1,171 @@
+/**
+ * Browser-side host-contract instantiation probe.
+ *
+ * Bundled by parityGate.js and served to a REAL headless Chrome behind
+ * COOP/COEP (cross-origin isolated, SAB-capable). Never jsdom — jsdom masks
+ * Illegal-invocation and threading realities, and a probe that lies about the
+ * browser is worse than no probe.
+ *
+ * For each artifact the probe synthesizes EXACTLY the declared host surface —
+ * WASI preview1 stubs plus the declared capability imports, with the real
+ * signatures read from the binary — and instantiates. Anything the artifact
+ * demands beyond that surface produces a LinkError naming the offender, which
+ * is the answer we want.
+ */
+
+import {
+  classifyArtifactImports,
+  readWasmImportDescriptors,
+  resolveHostSurface,
+  WASI_PREVIEW1_MODULE,
+} from "./hostContract.js";
+
+const ZERO_BY_RESULT = {
+  i32: 0,
+  i64: 0n,
+  f32: 0,
+  f64: 0,
+  v128: 0,
+};
+
+function stubReturn(results) {
+  if (!results || results.length === 0) return undefined;
+  return ZERO_BY_RESULT[results[0]] ?? 0;
+}
+
+/**
+ * Build an import object containing ONLY surface-legal entries. Out-of-surface
+ * imports are deliberately NOT supplied: their absence is the signal.
+ */
+export function buildSurfaceImports(bytes, surfaceId) {
+  const surface = resolveHostSurface(surfaceId);
+  const allowedExtra = new Set(surface.extra);
+  const descriptors = readWasmImportDescriptors(bytes);
+  const imports = Object.create(null);
+  const supplied = [];
+
+  for (const entry of descriptors) {
+    const key = `${entry.module}.${entry.name}`;
+    const inSurface =
+      (surface.wasiAny && entry.module === WASI_PREVIEW1_MODULE) ||
+      allowedExtra.has(key);
+    if (!inSurface) continue;
+
+    imports[entry.module] ??= Object.create(null);
+    if (entry.kind === "function") {
+      const results = entry.results;
+      imports[entry.module][entry.name] = () => stubReturn(results);
+    } else if (entry.kind === "memory") {
+      imports[entry.module][entry.name] = new WebAssembly.Memory({
+        initial: entry.initial,
+        maximum: entry.maximum ?? entry.initial,
+        shared: entry.shared,
+      });
+    } else if (entry.kind === "table") {
+      imports[entry.module][entry.name] = new WebAssembly.Table({
+        element: entry.element === "anyfunc" ? "anyfunc" : "externref",
+        initial: entry.initial,
+        maximum: entry.maximum,
+      });
+    } else if (entry.kind === "global") {
+      imports[entry.module][entry.name] = new WebAssembly.Global(
+        { value: entry.valtype, mutable: entry.mutable },
+        entry.valtype === "i64" ? 0n : 0,
+      );
+    }
+    supplied.push(key);
+  }
+  return { imports, supplied };
+}
+
+function linkErrorTarget(message) {
+  // Chrome: 'WebAssembly.instantiate(): Import #3 "env" "flatsql_io_open":
+  //          function import requires a callable'
+  const named = /Import\s+#\d+\s+"([^"]*)"\s+"([^"]*)"/.exec(String(message));
+  if (named) return `${named[1]}.${named[2]}`;
+  const moduleOnly = /module="([^"]*)"\s*function="([^"]*)"/.exec(String(message));
+  if (moduleOnly) return `${moduleOnly[1]}.${moduleOnly[2]}`;
+  return null;
+}
+
+export async function probeArtifactInBrowser(bytes, surfaceId) {
+  const structural = classifyArtifactImports(bytes, surfaceId);
+  let compiled;
+  try {
+    compiled = await WebAssembly.compile(bytes);
+  } catch (error) {
+    return {
+      outcome: "compile-error",
+      detail: String(error?.message ?? error),
+      missingImport: null,
+      structural,
+      exportCount: 0,
+    };
+  }
+  const { imports, supplied } = buildSurfaceImports(bytes, surfaceId);
+  try {
+    const instance = await WebAssembly.instantiate(compiled, imports);
+    return {
+      outcome: "instantiated",
+      detail: null,
+      missingImport: null,
+      structural,
+      suppliedImports: supplied,
+      exportCount: Object.keys(instance.exports ?? {}).length,
+      exportNames: Object.keys(instance.exports ?? {}).sort(),
+    };
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    const isLink = error instanceof WebAssembly.LinkError || /Import #/.test(message);
+    return {
+      outcome: isLink ? "link-error" : "instantiate-error",
+      detail: message,
+      missingImport: linkErrorTarget(message),
+      structural,
+      suppliedImports: supplied,
+      exportCount: 0,
+    };
+  }
+}
+
+/** Entry point executed inside the page. */
+export async function runBrowserGateProbe() {
+  const status = document.getElementById("status");
+  const report = (text) => {
+    if (status) status.textContent = text;
+  };
+  try {
+    const plan = await (await fetch("/gate-plan")).json();
+    report(`probing ${plan.artifacts.length} artifact(s)…`);
+    const results = [];
+    for (const artifact of plan.artifacts) {
+      const bytes = new Uint8Array(
+        await (await fetch(artifact.url)).arrayBuffer(),
+      );
+      const probe = await probeArtifactInBrowser(bytes, artifact.surface);
+      results.push({
+        id: artifact.id,
+        surface: artifact.surface,
+        byteLength: bytes.length,
+        crossOriginIsolated: Boolean(globalThis.crossOriginIsolated),
+        sharedArrayBufferAvailable: typeof SharedArrayBuffer === "function",
+        ...probe,
+      });
+      report(`probed ${results.length}/${plan.artifacts.length}`);
+    }
+    await fetch("/done", {
+      method: "POST",
+      body: JSON.stringify({ results }),
+    });
+    report("done");
+  } catch (error) {
+    await fetch("/done", {
+      method: "POST",
+      body: JSON.stringify({ fatal: String(error?.stack ?? error) }),
+    }).catch(() => {});
+  }
+}
+
+if (typeof document !== "undefined") {
+  runBrowserGateProbe();
+}

package/src/testing/parityLanes.js

@@ -29,6 +29,7 @@ import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
 import { ExitClass, assertWasmEdgeVersionMatchesPin } from "./parityHarness.js";
+import { normalizeWasmEdgeOutcome } from "./wasmedgeOutput.js";
 
 const execFile = promisify(execFileCallback);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -192,18 +193,21 @@ export async function runNativeWasmEdgeLane(context) {
             timeoutMs: context.timeoutMs,
           },
         );
+        // WasmEdge logs its own diagnostics to STDOUT; pull them out before
+        // anything compares guest bytes or classifies an exit.
+        const normalized = normalizeWasmEdgeOutcome(outcome);
         const { exitClass, exitDetail } = classifyProcessOutcome({
           code: outcome.code,
           signal: outcome.signal,
-          stderrText: Buffer.from(outcome.stderr).toString("utf8"),
+          stderrText: normalized.diagnosticText,
         });
         runs.push({
           caseId: planCase.id,
           threadCount,
           exitClass,
           exitDetail,
-          stdout: outcome.stdout,
-          stderr: outcome.stderr,
+          stdout: normalized.stdout,
+          stderr: normalized.stderr,
           stateFiles: null,
         });
       }
@@ -306,18 +310,19 @@ export async function runDockerWasmEdgeLane(context) {
           stdinBytes: planCase.stdinBytes,
           timeoutMs: context.timeoutMs,
         });
+        const normalized = normalizeWasmEdgeOutcome(outcome);
         const { exitClass, exitDetail } = classifyProcessOutcome({
           code: outcome.code,
           signal: outcome.signal,
-          stderrText: Buffer.from(outcome.stderr).toString("utf8"),
+          stderrText: normalized.diagnosticText,
         });
         runs.push({
           caseId: planCase.id,
           threadCount,
           exitClass,
           exitDetail,
-          stdout: outcome.stdout,
-          stderr: outcome.stderr,
+          stdout: normalized.stdout,
+          stderr: normalized.stderr,
           stateFiles: null,
         });
       }

package/src/testing/wasmedgeOutput.js

@@ -0,0 +1,77 @@
+/**
+ * WasmEdge CLI output normalization — an SDK HOST SHIM, which is the only
+ * place a runtime difference is ever allowed to be absorbed.
+ *
+ * MEASURED (WasmEdge 0.16.4, native and in the pinned container): the CLI
+ * writes its own diagnostics — `[2026-08-08 00:00:00.000] [error] …` — to
+ * **stdout**, not stderr. Two consequences, both of which produced wrong
+ * answers before this shim existed:
+ *
+ *  1. A classifier that reads only stderr sees NOTHING when instantiation
+ *     fails, so a module that cannot link reads as a clean run. That is a
+ *     FALSE PASS in the isomorphism gate — the worst possible defect in an
+ *     acceptance instrument, and exactly the failure class this stack keeps
+ *     hitting: a measurement that reads as evidence.
+ *  2. Those diagnostic lines land inside the bytes the parity harness
+ *     byte-compares. A browser lane that reports the same failure through a
+ *     different channel would then look like an OUTPUT divergence, sending a
+ *     reader hunting for a nonexistent computational difference.
+ *
+ * So: strip the runtime's own log lines out of the guest's stdout, hand them
+ * back as diagnostics, and compare the guest bytes. The guest's own output is
+ * untouched — nothing here inspects or rewrites a single byte the module
+ * wrote.
+ */
+
+const DIAGNOSTIC_LINE =
+  /^\[\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d+\] \[(error|warning|warn|info|debug|critical)\]/;
+
+const decoder = new TextDecoder("utf-8", { fatal: false });
+const encoder = new TextEncoder();
+
+/**
+ * Split WasmEdge's own diagnostic lines out of a captured stdout buffer.
+ *
+ * @returns {{stdout: Uint8Array, diagnostics: string}}
+ */
+export function splitWasmEdgeDiagnostics(stdoutBytes) {
+  const bytes = stdoutBytes ?? new Uint8Array(0);
+  const text = decoder.decode(bytes);
+  if (!DIAGNOSTIC_LINE.test(text) && !text.includes("] [error]")) {
+    return { stdout: bytes, diagnostics: "" };
+  }
+  const guestLines = [];
+  const diagnosticLines = [];
+  // Preserve a trailing newline distinction: split on "\n" and rejoin, so a
+  // guest payload without a final newline stays without one.
+  const lines = text.split("\n");
+  const lastIndex = lines.length - 1;
+  for (let index = 0; index <= lastIndex; index += 1) {
+    const line = lines[index];
+    if (DIAGNOSTIC_LINE.test(line)) diagnosticLines.push(line);
+    else guestLines.push(line);
+  }
+  // If every non-diagnostic line is empty the guest produced nothing.
+  const rejoined = guestLines.join("\n");
+  const guestText = guestLines.every((line) => line.length === 0) ? "" : rejoined;
+  return {
+    stdout: encoder.encode(guestText),
+    diagnostics: diagnosticLines.join("\n"),
+  };
+}
+
+/**
+ * Normalize one WasmEdge process outcome: guest stdout with the runtime's
+ * diagnostics removed, and a combined diagnostic text (stderr + whatever the
+ * runtime logged to stdout) for classification.
+ */
+export function normalizeWasmEdgeOutcome({ stdout, stderr }) {
+  const { stdout: guestStdout, diagnostics } = splitWasmEdgeDiagnostics(stdout);
+  const stderrText = decoder.decode(stderr ?? new Uint8Array(0));
+  const combined = [stderrText, diagnostics].filter(Boolean).join("\n");
+  return {
+    stdout: guestStdout,
+    stderr: encoder.encode(combined),
+    diagnosticText: combined,
+  };
+}