space-data-module-sdk 0.8.20 → 0.8.22

package/src/host/wasiThreadWorkerRuntime.js

@@ -1,4 +1,5 @@
 import { createHostcallBridge, DEFAULT_HOSTCALL_IMPORT_MODULE } from "./abi.js";
+import { mergeImportFragments, resolveExtraImports } from "./flatsqlIoImports.js";
 import {
   createSabHostcallBuffer,
   createSabHostcallClientDispatch,
@@ -54,11 +55,27 @@ function createThreadHostcallDispatch(options) {
   };
 }
 
+/**
+ * The per-worker half of the wasi-threads host: the import object one guest
+ * thread instantiates the shared module with.
+ *
+ * Every pool thread gets WASI, the shared `env.memory`, a `wasi.thread-spawn`
+ * stub, the hostcall bridge when the module imports it, and the `extraImports`
+ * entries (T9): per-worker import objects such as FlatSQL's `env.flatsql_io_*`.
+ * Each entry is a factory `(ctx) => importObject` (or `{ imports, close }`), or
+ * a built-in descriptor such as `{ provider: "flatsql-io", instanceId, channels }`
+ * (flatsqlIoImports.js). Factories run once per worker, so each worker owns its
+ * own resources (for flatsql-io: its own request-ring slot). `ctx` is
+ * `{ memory, getMemory, tid, workerIndex }`.
+ */
 export function createWasiThreadWorkerRuntime({
   wasmModule,
   memory,
   hostcallChannel,
   processState,
+  extraImports,
+  workerIndex,
+  tid,
 } = {}) {
   const wasi = createBrowserWasiShim({ processState });
   wasi.setMemory(memory);
@@ -79,7 +96,18 @@ export function createWasiThreadWorkerRuntime({
     Object.assign(imports, bridge.imports);
   }
 
+  const extras = resolveExtraImports(extraImports, {
+    memory,
+    getMemory: () => instance?.exports?.memory ?? memory,
+    workerIndex: workerIndex ?? null,
+    tid: tid ?? null,
+  });
+  mergeImportFragments(imports, extras.fragments);
+  // The shared memory is the one contract every import object must agree on.
+  imports.env.memory = memory;
+
   return {
+    imports,
     instantiate() {
       instance = new WebAssembly.Instance(wasmModule, imports);
       wasi.setMemory(instance.exports.memory ?? memory);
@@ -87,8 +115,34 @@ export function createWasiThreadWorkerRuntime({
     },
     close() {
       hostcalls?.close();
+      extras.close();
     },
   };
 }
 
+/**
+ * Resolve `{ moduleUrl, exportName?, config? }` entries by importing their
+ * factory module (module workers and Node; a classic blob worker cannot). The
+ * resolved entries are factories that receive `{ ...ctx, config }`. Other
+ * entries pass through unchanged.
+ */
+export async function resolveModuleExtraImports(extraImports) {
+  const out = [];
+  for (const entry of extraImports ?? []) {
+    if (entry && typeof entry.moduleUrl === "string") {
+      const mod = await import(/* @vite-ignore */ /* webpackIgnore: true */ entry.moduleUrl);
+      const factory = mod[entry.exportName ?? "default"];
+      if (typeof factory !== "function") {
+        throw new TypeError(
+          `extraImports module ${entry.moduleUrl} exports no factory "${entry.exportName ?? "default"}".`,
+        );
+      }
+      out.push({ factory, config: entry.config ?? null });
+    } else {
+      out.push(entry);
+    }
+  }
+  return out;
+}
+
 export const WASI_THREAD_HOSTCALL_MESSAGE = THREAD_HOSTCALL_MESSAGE;

package/src/index.d.ts

@@ -2063,6 +2063,353 @@ export function createSabHostcallServer(options: {
   dispatch: (operation: string, params: unknown) => Promise<unknown> | unknown;
 }): { handleRequest(request: { operation: string; params?: unknown }): Promise<void> };
 
+// --- FlatSQL partition store host I/O (T9; docs/isomorphic-pthreads.md) ---
+export const DEFAULT_FLATSQL_IO_CHUNK_BYTES: number;
+export const DEFAULT_FLATSQL_IO_SPIN_MICROS: number;
+export const DEFAULT_SAB_IO_CLIENT_SPIN_MICROS: number;
+export const DEFAULT_SAB_IO_DATA_BYTES: number;
+export const DEFAULT_SAB_IO_MAX_INSTANCES: number;
+export const DEFAULT_SAB_IO_SLOTS: number;
+export const FLATSQL_IO_CREATE: number;
+export const FLATSQL_IO_CREATE_PARENTS: number;
+export const FLATSQL_IO_DELETE_ON_CLOSE: number;
+export const FLATSQL_IO_ERR_ACCESS: number;
+export const FLATSQL_IO_ERR_BADHANDLE: number;
+export const FLATSQL_IO_ERR_BUSY: number;
+export const FLATSQL_IO_ERR_GENERIC: number;
+export const FLATSQL_IO_ERR_IO: number;
+export const FLATSQL_IO_ERR_NOENT: number;
+export const FLATSQL_IO_ERR_NOSPACE: number;
+export const FLATSQL_IO_EXCL: number;
+export const FLATSQL_IO_MAX_PATH_BYTES: number;
+export const FLATSQL_IO_OK: number;
+export const FLATSQL_IO_OPEN_DEFERRED: number;
+export const FLATSQL_IO_PROBE: number;
+export const FLATSQL_IO_READ: number;
+export const FLATSQL_IO_SERVER_CREATE_FLAGS: number;
+export const FLATSQL_IO_TRUNC: number;
+export const FLATSQL_IO_UNLINK: number;
+export const FLATSQL_IO_UNLINK_IF_UNUSED: number;
+export const FLATSQL_IO_WRITE: number;
+export const NODE_SYNC_FS_ANONYMOUS_INSTANCE: number;
+export const SAB_IO_DATA_MEMORY: number;
+export const SAB_IO_DATA_SLOT: number;
+export const SAB_IO_DOORBELL_ATOMICS: number;
+export const SAB_IO_DOORBELL_MESSAGE: number;
+export const SAB_IO_H_CHANNEL_ID: number;
+export const SAB_IO_H_CLAIM_HINT: number;
+export const SAB_IO_H_DATA_BYTES: number;
+export const SAB_IO_H_DOORBELL: number;
+export const SAB_IO_H_DOORBELL_MODE: number;
+export const SAB_IO_H_MAGIC: number;
+export const SAB_IO_H_MAX_INSTANCES: number;
+export const SAB_IO_H_SERVED: number;
+export const SAB_IO_H_SERVER_EPOCH: number;
+export const SAB_IO_H_SERVER_STATE: number;
+export const SAB_IO_H_SLOT_BYTES: number;
+export const SAB_IO_H_SLOT_COUNT: number;
+export const SAB_IO_H_SLOT_RELEASES: number;
+export const SAB_IO_H_VERSION: number;
+export const SAB_IO_INSTANCE_ATTACHED: number;
+export const SAB_IO_INSTANCE_NONE: number;
+export const SAB_IO_INSTANCE_REVOKED: number;
+export const SAB_IO_INSTANCE_REVOKING: number;
+export const SAB_IO_MAGIC: number;
+export const SAB_IO_NOTIFY_ATOMICS: number;
+export const SAB_IO_NOTIFY_MESSAGE: number;
+export const SAB_IO_OP_CLOSE: number;
+export const SAB_IO_OP_OPEN: number;
+export const SAB_IO_OP_READ: number;
+export const SAB_IO_OP_SIZE: number;
+export const SAB_IO_OP_SYNC: number;
+export const SAB_IO_OP_TRUNCATE: number;
+export const SAB_IO_OP_WRITE: number;
+export const SAB_IO_SCRATCH_INSTANCE: number;
+export const SAB_IO_SERVER_DEAD: number;
+export const SAB_IO_SERVER_NOT_STARTED: number;
+export const SAB_IO_SERVER_RUNNING: number;
+export const SAB_IO_SERVER_STOPPED: number;
+export const SAB_IO_SLOT_DONE: number;
+export const SAB_IO_SLOT_FREE: number;
+export const SAB_IO_SLOT_IDLE: number;
+export const SAB_IO_SLOT_PENDING: number;
+export const SAB_IO_SLOT_SERVICING: number;
+export const SAB_IO_STATUS_DEAD: number;
+export const SAB_IO_STATUS_REVOKED: number;
+export const SAB_IO_S_DATA_MODE: number;
+export const SAB_IO_S_DONE_SEQ: number;
+export const SAB_IO_S_F64_OFFSET: number;
+export const SAB_IO_S_F64_RESULT: number;
+export const SAB_IO_S_FLAGS: number;
+export const SAB_IO_S_HANDLE: number;
+export const SAB_IO_S_INSTANCE: number;
+export const SAB_IO_S_LEN: number;
+export const SAB_IO_S_NOTIFY: number;
+export const SAB_IO_S_OP: number;
+export const SAB_IO_S_OWNER: number;
+export const SAB_IO_S_PATH_LEN: number;
+export const SAB_IO_S_PTR: number;
+export const SAB_IO_S_SEQ: number;
+export const SAB_IO_S_STATE: number;
+export const SAB_IO_S_STATUS: number;
+export const SAB_IO_VERSION: number;
+export const SAB_IO_WAIT_SLICE_MS: number;
+export const FLATSQL_IO_IMPORT_MODULE: string;
+export const FLATSQL_IO_PROVIDER_DESCRIPTOR: string;
+export const FLATSQL_IO_WORKER_FILENAME: string;
+export const NODE_SYNC_FS_PROVIDER_DESCRIPTOR: string;
+export const OPFS_SHARED_HANDLE_MODE: string;
+export const FLATSQL_IO_FLAGS: Readonly<Record<string, number>>;
+export const FLATSQL_IO_STATUS: Readonly<Record<string, number>>;
+export const FLATSQL_IO_IMPORT_NAMES: readonly string[];
+export const FLATSQL_IO_TRACE_OPS: Readonly<Record<string, number>>;
+
+/** Synchronous provider behind the seven env.flatsql_io_* imports. */
+export interface FlatsqlIoProvider {
+  open(path: Uint8Array | string, flags: number): number;
+  read(handle: number, ptr: number, len: number, offset: number): number;
+  write(handle: number, ptr: number, len: number, offset: number): number;
+  truncate(handle: number, size: number): number;
+  sync(handle: number): number;
+  size(handle: number): number;
+  close(handle: number): number;
+}
+export interface FlatsqlIoSyncClient extends FlatsqlIoProvider {
+  readonly instanceId: number;
+  readonly requests: number;
+  readInto(handle: number, view: Uint8Array, offset: number): number;
+  writeFrom(handle: number, view: Uint8Array, offset: number): number;
+  release(): void;
+}
+export interface FlatsqlIoAsyncClient {
+  readonly instanceId: number;
+  open(path: Uint8Array | string, flags: number): Promise<number>;
+  read(handle: number, length: number, offset: number): Promise<Uint8Array | number>;
+  write(handle: number, bytes: Uint8Array, offset: number): Promise<number>;
+  truncate(handle: number, size: number): Promise<number>;
+  sync(handle: number): Promise<number>;
+  size(handle: number): Promise<number>;
+  close(handle: number): Promise<number>;
+  close$(): void;
+}
+export interface FlatsqlIoBackendFile {
+  read(view: Uint8Array, options?: { at?: number }): number;
+  write(view: Uint8Array, options?: { at?: number }): number;
+  truncate(size: number): void;
+  flush(): void;
+  getSize(): number;
+  close(): void;
+}
+export interface FlatsqlIoBackend {
+  kind: string;
+  init?(): Promise<Record<string, unknown>>;
+  openFile(path: string, components: string[], flags: number): FlatsqlIoBackendFile | Promise<FlatsqlIoBackendFile>;
+  exists(path: string, components: string[]): boolean | Promise<boolean>;
+  remove(path: string, components: string[]): void | Promise<void>;
+}
+export interface FlatsqlIoMirrorOptions {
+  buffer: SharedArrayBuffer;
+  suffixes?: string[];
+  write?: boolean;
+}
+export type FlatsqlIoExtraImport =
+  | { provider: "flatsql-io"; instanceId?: number; channels: SharedArrayBuffer[]; mirror?: FlatsqlIoMirrorOptions; trace?: { buffer: SharedArrayBuffer } }
+  | { provider: "flatsql-io-node"; root: string; table: SharedArrayBuffer; instanceId?: number; mirror?: FlatsqlIoMirrorOptions; trace?: { buffer: SharedArrayBuffer } }
+  | { moduleUrl: string; exportName?: string; config?: unknown };
+
+export class FlatsqlIoStatusError extends Error {
+  constructor(status: number, message?: string);
+  status: number;
+}
+export function flatsqlIoStatusForError(error: unknown, options?: { during?: "open" }): number;
+export function flatsqlIoStatusOf(error: unknown, options?: { during?: "open" }): number;
+export function splitFlatsqlIoPath(path: string): string[] | number;
+export function decodeFlatsqlIoPath(bytes: Uint8Array): string | number;
+export function hashFlatsqlIoPath(bytes: Uint8Array): number;
+
+export function createSabIoChannelBuffer(options?: { slots?: number; dataBytes?: number; maxInstances?: number }): SharedArrayBuffer;
+export function describeSabIoChannel(buffer: SharedArrayBuffer): Record<string, unknown>;
+export function sabIoDoorbellChannelName(channelId: number): string;
+export function sabIoCompletionChannelName(channelId: number): string;
+export function createSabIoClient(options: { buffer: SharedArrayBuffer; instanceId?: number; getMemory?: () => WebAssembly.Memory | null; spinMicros?: number }): FlatsqlIoSyncClient;
+export function createSabIoAsyncClient(options: { buffer: SharedArrayBuffer; instanceId?: number; forceMessages?: boolean }): FlatsqlIoAsyncClient;
+export function sabIoInstanceState(buffer: SharedArrayBuffer, instanceId: number): number;
+export function revokeSabIoInstance(buffer: SharedArrayBuffer, instanceId: number, options?: { pollMs?: number }): Promise<void>;
+export function resetSabIoInstance(buffer: SharedArrayBuffer, instanceId: number): void;
+export function failPendingSabIoRequests(buffer: SharedArrayBuffer, status?: number): number;
+export function reclaimSabIoSlots(buffer: SharedArrayBuffer, instanceId: number): number;
+export function completeSabIoSlot(layout: unknown, slot: unknown, status: number, f64Result?: number): void;
+
+export function createSabIoMirrorBuffer(options?: { entries?: number; entryBytes?: number; maxPathBytes?: number }): SharedArrayBuffer;
+export function sabIoMirrorEntryBytes(buffer: SharedArrayBuffer): number;
+export function findSabIoMirrorEntry(buffer: SharedArrayBuffer, path: string | Uint8Array): number;
+export function updateSabIoMirror(buffer: SharedArrayBuffer, path: string | Uint8Array, offset: number, bytes: Uint8Array, options?: { truncateTo?: number }): boolean;
+export function clearSabIoMirror(buffer: SharedArrayBuffer, path: string | Uint8Array): void;
+export function readSabIoMirror(buffer: SharedArrayBuffer, path: string | Uint8Array, dst: Uint8Array, offset: number): number;
+export function readSabIoMirrorEntry(buffer: SharedArrayBuffer, index: number, dst: Uint8Array, offset: number): number;
+export function createSabIoMirrorMatcher(suffixes?: string[]): (path: string) => boolean;
+
+export function createFlatsqlIoImports(options: {
+  getMemory: () => WebAssembly.Memory;
+  provider: FlatsqlIoProvider | FlatsqlIoProvider[];
+  mirror?: FlatsqlIoMirrorOptions;
+  trace?: { buffer: SharedArrayBuffer };
+}): { env: Record<string, (...args: number[]) => number> };
+export function resolveFlatsqlIoDescriptor(descriptor: FlatsqlIoExtraImport, ctx: { getMemory: () => WebAssembly.Memory }): { imports: WebAssembly.Imports; close(): void };
+export function resolveExtraImports(extraImports: Array<FlatsqlIoExtraImport | ((ctx: unknown) => unknown)>, ctx: { memory: WebAssembly.Memory; getMemory: () => WebAssembly.Memory; tid?: number | null; workerIndex?: number | null }): { fragments: WebAssembly.Imports[]; close(): void };
+export function mergeImportFragments(imports: WebAssembly.Imports, fragments: WebAssembly.Imports[]): WebAssembly.Imports;
+export function createFlatsqlIoTraceBuffer(capacity?: number): SharedArrayBuffer;
+export function readFlatsqlIoTrace(buffer: SharedArrayBuffer): { recorded: number; capacity: number; samples: Array<{ op: number; micros: number }> };
+
+export interface FlatsqlIoServer {
+  readonly doorbellMode: number;
+  readonly stats: Record<string, number | boolean>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  attachMemory(instanceId: number, memory: WebAssembly.Memory | SharedArrayBuffer): boolean;
+  detachMemory(instanceId: number): void;
+  preopen(paths: string[], flags?: number): Promise<number[]>;
+  releasePreopen(paths: string[]): void;
+  inventory(): { files: Array<{ path: string; refs: number; pins: number; opening: boolean; openStatus: number }>; handles: number };
+}
+export function createFlatsqlIoServer(options: {
+  buffer: SharedArrayBuffer;
+  backend: FlatsqlIoBackend;
+  chunkBytes?: number;
+  doorbell?: "auto" | "atomics" | "message";
+  mirror?: { buffer: SharedArrayBuffer; match(path: string): boolean; write?: boolean };
+  spinMicros?: number;
+  onEvent?: (event: Record<string, unknown>) => void;
+}): FlatsqlIoServer;
+export function createFlatsqlIoMemoryBackend(options?: { maxBytes?: number }): FlatsqlIoBackend & {
+  reset(): void;
+  usage(): { files: number; allocatedBytes: number };
+  list(): string[];
+};
+export function createOpfsIoBackend(options?: {
+  rootDirectory?: string;
+  handleMode?: "auto" | "shared" | "exclusive";
+  openDelayMs?: (path: string) => number;
+  root?: unknown;
+  busyRetry?: { attempts: number; baseMs?: number };
+}): FlatsqlIoBackend & { readonly sharedModes: boolean; readonly sharedViews: boolean | null; clear(): Promise<void> };
+export function probeOpfsSharedHandleModes(root: unknown, name?: string): Promise<{ supported: boolean; detail: string }>;
+export function probeOpfsSharedViews(root: unknown, name?: string): Promise<boolean>;
+
+export class FlatsqlIoWorkerStartError extends Error {
+  lockUnavailable?: boolean;
+}
+export interface FlatsqlIoWorkerController {
+  readonly buffer: SharedArrayBuffer;
+  readonly info: Record<string, unknown> | null;
+  readonly dead: boolean;
+  readonly restarts: number;
+  readonly worker: unknown;
+  attachMemory(instanceId: number, memory: WebAssembly.Memory | SharedArrayBuffer): Promise<boolean>;
+  detachMemory(instanceId: number): void;
+  revoke(instanceId: number): Promise<void>;
+  preopen(paths: string[], flags?: number): Promise<number[]>;
+  releasePreopen(paths: string[]): void;
+  stats(): Promise<Record<string, unknown>>;
+  reset(): Promise<void>;
+  clear(): Promise<unknown>;
+  stop(): Promise<void>;
+  kill(): void;
+}
+export function createFlatsqlIoWorker(options?: {
+  buffer?: SharedArrayBuffer;
+  channel?: { slots?: number; dataBytes?: number; maxInstances?: number };
+  backend?: "opfs" | "memory";
+  role?: "writer" | "reader";
+  chunkBytes?: number;
+  doorbell?: "auto" | "atomics" | "message";
+  mirror?: FlatsqlIoMirrorOptions;
+  rootDirectory?: string;
+  handleMode?: "auto" | "shared" | "exclusive";
+  memoryMaxBytes?: number;
+  openDelay?: { pattern: string; ms: number } | null;
+  lock?: { name: string; ifAvailable?: boolean } | null;
+  busyRetry?: { attempts: number; baseMs?: number } | null;
+  workerUrl?: string | URL;
+  workerType?: "module" | "classic";
+  onError?: (error: unknown, info: { restarted: boolean; failedRequests: number }) => void;
+  restart?: boolean;
+}): Promise<FlatsqlIoWorkerController>;
+
+export const FLATSQL_IO_CONFORMANCE_CASES: ReadonlyArray<{ name: string; run(io: unknown, dir: string): Promise<void> }>;
+export function runFlatsqlIoConformance(io: unknown, options?: { prefix?: string; skip?: string[] }): Promise<{ passed: string[]; failed: Array<{ name: string; error: string }>; skipped: string[] }>;
+export function conformanceAdapterForAsyncClient(client: FlatsqlIoAsyncClient): unknown;
+
+export function probeWorkerCapabilities(): Promise<Record<string, unknown>>;
+export function workerCapabilityProbeSource(): string;
+export function probeBrowserCapabilities(options?: { timeoutMs?: number }): Promise<{
+  page: Record<string, unknown>;
+  worker: Record<string, unknown> | null;
+  localStore: { supported: boolean; missing: string[]; doorbell: "atomics" | "message"; transfer: "direct" | "scratch" };
+}>;
+export function flatsqlLocalStoreGate(matrix: { page: Record<string, unknown>; worker: Record<string, unknown> | null }): {
+  supported: boolean;
+  missing: string[];
+  doorbell: "atomics" | "message";
+  transfer: "direct" | "scratch";
+};
+
+export function createNodeSyncFsIoTable(options?: { maxHandles?: number; maxPathBytes?: number; maxInstances?: number }): SharedArrayBuffer;
+export function createNodeSyncFsIo(options: {
+  root: string;
+  table: SharedArrayBuffer;
+  instanceId?: number;
+  getMemory?: () => WebAssembly.Memory | null;
+  interpose?: (op: string, fn: (...args: unknown[]) => unknown, args: unknown[]) => unknown;
+}): FlatsqlIoProvider & {
+  readInto(handle: number, view: Uint8Array, offset: number): number;
+  writeFrom(handle: number, view: Uint8Array, offset: number): number;
+  closeLocalFds(): void;
+  liveHandles(): number;
+  localFdCount(): number;
+};
+export function revokeNodeSyncFsIoInstance(table: SharedArrayBuffer, instanceId: number): void;
+export function resetNodeSyncFsIoInstance(table: SharedArrayBuffer, instanceId: number): void;
+export function resolveNodeFlatsqlIoDescriptors(entries: unknown[]): unknown[];
+
+export interface WasiThreadSpawnReport {
+  poolSize: number | null;
+  armed: number;
+  failedToArm: number;
+  spawned: number;
+  declined: number;
+  declinedByReason: Record<string, number>;
+  lastDeclineReason: string | null;
+  active: number;
+  idle?: number;
+}
+export function isWasiThreadsModule(wasmModule: WebAssembly.Module): boolean;
+export function createWasiThreadSpawn(options: {
+  wasmModule: WebAssembly.Module;
+  memory: WebAssembly.Memory;
+  requestedThreads?: number;
+  poolSize?: number;
+  extraImports?: FlatsqlIoExtraImport[];
+  instanceId?: number;
+  onGuestError?: (instanceId: number | null, tid: number | null, error: unknown) => void;
+  onSpawnDeclined?: (event: { reason: string; poolSize: number | null; declined: number }) => void;
+  probeTimeoutMs?: number;
+  hostcallChannel?: unknown;
+  processState?: unknown;
+  requiresHostcalls?: boolean;
+  enableBrowserThreads?: boolean;
+  browserWorkerBaseUrl?: string | URL;
+  browserWorkerUrl?: string | URL;
+  browserWorkerType?: "module" | "classic";
+}): Promise<{
+  threadSpawn(startArg: number): number;
+  activeThreadCount(): number;
+  spawnCount(): number;
+  distinctOsThreadCount(): number;
+  spawnReport(): WasiThreadSpawnReport;
+  terminateAll(): Promise<void>;
+}>;
+
 // --- Browser cron/timer driver (WS6.3) ---
 export interface ModuleTimerRunRecord {
   timerId: string;
@@ -2790,6 +3137,8 @@ export const DefaultInvokeExports: {
   allocSymbol: string;
   freeSymbol: string;
   commandSymbol: string;
+  reactorInitializeSymbol: string;
+  constructorsSymbol: string;
 };
 
 export const DrainPolicy: {

package/src/runtime/constants.js

@@ -74,4 +74,10 @@ export const DefaultInvokeExports = Object.freeze({
   allocSymbol: "plugin_alloc",
   freeSymbol: "plugin_free",
   commandSymbol: "_start",
+  // Direct-surface initialization. A reactor exports `_initialize`; a command
+  // artifact that also serves the direct surface exports `__wasm_call_ctors`
+  // (its `_start` would run main). A direct host calls the first one present,
+  // once per instance, before the first direct call.
+  reactorInitializeSymbol: "_initialize",
+  constructorsSymbol: "__wasm_call_ctors",
 });

package/src/testing/native/wasmedge_wasi_threads_runner.c

@@ -150,9 +150,12 @@ static WasmEdge_ModuleInstanceContext *memory_import(Threads *g) {
   return env;
 }
 
-// Reactor artifacts use the same PIV request/response bytes as commands. Stage
-// the request through the public allocator, then monitor the direct call with
-// the same worker-group lifecycle as _start. No guest ABI is reimplemented.
+// Direct calls use the same PIV request/response bytes as commands. Stage the
+// request through the public allocator, then monitor the direct call with the
+// same worker-group lifecycle as _start. No guest ABI is reimplemented. The
+// module initializes first, once: a reactor through _initialize, a command
+// artifact serving the direct surface through __wasm_call_ctors (its _start
+// would run main).
 static uint32_t stage_direct_request(Threads *g,
     WasmEdge_ModuleInstanceContext *instance,
     WasmEdge_MemoryInstanceContext *memory, WasmEdge_Value args[3]) {
@@ -171,6 +174,7 @@ static uint32_t stage_direct_request(Threads *g,
   }
   const WasmEdge_FunctionInstanceContext *init =
       WasmEdge_ModuleInstanceFindFunction(instance, name("_initialize"));
+  if (!init) init = WasmEdge_ModuleInstanceFindFunction(instance, name("__wasm_call_ctors"));
   if (init) require_result("initialize", WasmEdge_ExecutorInvoke(g->executor, init, NULL, 0, NULL, 0));
   const WasmEdge_FunctionInstanceContext *alloc =
       WasmEdge_ModuleInstanceFindFunction(instance, name("plugin_alloc"));
@@ -224,10 +228,12 @@ int main(int argc, char **argv) {
   if (!envs) return 1;
   uint32_t env_count = 0;
   bool stats = false;
+  bool force_direct = false;
   int first = 1;
   for (; first < argc; ++first) {
     if (strcmp(argv[first], "--enable-threads") == 0) continue;
     if (strcmp(argv[first], "--sdm-thread-stats") == 0) { stats = true; continue; }
+    if (strcmp(argv[first], "--sdm-direct") == 0) { force_direct = true; continue; }
     if (strcmp(argv[first], "--env") == 0 && first + 1 < argc) {
       envs[env_count++] = argv[++first];
       continue;
@@ -235,7 +241,7 @@ int main(int argc, char **argv) {
     break;
   }
   if (first >= argc || argv[first][0] == '-') {
-    fprintf(stderr, "usage: %s [--env NAME=VALUE] module.wasm [args...]\n", argv[0]);
+    fprintf(stderr, "usage: %s [--sdm-direct] [--env NAME=VALUE] module.wasm [args...]\n", argv[0]);
     free(envs);
     return 2;
   }
@@ -269,7 +275,9 @@ int main(int argc, char **argv) {
   WasmEdge_ModuleInstanceContext *instance = NULL;
   require_result("instantiate", WasmEdge_ExecutorInstantiate(
       g.executor, &instance, g.store, g.ast));
-  const WasmEdge_FunctionInstanceContext *start =
+  // --sdm-direct serves the direct surface of an artifact that also has a
+  // command entry; a reactor (no _start) is always served directly.
+  const WasmEdge_FunctionInstanceContext *start = force_direct ? NULL :
       WasmEdge_ModuleInstanceFindFunction(instance, name("_start"));
   bool direct = start == NULL;
   WasmEdge_Value direct_args[3], response_pointer;

package/src/testing/parityHarness.js

@@ -499,6 +499,11 @@ function applyInjectedDivergence(runs, injectDivergence) {
  * @param {string[]} [options.lanes] - subset of PARITY_LANES. Defaults to ALL
  *   THREE. Narrowing is always an explicit caller decision — lanes are never
  *   skipped silently, and a single-lane run can never claim parity.
+ * @param {string} [options.surface] - "direct" runs EVERY lane on the direct
+ *   surface: the browser harness, and the wasi-threads runner with
+ *   --sdm-direct (the WasmEdge CLI has no direct surface, so a single-thread
+ *   artifact cannot be compared on it). Omitted: the browser lane follows
+ *   browserSurface and the WasmEdge lanes run the artifact's default surface.
  * @param {Object} [options.laneRunners] - {laneName: async (context) => runs[]}
  *   override for tests. Default runners come from parityLanes.js.
  * @param {string} [options.injectDivergence] - fire-drill: XOR one output byte
@@ -555,7 +560,8 @@ export async function runParityHarness(options = {}) {
     chromeBinary: options.chromeBinary,
     wasmedgeBinary: options.wasmedgeBinary,
     wasmEdgeRunnerBinary: options.wasmEdgeRunnerBinary,
-    browserSurface: options.browserSurface ??
+    surface: options.surface ?? null,
+    browserSurface: options.browserSurface ?? options.surface ??
       (WebAssembly.Module.exports(await WebAssembly.compile(loadableBytes)).some((entry) => entry.name === "_start") ? "command" : "direct"),
     dockerBinary: options.dockerBinary,
     dockerPlatform: options.dockerPlatform,

package/src/testing/parityLanes.js

@@ -130,6 +130,21 @@ function wasmedgeInvocationArgs(planCase, plan, threadCount) {
   return args;
 }
 
+// Runner flags that select the surface. Only the wasi-threads runner serves the
+// direct surface of an artifact with a command entry; the WasmEdge CLI runs
+// `_start` or nothing, so a direct-surface comparison on it would silently
+// compare two different surfaces.
+function surfaceArgs(context, threaded, lane) {
+  if (context.surface !== "direct") return [];
+  if (!threaded) {
+    throw new Error(
+      `${lane}: the WasmEdge CLI serves only the command surface of a single-thread artifact; ` +
+        "it cannot take part in a direct-surface parity run.",
+    );
+  }
+  return ["--sdm-direct"];
+}
+
 async function stageModuleWorkdir(context, label) {
   const workdir = await mkdtemp(path.join(os.tmpdir(), `sdm-parity-${label}-`));
   // Stage the canonical loadable bytes (publication records stripped by the
@@ -183,6 +198,7 @@ export async function runNativeWasmEdgeLane(context) {
     `native binary ${binary}`,
   );
 
+  const directArgs = surfaceArgs(context, threaded, "native WasmEdge lane");
   const workdir = await stageModuleWorkdir(context, "native");
   const runs = [];
   try {
@@ -191,6 +207,7 @@ export async function runNativeWasmEdgeLane(context) {
         const outcome = await spawnWithStdin(
           binary,
           [...(threaded ? ["--sdm-thread-stats"] : []),
+            ...directArgs,
             ...wasmedgeInvocationArgs(planCase, context.plan, threadCount)],
           {
             cwd: workdir,
@@ -288,6 +305,7 @@ export async function runDockerWasmEdgeLane(context) {
       `docker WasmEdge lane: cannot execute "${dockerBinary}" (${error.message}).`,
     );
   }
+  const directArgs = surfaceArgs(context, threaded, "docker WasmEdge lane");
   const image = await ensureDockerParityImage(context);
 
   const workdir = await stageModuleWorkdir(context, "docker");
@@ -313,6 +331,7 @@ export async function runDockerWasmEdgeLane(context) {
         dockerArgs.push(
           image,
           ...(threaded ? ["--sdm-thread-stats"] : []),
+          ...directArgs,
           ...wasmedgeInvocationArgs(planCase, context.plan, threadCount),
         );
         const outcome = await spawnWithStdin(dockerBinary, dockerArgs, {