space-data-module-sdk 0.8.4 → 0.8.6

package/src/testing/docker/wasmedge-parity.Dockerfile

@@ -0,0 +1,39 @@
+# Tri-runtime parity harness: Docker WasmEdge lane image.
+#
+# The WasmEdge version is NOT pinned here — it is injected from
+# src/testing/wasmedgePin.json (the single pin source) via --build-arg by
+# the parity harness (`ensureDockerParityImage`). Building this file by hand
+# with a different version produces an image the harness will reject at
+# version-check time.
+FROM ubuntu:24.04
+
+ARG WASMEDGE_VERSION
+RUN test -n "${WASMEDGE_VERSION}" || (echo "WASMEDGE_VERSION build-arg is required (injected from src/testing/wasmedgePin.json)" && exit 1)
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN set -eux; \
+    arch="$(uname -m)"; \
+    case "${arch}" in \
+      x86_64) triple="manylinux_2_28_x86_64" ;; \
+      aarch64) triple="manylinux_2_28_aarch64" ;; \
+      *) echo "unsupported architecture: ${arch}"; exit 1 ;; \
+    esac; \
+    curl -sSfL \
+      "https://github.com/WasmEdge/WasmEdge/releases/download/${WASMEDGE_VERSION}/WasmEdge-${WASMEDGE_VERSION}-${triple}.tar.gz" \
+      -o /tmp/wasmedge.tar.gz; \
+    mkdir -p /opt/wasmedge; \
+    # The manylinux release tarballs are rootless (bin/, lib64/, include/ at
+    # the archive top level) — extract as-is, no component stripping.
+    tar -xzf /tmp/wasmedge.tar.gz -C /opt/wasmedge; \
+    rm /tmp/wasmedge.tar.gz; \
+    LD_LIBRARY_PATH=/opt/wasmedge/lib64:/opt/wasmedge/lib /opt/wasmedge/bin/wasmedge --version
+
+ENV PATH="/opt/wasmedge/bin:${PATH}" \
+    LD_LIBRARY_PATH="/opt/wasmedge/lib64:/opt/wasmedge/lib"
+
+# The parity harness always runs this image with an explicit wasmedge argv
+# (flags + guest module + guest args) so the container is a pure runtime shell.
+ENTRYPOINT ["wasmedge"]

package/src/testing/index.d.ts

