@gadgetinc/substrate 0.1.0-rc.1

package/dist/runtime/process-manager.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Process Manager
+ *
+ * Manages all process contexts in the runtime. Each process gets its own
+ * isolated context with its own event loop, timers, and state.
+ *
+ * The ProcessManager is the single point of truth for:
+ * - Creating new processes (root process, child processes via spawn/fork)
+ * - Tracking active processes by PID
+ * - Cleaning up exited processes
+ * - Routing to the correct ProcessContext
+ */
+import type { KernelBridge } from "../kernel/types.js";
+import { ProcessContext, type ProcessCreateOptions } from "./process-context.js";
+/**
+ * Process Manager
+ *
+ * Owns all ProcessContext instances and provides methods for creating,
+ * looking up, and destroying processes.
+ */
+export declare class ProcessManager {
+    /** All active processes, keyed by PID */
+    private processes;
+    /** Kernel bridge (shared across all processes) */
+    private kernel;
+    /** Root process (PID 1) */
+    private rootProcess;
+    constructor(kernel: KernelBridge);
+    /**
+     * Create the root process (PID 1)
+     *
+     * This is called once during runtime initialization.
+     * The root process is the parent of all other processes.
+     *
+     * The kernel already creates PID 1 during initialization with cwd="/".
+     * We claim PID 1 as our root process and update its cwd if needed.
+     */
+    createRootProcess(options: {
+        cwd: string;
+        env: Record<string, string | undefined>;
+        argv: string[];
+    }): ProcessContext;
+    /**
+     * Get the root process
+     */
+    getRootProcess(): ProcessContext;
+    /**
+     * Create a ProcessContext for an already-spawned child process.
+     *
+     * The kernel proc_spawn was already called by child_process.spawn(), which
+     * assigned the PID. This method creates the JS-side ProcessContext with
+     * its own event loop, module cache, etc.
+     *
+     * @param pid - The kernel-assigned PID (from ChildProcess.pid)
+     * @param options - Process options (parent, cwd, env, argv)
+     */
+    createChildContext(pid: number, options: ProcessCreateOptions): ProcessContext;
+    /**
+     * Get a process by PID
+     */
+    getProcess(pid: number): ProcessContext | undefined;
+    /**
+     * Check if a process exists
+     */
+    hasProcess(pid: number): boolean;
+    /**
+     * Get all active processes
+     */
+    getAllProcesses(): ProcessContext[];
+    /**
+     * Get the kernel bridge backing this process manager.
+     */
+    getKernelBridge(): KernelBridge;
+}
+/**
+ * Set the current process manager (used by node compat).
+ */
+export declare function setCurrentProcessManager(manager: ProcessManager): void;
+/**
+ * Get the current process manager (used by node compat).
+ */
+export declare function getCurrentProcessManager(): ProcessManager;
+/**
+ * Reset the process manager (tests).
+ */
+export declare function resetProcessManager(): void;
+//# sourceMappingURL=process-manager.d.ts.map

package/dist/runtime/process-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-manager.d.ts","sourceRoot":"","sources":["../../src/runtime/process-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAYjF;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,yCAAyC;IACzC,OAAO,CAAC,SAAS,CAAqC;IAEtD,kDAAkD;IAClD,OAAO,CAAC,MAAM,CAAe;IAE7B,2BAA2B;IAC3B,OAAO,CAAC,WAAW,CAA+B;IAElD,YAAY,MAAM,EAAE,YAAY,EAE/B;IAMD;;;;;;;;OAQG;IACH,iBAAiB,CAAC,OAAO,EAAE;QACzB,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;QACxC,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,GAAG,cAAc,CA2BjB;IAED;;OAEG;IACH,cAAc,IAAI,cAAc,CAK/B;IAMD;;;;;;;;;OASG;IACH,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,GAAG,cAAc,CAkB7E;IAMD;;OAEG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAElD;IAED;;OAEG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/B;IAED;;OAEG;IACH,eAAe,IAAI,cAAc,EAAE,CAElC;IAED;;OAEG;IACH,eAAe,IAAI,YAAY,CAE9B;CACF;AAID;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAEtE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,cAAc,CAKzD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAI1C"}