@@ -8,6 +8,9 @@ import type {
 export interface HarnessInputFrame {
   portId?: string | null;
   typeRef?: PayloadTypeRef | null;
+  alignment?: number;
+  offset?: number;
+  size?: number;
   payload?: Uint8Array | ArrayBuffer | ArrayBufferView | string | null;
 }
 
@@ -187,6 +190,12 @@ export interface PluginInvokeProcessClient {
   invokeRaw(requestBytes: Uint8Array | ArrayBuffer | ArrayBufferView): Promise<Uint8Array>;
   invoke(request: {
     methodId?: string | null;
+    /**
+     * Browser direct invoke requires this to be a full view of the active
+     * SharedArrayBuffer-backed module memory; foreign arenas and
+     * payload-bearing frames are rejected.
+     */
+    externalArena?: Uint8Array | ArrayBuffer | ArrayBufferView;
     inputs?: HarnessInputFrame[];
   }): Promise<{
       statusCode: number;
@@ -250,6 +259,7 @@ export interface ModuleHarness {
   invokeRaw(requestBytes: Uint8Array | ArrayBuffer | ArrayBufferView): Promise<Uint8Array>;
   invoke(request: {
     methodId?: string | null;
+    externalArena?: Uint8Array | ArrayBuffer | ArrayBufferView;
     inputs?: HarnessInputFrame[];
   }): Promise<{
       statusCode: number;
@@ -339,8 +349,24 @@ export interface BrowserModuleHarness {
   invokeRaw(
     requestBytes: Uint8Array | ArrayBuffer | ArrayBufferView,
   ): Promise<Uint8Array>;
+  invokeDirect(request: {
+    methodId?: string | null;
+    /**
+     * Browser direct invoke requires this to be a full view of the active
+     * SharedArrayBuffer-backed module memory; foreign arenas and
+     * payload-bearing frames are rejected.
+     */
+    externalArena?: Uint8Array | ArrayBuffer | ArrayBufferView;
+    inputs?: HarnessInputFrame[];
+  }): Promise<{
+    statusCode: number;
+    errorCode?: string | null;
+    errorMessage?: string | null;
+    outputs: HarnessInputFrame[];
+  }>;
   invoke(request: {
     methodId?: string | null;
+    externalArena?: Uint8Array | ArrayBuffer | ArrayBufferView;
     inputs?: HarnessInputFrame[];
   }): Promise<{
     statusCode: number;
@@ -418,11 +444,18 @@ export function createBrowserModuleHarness(options?: {
   hostOptions?: unknown;
   args?: string[];
   env?: Record<string, string>;
+  manifest?: Record<string, unknown>;
   surface?: "direct" | "command";
   performance?: {
     now(): number;
     timeOrigin: number;
   };
+  wasmMemory?: WebAssembly.Memory;
+  memory?: WebAssembly.Memory;
+  sharedMemory?: boolean;
+  allowRawInvoke?: boolean;
+  initialMemoryBytes?: number;
+  maximumMemoryBytes?: number;
   logOutput?: boolean;
 }): Promise<BrowserModuleHarness>;
 
@@ -446,3 +479,121 @@ export function buildWasmEdgeEmscriptenPthreadRunner(options: {
   output?: string;
   cwd?: string;
 }): Promise<string>;
+
+// --- Tri-runtime parity harness (browser / WasmEdge / Docker WasmEdge) -------
+
+export declare const PARITY_LANES: readonly ["browser", "wasmedge", "docker-wasmedge"];
+export type ParityLaneName = (typeof PARITY_LANES)[number];
+
+export declare const ParityExitClass: Readonly<{
+  Ok: "ok";
+  GuestError: "guest-error";
+  Trap: "trap";
+  HarnessFailure: "harness-failure";
+}>;
+
+export interface WasmEdgePin {
+  wasmedgeVersion: string;
+  dockerImageRepository: string;
+  dockerImage: string;
+  dockerfilePath: string;
+  dockerfileContextDir: string;
+  pinPath: string;
+}
+
+export interface ParityPlanCase {
+  id: string;
+  stdinBytes: Uint8Array;
+  env: Record<string, string>;
+  args: readonly string[];
+  expect: "ok" | "guest-error" | "trap" | null;
+  threadCounts: readonly number[];
+}
+
+export interface ParityPlan {
+  name: string;
+  threadEnvVar: string;
+  cases: readonly ParityPlanCase[];
+}
+
+export interface ParityRunResult {
+  lane?: ParityLaneName;
+  caseId: string;
+  threadCount: number;
+  exitClass: string;
+  exitDetail?: string | null;
+  stdout: Uint8Array;
+  stderr?: Uint8Array;
+  stateFiles?: Record<string, string> | null;
+}
+
+export interface ParityFailure {
+  caseId?: string;
+  kind: string;
+  message: string;
+}
+
+export interface ParityReport {
+  ok: boolean;
+  fixture: string;
+  wasmPath: string;
+  artifactSha256: string;
+  moduleSha256: string;
+  pin: string;
+  lanes: Array<{ lane: string; runs: number; durationMs: number }>;
+  cases: string[];
+  comparisons: number;
+  failures: ParityFailure[];
+  runs: Array<{
+    lane: string;
+    caseId: string;
+    threadCount: number;
+    exitClass: string;
+    exitDetail: string | null;
+    stdoutSha256: string;
+    stdoutLength: number;
+  }>;
+}
+
+export declare function loadWasmEdgePin(): WasmEdgePin;
+export declare function assertWasmEdgeVersionMatchesPin(
+  versionOutput: string,
+  pin: WasmEdgePin,
+  context: string,
+): string;
+export declare function normalizeParityFixture(
+  fixture: unknown,
+  options?: { fixtureDir?: string },
+): Promise<ParityPlan>;
+export declare function loadParityFixture(fixturePath: string): Promise<ParityPlan>;
+export declare function diffParityRuns(
+  plan: ParityPlan,
+  runs: ParityRunResult[],
+): { ok: boolean; failures: ParityFailure[]; comparisons: number };
+export declare function formatParityReport(report: ParityReport): string;
+export declare function runParityHarness(options: {
+  wasmPath: string;
+  plan?: ParityPlan;
+  fixturePath?: string;
+  lanes?: string[];
+  laneRunners?: Record<string, (context: unknown) => Promise<ParityRunResult[]>>;
+  injectDivergence?: string;
+  chromeBinary?: string;
+  wasmedgeBinary?: string;
+  dockerBinary?: string;
+  dockerPlatform?: string;
+  autoBuildDockerImage?: boolean;
+  allowSingleLane?: boolean;
+  timeoutMs?: number;
+  log?: (line: string) => void;
+}): Promise<ParityReport>;
+
+export declare const defaultParityLaneRunners: Readonly<
+  Record<ParityLaneName, (context: unknown) => Promise<ParityRunResult[]>>
+>;
+export declare function ensureDockerParityImage(context: unknown): Promise<string>;
+export declare function resolveChromeBinary(context?: unknown): Promise<string>;
+export declare function resolveWasmEdgeBinary(context?: unknown): Promise<string>;
+export declare function runBrowserLane(context: unknown): Promise<ParityRunResult[]>;
+export declare function runDockerWasmEdgeLane(context: unknown): Promise<ParityRunResult[]>;
+export declare function runNativeWasmEdgeLane(context: unknown): Promise<ParityRunResult[]>;

package/src/testing/index.js

@@ -11,6 +11,7 @@ export {
   createBrowserModuleHarness,
   detectArtifactProfile,
 } from "./browserModuleHarness.js";
+export { createWorkerModuleHarness } from "./workerModuleHarness.js";
 export {
   buildWasmEdgeSpawnEnv,
   createPluginInvokeProcessClient,
@@ -27,6 +28,26 @@ export {
   resolveModuleHarnessLaunchPlan,
 } from "./moduleHarness.js";
 export { createModuleFlatBufferStreamPump } from "./moduleFlatbufferStreamPump.js";
+export {
+  PARITY_LANES,
+  ExitClass as ParityExitClass,
+  assertWasmEdgeVersionMatchesPin,
+  diffParityRuns,
+  formatParityReport,
+  loadParityFixture,
+  loadWasmEdgePin,
+  normalizeParityFixture,
+  runParityHarness,
+} from "./parityHarness.js";
+export {
+  defaultParityLaneRunners,
+  ensureDockerParityImage,
+  resolveChromeBinary,
+  resolveWasmEdgeBinary,
+  runBrowserLane,
+  runDockerWasmEdgeLane,
+  runNativeWasmEdgeLane,
+} from "./parityLanes.js";
 
 const CapabilitySurfaceMatrix = Object.freeze({
   logging: Object.freeze({

package/src/testing/native/wasmedge_emscripten_pthread_runner.c

@@ -1493,6 +1493,31 @@ static bool invoke_optional_module_init(
     WasmEdge_ExecutorContext *executor,
     WasmEdge_ModuleInstanceContext *module,
     bool service_mode) {
+  // Reactor artifacts (the isomorphic-pthreads wasi-threads default, built with
+  // -mexec-model=reactor) export `_initialize` and NO `_start`. `_initialize`
+  // runs the global constructors AND the WASI reactor init; it is the canonical,
+  // complete init entry. It MUST be invoked or global ctors never execute under
+  // WasmEdge (static registration / std::once / SDS + FlatSQL statics silently
+  // stay uninitialized). This applies in BOTH the service_mode (resident plugin)
+  // and one-shot paths. Command modules (which export `_start`) keep their
+  // EXISTING behavior exactly: the `_initialize` branch is only taken when there
+  // is no `_start`.
+  WasmEdge_FunctionInstanceContext *start = find_function(module, "_start");
+  if (start == NULL) {
+    WasmEdge_FunctionInstanceContext *initialize =
+        find_function(module, "_initialize");
+    if (initialize != NULL) {
+      return invoke_function(
+          executor,
+          initialize,
+          NULL,
+          0,
+          NULL,
+          0,
+          "_initialize");
+    }
+  }
+
   if (service_mode) {
     WasmEdge_FunctionInstanceContext *ctors =
         find_function(module, "__wasm_call_ctors");
@@ -1509,7 +1534,6 @@ static bool invoke_optional_module_init(
     return true;
   }
 
-  WasmEdge_FunctionInstanceContext *start = find_function(module, "_start");
   if (start != NULL) {
     return invoke_function(executor, start, NULL, 0, NULL, 0, "_start");
   }

package/src/testing/parityBrowserRunner.js

@@ -0,0 +1,138 @@
+/**
+ * Browser-side entry for the tri-runtime parity harness.
+ *
+ * esbuild-bundled by parityLanes.js and served to a REAL headless Chrome
+ * behind COOP/COEP headers (cross-origin isolated, SharedArrayBuffer-capable).
+ * Never executed under jsdom — jsdom masks Illegal-invocation and threading
+ * realities, which is exactly what this lane exists to catch.
+ *
+ * Protocol with the lane server (same origin):
+ *   GET  /plan        -> {threadEnvVar, cases:[{id, stdinBase64, env, args, threadCounts}]}
+ *   GET  /module.wasm -> the ONE isomorphic artifact
+ *   POST /done        -> {runs:[...]} on completion or {fatal} on runner failure
+ */
+
+import { createBrowserModuleHarness } from "./browserModuleHarness.js";
+
+const OK = "ok";
+const GUEST_ERROR = "guest-error";
+const TRAP = "trap";
+
+function base64ToBytes(value) {
+  const binary = atob(String(value ?? ""));
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+function bytesToBase64(bytes) {
+  let binary = "";
+  const chunk = 0x8000;
+  for (let index = 0; index < bytes.length; index += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + chunk));
+  }
+  return btoa(binary);
+}
+
+function classifyBrowserError(error) {
+  // WasiExitError with code 0 is swallowed inside the harness; reaching here
+  // with one means a real nonzero guest exit.
+  if (error?.name === "WasiExitError") {
+    return { exitClass: GUEST_ERROR, exitDetail: `exit=${error.code}` };
+  }
+  return {
+    exitClass: TRAP,
+    exitDetail: `${error?.name ?? "Error"}: ${error?.message ?? String(error)}`,
+  };
+}
+
+export async function runParityPlanInBrowser({ baseUrl = "" } = {}) {
+  const status = globalThis.document?.getElementById?.("status") ?? null;
+  const setStatus = (text) => {
+    if (status) status.textContent = text;
+  };
+
+  const [planResponse, moduleResponse] = await Promise.all([
+    fetch(`${baseUrl}/plan`),
+    fetch(`${baseUrl}/module.wasm`),
+  ]);
+  if (!planResponse.ok || !moduleResponse.ok) {
+    throw new Error("parity browser runner: failed to fetch plan or module.");
+  }
+  const plan = await planResponse.json();
+  const moduleBytes = new Uint8Array(await moduleResponse.arrayBuffer());
+
+  if (globalThis.crossOriginIsolated !== true) {
+    throw new Error(
+      "parity browser runner: page is not cross-origin isolated (COOP/COEP missing) — SAB-backed thread parity cannot be validated.",
+    );
+  }
+
+  const runs = [];
+  for (const planCase of plan.cases) {
+    const stdinBytes = base64ToBytes(planCase.stdinBase64);
+    for (const threadCount of planCase.threadCounts) {
+      setStatus(`case ${planCase.id} @ ${threadCount} thread(s)`);
+      let exitClass = OK;
+      let exitDetail = null;
+      let stdout = new Uint8Array(0);
+      let stderr = new Uint8Array(0);
+      let harness = null;
+      try {
+        harness = await createBrowserModuleHarness({
+          wasmSource: moduleBytes.slice(),
+          surface: "command",
+          args: planCase.args,
+          env: {
+            ...planCase.env,
+            [plan.threadEnvVar]: String(threadCount),
+          },
+        });
+        stdout = await harness.invokeRaw(stdinBytes);
+        stderr = harness.wasi?.stderr ?? new Uint8Array(0);
+      } catch (error) {
+        ({ exitClass, exitDetail } = classifyBrowserError(error));
+      } finally {
+        try {
+          harness?.destroy?.();
+        } catch {
+          /* teardown must never mask the run result */
+        }
+      }
+      runs.push({
+        caseId: planCase.id,
+        threadCount,
+        exitClass,
+        exitDetail,
+        stdoutBase64: bytesToBase64(stdout),
+        stderrBase64: bytesToBase64(stderr),
+      });
+    }
+  }
+  setStatus(`done: ${runs.length} run(s)`);
+  return runs;
+}
+
+async function postDone(body) {
+  await fetch("/done", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+// Auto-run only inside a real browser page (the served runner). Node imports
+// of this module (tests, bundlers) never auto-run.
+if (
+  typeof globalThis.document !== "undefined" &&
+  typeof globalThis.window !== "undefined" &&
+  globalThis.__SDM_PARITY_AUTORUN__ !== false
+) {
+  runParityPlanInBrowser({})
+    .then((runs) => postDone({ runs }))
+    .catch((error) =>
+      postDone({ fatal: `${error?.name ?? "Error"}: ${error?.message ?? error}` }),
+    );
+}