package/dist/runtime/process-scheduler.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Global Process Scheduler
+ *
+ * Manages all process lifecycles independently of their parent's execution context.
+ * This ensures child processes continue running even if their parent's Promise
+ * chain is disrupted.
+ *
+ * ## Why This Exists
+ *
+ * Previously, when a parent process spawned a child, the child's event loop was
+ * managed through a Promise chain: `execute().then(handleExit)`. This created a
+ * structural dependency where the child's completion handling was tied to the
+ * parent's context.
+ *
+ * The scheduler decouples this by:
+ * 1. Owning all process registrations globally
+ * 2. Starting event loops in a fire-and-forget manner
+ * 3. Handling exit callbacks through its own context, not the parent's
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const scheduler = getProcessScheduler();
+ *
+ * // Register a process with its event loop and exit handler
+ * scheduler.register(pid, eventLoop, (exitCode, signal) => {
+ *   // Called when the process exits - owned by scheduler, not parent
+ *   child._handleExit(exitCode, signal);
+ * });
+ *
+ * // Start the process - fire and forget
+ * scheduler.startProcess(pid, async () => {
+ *   // Run the script
+ *   Module.runMain(scriptPath);
+ * });
+ * ```
+ */
+import type { ProcessEventLoop } from "./process-event-loop.js";
+/**
+ * Callback invoked when a process exits
+ */
+export type ProcessExitCallback = (exitCode: number, signal: string | null) => void;
+/**
+ * Global process scheduler that owns all process lifecycles.
+ *
+ * The scheduler ensures that:
+ * 1. Process event loops run independently of their parent's context
+ * 2. Exit handling is managed globally, not through parent Promise chains
+ * 3. All processes are properly cleaned up when they exit
+ */
+declare class ProcessScheduler {
+    /** All registered processes */
+    private processes;
+    /** Whether the scheduler's pump loop is running */
+    private pumping;
+    /**
+     * Register a process with the scheduler.
+     *
+     * The process's event loop will be managed by the scheduler, and the
+     * onExit callback will be called when the event loop completes.
+     *
+     * @param pid - Process ID
+     * @param eventLoop - The process's event loop instance
+     * @param onExit - Callback to invoke when the process exits
+     */
+    register(pid: number, eventLoop: ProcessEventLoop, onExit: ProcessExitCallback): void;
+    /**
+     * Start a registered process's event loop.
+     *
+     * This method:
+     * 1. Runs the provided script setup function
+     * 2. Starts the event loop (fire-and-forget)
+     * 3. When the event loop exits, calls the registered onExit callback
+     *
+     * @param pid - Process ID to start
+     * @param runScript - Function that runs the process's script (e.g., Module.runMain)
+     */
+    startProcess(pid: number, runScript: () => void): void;
+    /**
+     * Unregister a process from the scheduler.
+     *
+     * Called when a process is cleaned up externally (e.g., killed, test cleanup).
+     */
+    unregister(pid: number): void;
+    /**
+     * Check if a process is registered with the scheduler.
+     */
+    isRegistered(pid: number): boolean;
+    /**
+     * Get the number of active processes.
+     */
+    get activeCount(): number;
+    /**
+     * Handle a process exit.
+     *
+     * This is called when a process's event loop completes (either normally or with error).
+     * The exit callback is invoked in the scheduler's context, not the parent's.
+     */
+    private handleProcessExit;
+    /**
+     * Ensure the pump loop is running.
+     *
+     * The pump loop keeps the scheduler alive as long as there are processes.
+     * It doesn't actively pump event loops (they run themselves via start()),
+     * but it prevents the scheduler from being garbage collected.
+     */
+    private ensurePumping;
+    private pumpLoop;
+    /**
+     * Reset the scheduler (for tests).
+     */
+    reset(): void;
+}
+/**
+ * Get the global process scheduler instance.
+ */
+export declare function getProcessScheduler(): ProcessScheduler;
+/**
+ * Reset the process scheduler (for tests).
+ */
+export declare function resetProcessScheduler(): void;
+export {};
+//# sourceMappingURL=process-scheduler.d.ts.map

package/dist/runtime/process-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-scheduler.d.ts","sourceRoot":"","sources":["../../src/runtime/process-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAUhE;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;AAgBpF;;;;;;;GAOG;AACH,cAAM,gBAAgB;IACpB,+BAA+B;IAC/B,OAAO,CAAC,SAAS,CAAwC;IAEzD,mDAAmD;IACnD,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAiBpF;IAED;;;;;;;;;;OAUG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,GAAG,IAAI,CAyDrD;IAED;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAM5B;IAED;;OAEG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjC;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAqBzB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;YAqBP,QAAQ;IAUtB;;OAEG;IACH,KAAK,IAAI,IAAI,CAIZ;CACF;AAQD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAKtD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C"}

package/dist/runtime/process-waker.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Process Waker
+ *
+ * A waker is a signal/wait primitive for async event loops. Code awaits
+ * waker.wait() and is woken by waker.signal().
+ *
+ * All registered wakers are signaled after event-emitting syscalls so that
+ * event loops and runtime code can poll the kernel for new events.
+ */
+export interface Waker {
+    signal: () => void;
+    wait: (timeoutMs: number) => Promise<void>;
+    isSignaled: () => boolean;
+    __getWaiterCount: () => number;
+}
+export declare const createWaker: (label: string) => Waker;
+export declare const registerWaker: (waker: Waker) => void;
+export declare const unregisterWaker: (waker: Waker) => void;
+/**
+ * Signal all registered wakers so they poll the kernel for new events.
+ * Called after event-emitting syscalls and kernel.deliver().
+ */
+export declare const wakeAllWakers: () => void;
+//# sourceMappingURL=process-waker.d.ts.map

package/dist/runtime/process-waker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-waker.d.ts","sourceRoot":"","sources":["../../src/runtime/process-waker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,gBAAgB,EAAE,MAAM,MAAM,CAAC;CAChC;AAED,eAAO,MAAM,WAAW,0BAoDvB,CAAC;AAQF,eAAO,MAAM,aAAa,wBAEzB,CAAC;AAEF,eAAO,MAAM,eAAe,wBAE3B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,YAIzB,CAAC"}

package/dist/runtime/promise.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Minimal interface for the event loop methods used by SubstratePromise.
+ * This avoids exposing ProcessEventLoop's internal types in the public API.
+ */
+export interface PromiseEventLoop {
+    pid: number;
+    queueMicrotask(callback: () => void): void;
+    captureAsyncContext(): unknown;
+    runInAsyncContext<T>(context: unknown, fn: () => T): T;
+    reportUnhandledRejection(reason: unknown, promise: unknown): void;
+}
+/**
+ * Interface for the SubstratePromise class returned by createPromiseClass.
+ */
+export interface SubstratePromiseConstructor {
+    new <T = unknown>(executor: (resolve: (value: T | SubstratePromiseLike<T>) => void, reject: (reason: unknown) => void) => void): SubstratePromiseLike<T>;
+    resolve<T>(value: T | SubstratePromiseLike<T>): SubstratePromiseLike<T>;
+    reject<T = never>(reason: unknown): SubstratePromiseLike<T>;
+    all<T>(iterable: Iterable<T | SubstratePromiseLike<T>>): SubstratePromiseLike<T[]>;
+    race<T>(iterable: Iterable<T | SubstratePromiseLike<T>>): SubstratePromiseLike<T>;
+    allSettled<T>(iterable: Iterable<T | SubstratePromiseLike<T>>): SubstratePromiseLike<Array<{
+        status: "fulfilled";
+        value: T;
+    } | {
+        status: "rejected";
+        reason: unknown;
+    }>>;
+    any<T>(iterable: Iterable<T | SubstratePromiseLike<T>>): SubstratePromiseLike<T>;
+    withResolvers<T>(): {
+        promise: SubstratePromiseLike<T>;
+        resolve: (value: T | SubstratePromiseLike<T>) => void;
+        reject: (reason: unknown) => void;
+    };
+}
+export interface SubstratePromiseLike<T> {
+    then<TResult1 = T, TResult2 = never>(onFulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onRejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): SubstratePromiseLike<TResult1 | TResult2>;
+    catch<TResult = never>(onRejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): SubstratePromiseLike<T | TResult>;
+    finally(onFinally?: (() => unknown) | null): SubstratePromiseLike<T>;
+}
+export declare const createPromiseClass: (eventLoop: PromiseEventLoop) => {
+    PromiseClass: SubstratePromiseConstructor;
+    checkUnhandledRejections: () => void;
+};
+//# sourceMappingURL=promise.d.ts.map

package/dist/runtime/promise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promise.d.ts","sourceRoot":"","sources":["../../src/runtime/promise.ts"],"names":[],"mappings":"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"}

package/dist/runtime/stack-trace.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Stack Trace Improvements
+ *
+ * Installs Error.prepareStackTrace (V8 API) to:
+ * 1. Filter internal runtime frames (loaders, event loop, promise, async transform)
+ * 2. Remap substrate:// positions to original source via the source map registry
+ * 3. Filter WASM frames
+ * 4. Stitch async continuation stacks from the __async helper
+ *
+ * Also provides Error.captureStackTrace polyfill if missing.
+ */
+interface V8CallSite {
+    getFileName(): string | null;
+    getLineNumber(): number | null;
+    getColumnNumber(): number | null;
+    getFunctionName(): string | null;
+    getMethodName(): string | null;
+    getTypeName(): string | null;
+    /** Returns the sourceURL from //# sourceURL= annotation if present, otherwise the script name */
+    getScriptNameOrSourceURL(): string | null;
+    isNative(): boolean;
+    isEval(): boolean;
+    isConstructor(): boolean;
+    isToplevel(): boolean;
+    toString(): string;
+}
+/**
+ * Determine if a V8 CallSite represents an internal frame that should
+ * be hidden from user-facing stack traces.
+ *
+ * Uses URL-based filtering: only substrate:// frames are user code.
+ * Additionally filters async transform trampoline names that appear
+ * inside substrate:// URLs.
+ */
+export declare function isInternalFrame(site: V8CallSite): boolean;
+/**
+ * Filter a pre-formatted stack line (string) for internal frames.
+ * Used when processing __asyncStack strings which are already formatted.
+ */
+export declare function isInternalFrameLine(line: string): boolean;
+/**
+ * Install the Error.prepareStackTrace hook for cleaning and remapping stacks.
+ * Safe to call multiple times — only installs once.
+ */
+export declare function installStackTraceHook(): void;
+/**
+ * Ensure Error.captureStackTrace is available for guest code.
+ * V8 in Chrome already provides it natively; this is a safety net.
+ */
+export declare function installCaptureStackTrace(): void;
+export {};
+//# sourceMappingURL=stack-trace.d.ts.map

package/dist/runtime/stack-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-trace.d.ts","sourceRoot":"","sources":["../../src/runtime/stack-trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,UAAU,UAAU;IAClB,WAAW,IAAI,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,IAAI,MAAM,GAAG,IAAI,CAAC;IAC/B,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IACjC,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IACjC,aAAa,IAAI,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,IAAI,MAAM,GAAG,IAAI,CAAC;IAC7B,iGAAiG;IACjG,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAAC;IAC1C,QAAQ,IAAI,OAAO,CAAC;IACpB,MAAM,IAAI,OAAO,CAAC;IAClB,aAAa,IAAI,OAAO,CAAC;IACzB,UAAU,IAAI,OAAO,CAAC;IACtB,QAAQ,IAAI,MAAM,CAAC;CACpB;AAyCD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAqBzD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CA0BzD;AA6DD;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAuE5C;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAc/C"}

package/dist/runtime/wasm-package-interceptor.d.ts

@@ -0,0 +1,141 @@
+/**
+ * WASM Package Interceptor
+ *
+ * Handles automatic installation of WASM alternatives for native binding packages.
+ *
+ * When files are written to node_modules that match native binding patterns
+ * (e.g., @rollup/rollup-linux-x64-gnu), we:
+ * 1. Fetch the WASM alternative package tarball
+ * 2. Extract it to /node_aliases/ in the VFS
+ * 3. Register aliases so native binding imports resolve to the WASM package
+ * 4. Register dynamic process handlers for bin stubs (e.g., esbuild)
+ *
+ * This allows tools like Vite to work in the browser without native binaries.
+ */
+/**
+ * Serializable WASM package mapping for use in boot configuration.
+ * This is the user-facing type — it can be sent over postMessage.
+ */
+export interface WasmPackageMapping {
+    /** Main package name (e.g., "rollup") */
+    packageName: string;
+    /** WASM replacement package name (e.g., "@rollup/wasm-node") — version is appended automatically */
+    wasmPackage: string;
+    /** Regex pattern strings matching native binding packages (e.g., ["^@rollup/rollup-(linux|darwin|win32)-"]) */
+    nativeBindingPatterns: string[];
+    /** Optional export subpath within the WASM package (e.g., "dist/native.js") */
+    wasmExportPath?: string;
+}
+/**
+ * Configuration for a package that has native bindings and a WASM alternative.
+ */
+export interface WasmPackageConfig {
+    /**
+     * The main package name (e.g., 'rollup', 'esbuild', 'rolldown')
+     */
+    packageName: string;
+    /**
+     * Function to get the WASM package name given the main package version
+     */
+    getWasmPackage: (version: string) => string;
+    /**
+     * Patterns matching native binding package names that should be aliased.
+     * These are the platform-specific packages like @rollup/rollup-linux-x64-gnu
+     */
+    nativeBindingPatterns: RegExp[];
+    /**
+     * The export path within the WASM package that native bindings should resolve to.
+     * If not specified, defaults to the package root.
+     */
+    wasmExportPath?: string;
+}
+/**
+ * Register a WASM package configuration.
+ */
+export declare function registerWasmPackage(config: WasmPackageConfig): void;
+/**
+ * Get config for a package by name
+ */
+export declare function getWasmPackageConfig(packageName: string): WasmPackageConfig | undefined;
+/**
+ * Initialize the WASM package interceptor.
+ * This sets up the native binding resolver, file write hook, and registers default packages.
+ * Custom packages are registered after defaults — if a custom package has the same
+ * packageName as a default, it overrides it.
+ */
+export declare function initWasmPackageInterceptor(customPackages?: WasmPackageMapping[]): void;
+/**
+ * Register default WASM package configurations for common tools.
+ */
+export declare function registerDefaultWasmPackages(): void;
+/**
+ * Check if a file path indicates a native binding package being written.
+ * Returns the detected package info if it's a native binding, null otherwise.
+ *
+ * Called from fsDriver.writeFile to detect when npm installs native bindings.
+ */
+export declare function detectNativeBinding(path: string): {
+    packageName: string;
+    nativePackage: string;
+    nodeModulesPath: string;
+} | null;
+/**
+ * Handle detection of a native binding package.
+ * Called when fsDriver.writeFile detects a native binding package.json.
+ *
+ * This function:
+ * 1. Finds the version of the main package
+ * 2. Fetches and installs the WASM alternative
+ * 3. Registers aliases for native binding imports
+ * 4. Optionally registers a dynamic process handler
+ *
+ * Returns a promise that resolves when installation is complete.
+ *
+ * IMPORTANT: This function intentionally avoids async/await. The worker code
+ * is transpiled to ES2016, which converts async/await into generators that use
+ * globalThis.Promise. When called inside runWithGlobals(), globalThis.Promise
+ * is SubstratePromise, whose .then() continuations are scheduled via the
+ * calling process's event loop microtask queue. If the process exits before
+ * the WASM download completes, those continuations never fire, the install
+ * promise never settles, and waitForPendingInstallations() hangs forever.
+ * By using explicit nativePromise chains, all continuations run via the
+ * browser's native microtask queue, independent of any process event loop.
+ */
+export declare function handleNativeBindingDetected(packageName: string, nativePackage: string, nodeModulesPath: string): Promise<void>;
+/**
+ * Try to match a module specifier against registered native binding patterns.
+ * Returns the target path if matched, null otherwise.
+ */
+export declare function tryResolveNativeBinding(specifier: string): string | null;
+/**
+ * Scan /node_aliases/ for previously installed WASM packages and register their aliases.
+ *
+ * Called after mounting a persistent VFS (e.g., booting from an OPFS store) to
+ * restore module resolution aliases without re-downloading WASM packages.
+ */
+export declare function scanAndRegisterAliases(): void;
+/**
+ * Check if there are any pending WASM package installations.
+ */
+export declare function hasPendingInstallations(): boolean;
+/**
+ * Wait for all pending WASM package installations to complete.
+ *
+ * Uses nativePromise.all to avoid depending on SubstratePromise scheduling,
+ * which would require a live process event loop. The promises in
+ * installingPackages are already native Promises (see handleNativeBindingDetected).
+ */
+export declare function waitForPendingInstallations(): Promise<void>;
+/**
+ * Clear all state (for testing).
+ */
+export declare function clearWasmPackageState(): void;
+/**
+ * Check if a WASM package is installed.
+ */
+export declare function isWasmPackageInstalled(packageName: string, version: string): boolean;
+/**
+ * Get the install path for a WASM package.
+ */
+export declare function getWasmPackageInstallPath(packageName: string, version: string): string | undefined;
+//# sourceMappingURL=wasm-package-interceptor.d.ts.map

package/dist/runtime/wasm-package-interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-package-interceptor.d.ts","sourceRoot":"","sources":["../../src/runtime/wasm-package-interceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAiBH;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,sGAAoG;IACpG,WAAW,EAAE,MAAM,CAAC;IACpB,+GAA+G;IAC/G,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAcD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IAE5C;;;OAGG;IACH,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAEhC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAcD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CASnE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEvF;AAMD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,cAAc,CAAC,EAAE,kBAAkB,EAAE,GAAG,IAAI,CA0BtF;AAqBD;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CA+BlD;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,GACX;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAqChF;AAeD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CA2Df;AA8JD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQxE;AAKD;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAkE7C;AAMD;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAO3D;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAM5C;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,SAAS,CAEpB"}

package/dist/runtime/web-streams.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Wrapped Web Stream globals for Substrate.
+ *
+ * Browser-native ReadableStream, WritableStream, and TransformStream return
+ * native V8 Promises from their reader/writer/iterator methods. These Promises
+ * bypass SubstratePromise's event loop queue, causing microtask escape bugs
+ * (SIGSEGV, premature process exit).
+ *
+ * This module provides wrapped constructors that intercept Promise-returning
+ * methods and route them through SubstratePromise with proper ref/unref to
+ * keep the event loop alive. The pattern mirrors `createWrappedFetch` in
+ * process-event-loop.ts.
+ */
+import type { SubstratePromiseConstructor } from "./promise.js";
+/** Unwrap a potentially Proxy-wrapped stream back to its native counterpart. */
+export declare function unwrapNativeStream<T>(stream: T): T;
+/** Minimal interface for the event loop's ref/unref mechanism. */
+interface RefUnref {
+    ref(): void;
+    unref(): void;
+}
+/**
+ * Wrap a native ReadableStream instance via Proxy. Intercepts all
+ * Promise-returning methods and routes them through SubstratePromise.
+ */
+export declare function wrapReadableStream<R = unknown>(nativeStream: ReadableStream<R>, SP: SubstratePromiseConstructor, eventLoop: RefUnref): ReadableStream<R>;
+/**
+ * Wrap a native Response so that `.body` returns a wrapped ReadableStream and
+ * body-consuming methods (`.text()`, `.json()`, etc.) return SubstratePromises.
+ */
+export declare function wrapFetchResponse(response: Response, SP: SubstratePromiseConstructor, eventLoop: RefUnref): Response;
+/**
+ * Create a wrapped Response constructor that unwraps Proxy-wrapped
+ * ReadableStreams passed as the body argument.
+ *
+ * The native Response constructor checks V8 internal slots to recognize
+ * ReadableStream bodies. Proxy-wrapped streams don't have these slots,
+ * so the constructor falls back to `.toString()` producing
+ * "[object ReadableStream]" instead of streaming the body.
+ */
+export declare function createWrappedResponse(): typeof globalThis.Response;
+export interface WrappedStreamClasses {
+    ReadableStream: typeof globalThis.ReadableStream;
+    WritableStream: typeof globalThis.WritableStream;
+    TransformStream: typeof globalThis.TransformStream;
+}
+/**
+ * Create per-process wrapped ReadableStream, WritableStream, and
+ * TransformStream constructors.
+ *
+ * Each constructor delegates to the native browser constructor then wraps the
+ * returned instance so all Promise-returning methods route through
+ * SubstratePromise with proper ref/unref.
+ */
+export declare function createWrappedStreamClasses(SP: SubstratePromiseConstructor, eventLoop: RefUnref): WrappedStreamClasses;
+export {};
+//# sourceMappingURL=web-streams.d.ts.map

package/dist/runtime/web-streams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-streams.d.ts","sourceRoot":"","sources":["../../src/runtime/web-streams.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,KAAK,EAAE,2BAA2B,EAAwB,MAAM,cAAc,CAAC;AAgBtF,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAElD;AAMD,kEAAkE;AAClE,UAAU,QAAQ;IAChB,GAAG,IAAI,IAAI,CAAC;IACZ,KAAK,IAAI,IAAI,CAAC;CACf;AA0ID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAC5C,YAAY,EAAE,cAAc,CAAC,CAAC,CAAC,EAC/B,EAAE,EAAE,2BAA2B,EAC/B,SAAS,EAAE,QAAQ,GAClB,cAAc,CAAC,CAAC,CAAC,CA8EnB;AA4ED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,EAAE,EAAE,2BAA2B,EAC/B,SAAS,EAAE,QAAQ,GAClB,QAAQ,CA2BV;AAQD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,UAAU,CAAC,QAAQ,CAkBlE;AAMD,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,OAAO,UAAU,CAAC,cAAc,CAAC;IACjD,cAAc,EAAE,OAAO,UAAU,CAAC,cAAc,CAAC;IACjD,eAAe,EAAE,OAAO,UAAU,CAAC,eAAe,CAAC;CACpD;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,2BAA2B,EAC/B,SAAS,EAAE,QAAQ,GAClB,oBAAoB,CAuGtB"}

package/dist/runtime/websocket.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Runtime-Level WebSocket Client
+ *
+ * This is a WebSocket client for use by runtime/orchestration code.
+ * It uses syscalls directly and does NOT depend on node compat code.
+ *
+ * This is different from the node compat WebSocket (src/node/ws.ts) which
+ * is for use by guest Node.js code running inside a process context.
+ *
+ * Architecture rule: Runtime code uses this. Node compat code uses net.Socket.
+ */
+import { type WebSocketReadyState } from "../utils/websocket-protocol.js";
+export interface RuntimeWebSocketEvents {
+    open: {
+        protocol: string;
+    };
+    message: {
+        data: string | ArrayBuffer;
+    };
+    close: {
+        code: number;
+        reason: string;
+        wasClean: boolean;
+    };
+    error: {
+        message: string;
+    };
+}
+type EventCallback<T> = (event: T) => void;
+/**
+ * Runtime-level WebSocket client.
+ *
+ * Uses syscalls directly.
+ * Safe to use from runtime/worker host code.
+ */
+export declare class RuntimeWebSocket {
+    static readonly CONNECTING: 0;
+    static readonly OPEN: 1;
+    static readonly CLOSING: 2;
+    static readonly CLOSED: 3;
+    private _readyState;
+    private _url;
+    private _protocol;
+    private _connId;
+    private _key;
+    private _protocols;
+    onopen: EventCallback<RuntimeWebSocketEvents["open"]> | null;
+    onmessage: EventCallback<RuntimeWebSocketEvents["message"]> | null;
+    onerror: EventCallback<RuntimeWebSocketEvents["error"]> | null;
+    onclose: EventCallback<RuntimeWebSocketEvents["close"]> | null;
+    private _receiveBuffer;
+    private _handshakeComplete;
+    private _eqId;
+    private _waker;
+    constructor(url: string | URL, protocols?: string | string[]);
+    get readyState(): WebSocketReadyState;
+    get url(): string;
+    get protocol(): string;
+    /**
+     * Connect to the WebSocket server using syscalls directly
+     */
+    private _connect;
+    private _runEventLoop;
+    /**
+     * Drain all available data from the connection's inbound buffer.
+     */
+    private _drainInbound;
+    /**
+     * Handle incoming data
+     */
+    private _handleData;
+    /**
+     * Process WebSocket frames from the buffer
+     */
+    private _processFrames;
+    /**
+     * Send a WebSocket frame
+     */
+    private _sendFrame;
+    /**
+     * Send a close frame
+     */
+    private _sendCloseFrame;
+    /**
+     * Clean up resources
+     */
+    private _cleanup;
+    private _emitOpen;
+    private _emitMessage;
+    private _emitClose;
+    private _emitError;
+    /**
+     * Send data through the WebSocket connection
+     */
+    send(data: string | ArrayBuffer | Uint8Array): void;
+    /**
+     * Close the WebSocket connection
+     */
+    close(code?: number, reason?: string): void;
+}
+export {};
+//# sourceMappingURL=websocket.d.ts.map