@volter/tabnode 0.4.0 → 0.5.0

package/src/node-lib/load.ts

@@ -29,6 +29,8 @@ import { nodeLibBinding } from './binding';
 import { nodeLibPublic } from './public-modules';
 import { setLibRequire } from './require-hook';
 import { NODE_LTS_VERSION, nodeVersions } from './node-versions';
+import { createUtilBinding } from './binding/util';
+import { createFsBindings } from './binding/fs';
 
 /**
  * The realm's built-ins, captured as Node captures them: before a program can
@@ -206,9 +208,16 @@ export function loadNodeLib(name: string): unknown {
  * Spread of a lazy proxy copied nothing; `Object.getOwnPropertyNames` reads
  * the proxy's ownKeys trap, which is the module's keys.
  */
-const builtinNamespaces: Array<{ cjs: object; ns: Record<string, unknown> }> = [];
+type BuiltinNamespace = { cjs: object; ns: Record<string, unknown> };
+const builtinNamespaces = new WeakMap<object, BuiltinNamespace[]>();
+const hostNamespaceOwner = {};
+function namespacesFor(owner: object): BuiltinNamespace[] {
+  let held = builtinNamespaces.get(owner);
+  if (!held) { held = []; builtinNamespaces.set(owner, held); }
+  return held;
+}
 
-export function esmNamespaceOf(mod: unknown): Record<string, unknown> {
+export function esmNamespaceOf(mod: unknown, owner: object = hostNamespaceOwner): Record<string, unknown> {
   const ns: Record<string, unknown> = { default: mod };
   if (mod !== null && (typeof mod === 'object' || typeof mod === 'function')) {
     const cjs = mod as object;
@@ -221,14 +230,14 @@ export function esmNamespaceOf(mod: unknown): Record<string, unknown> {
         set(value: unknown) { (cjs as Record<string, unknown>)[key] = value; },
       });
     }
-    builtinNamespaces.push({ cjs, ns });
+    namespacesFor(owner).push({ cjs, ns });
   }
   return ns;
 }
 
 /** Node's `module.syncBuiltinESMExports`: newly assigned CJS keys appear on the namespace. */
-export function syncBuiltinESMExports(): void {
-  for (const { cjs, ns } of builtinNamespaces) {
+export function syncBuiltinESMExports(owner: object = hostNamespaceOwner): void {
+  for (const { cjs, ns } of namespacesFor(owner)) {
     for (const key of Object.getOwnPropertyNames(cjs)) {
       if (key === 'default' || Object.prototype.hasOwnProperty.call(ns, key)) continue;
       Object.defineProperty(ns, key, {
@@ -248,35 +257,144 @@ export function loadNodeLibInstance(name: string): unknown {
 }
 
 /**
- * A vendored file cached on one engine instance rather than the realm.
- *
- * Node has one builtin cache per process. The engine runs many processes in
- * one realm, and the realm cache is keyed only by name, so a second
- * `Runtime`'s `require('fs')` was the first's module object: a `Symbol.for`
- * tag written by one guest was readable by the other. The first instance
- * still uses {@link loadNodeLib}; a later instance asks here, and the file
- * is compiled once for that owner. Its `require` of other vendored files
- * still hits the realm cache, so `net` and `events` stay one class.
+ * Each guest owns one recursively resolved builtin graph. The default loader
+ * is private to the engine; guest monkey patches never reach it or siblings.
+ * Native bindings retain the shared OS registries beneath those graphs.
  */
-let byOwner: WeakMap<object, Map<string, NodeLibModule>> | undefined;
-export function loadNodeLibFor(owner: object, name: string): unknown {
-  byOwner ??= new WeakMap();
-  let owned = byOwner.get(owner);
-  if (!owned) {
-    owned = new Map();
-    byOwner.set(owner, owned);
+export type NodeLibRequire = (name: string) => any;
+type ModuleInitializer = (name: string, value: any, require: NodeLibRequire) => void;
+const moduleInitializers = new Set<ModuleInitializer>();
+
+/** Host bootstrap adapters are applied to each newly compiled builtin. */
+export function onNodeLibLoaded(initialize: ModuleInitializer): () => void {
+  moduleInitializers.add(initialize);
+  return () => { moduleInitializers.delete(initialize); };
+}
+
+/** Native implementations can be shared; their exported module records cannot. */
+export function moduleSurface(value: any, seen = new Map<object, any>()): any {
+  if (value === null || typeof value !== 'object') return value;
+  if (seen.has(value)) return seen.get(value);
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== null && prototype !== Object.prototype && !Array.isArray(value)) return value;
+  const surface = Array.isArray(value) ? [] : Object.create(prototype === null ? null : Object.prototype);
+  seen.set(value, surface);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (Array.isArray(value) && key === 'length') continue;
+    descriptor.configurable = true;
+    if ('value' in descriptor) {
+      descriptor.value = moduleSurface(descriptor.value, seen);
+      descriptor.writable = true;
+    }
+    Object.defineProperty(surface, key, descriptor);
   }
-  const cached = owned.get(name);
-  if (cached) return cached.exports;
-  const record = newNodeLibRecord(name);
-  owned.set(name, record);
-  try {
-    compileNodeLib(name, record);
-  } catch (error) {
-    owned.delete(name);
-    throw error;
+  return surface;
+}
+
+/** Native class implementation and OS registries are shared, JS prototypes are not. */
+function bindingSurface(value: unknown): unknown {
+  const surface = moduleSurface(value);
+  for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(surface))) {
+    const implementation = descriptor.value;
+    // ECMAScript classes have a non-writable own prototype. Ordinary native
+    // functions stay callable functions; class facades retain their static API.
+    if (typeof implementation !== 'function'
+      || Object.getOwnPropertyDescriptor(implementation, 'prototype')?.writable !== false) continue;
+    const ScopedBinding = class extends implementation {};
+    Object.defineProperty(ScopedBinding, 'name', { value: implementation.name, configurable: true });
+    // IPC transfers native handles within the shared OS. Node's native-brand
+    // checks must recognize the received handle even when its JS facade was
+    // allocated by another process. This does not share guest module exports.
+    Object.defineProperty(ScopedBinding, Symbol.hasInstance, {
+      value: (instance: unknown) => Function.prototype[Symbol.hasInstance].call(implementation, instance),
+    });
+    Object.defineProperty(surface, key, { ...descriptor, value: ScopedBinding });
+  }
+  return surface;
+}
+
+class NodeLibScope {
+  private readonly modules = new Map<string, NodeLibModule>();
+  private readonly internals = new Map<string, unknown>();
+  private readonly bindings = new Map<string, unknown>();
+  private readonly surfaces = new Map<string, unknown>();
+  constructor(readonly process: object) {}
+
+  readonly require: NodeLibRequire = (specifier) => {
+    const name = specifier.startsWith('node:') ? specifier.slice(5) : specifier;
+    if (name === 'process') return this.process;
+    if (name === 'fs/promises') return this.require('internal/fs/promises').exports;
+    if (name === 'timers/promises') return this.require('timers').promises;
+    if (name === 'dns/promises') return this.require('dns').promises;
+    if (name === 'path/posix') return this.require('path').posix;
+    if (name === 'path/win32') return this.require('path').win32;
+    if (name === 'assert/strict') return this.require('assert').strict;
+    if (name === 'util/types') return this.require('internal/util/types');
+    if (NODE_LIB_SOURCES[name] !== undefined) return this.load(name);
+    const internal = nodeLibInternal(name, this.require, this.process);
+    if (internal) {
+      if (!this.internals.has(name)) this.internals.set(name, moduleSurface(internal()));
+      return this.internals.get(name);
+    }
+    const native = nodeLibPublic(name, this.require, this.process);
+    if (native) return this.surface(name, native);
+    throw new Error(`node-lib: no builtin '${specifier}' in this process`);
+  };
+
+  surface(name: string, create: () => unknown): unknown {
+    if (!this.surfaces.has(name)) this.surfaces.set(name, moduleSurface(create()));
+    return this.surfaces.get(name);
+  }
+
+  private readonly binding = (name: string): unknown => {
+    if (!this.bindings.has(name)) {
+      if (['fs', 'fs_dir', 'fs_event_wrap'].includes(name)) {
+        // Exported handles and encoded names belong to this graph; the fd
+        // allocator, open-file descriptions and filesystem remain shared OS state.
+        const fs = createFsBindings(() => this.require('buffer').Buffer);
+        this.bindings.set('fs', fs.fsBinding);
+        this.bindings.set('fs_dir', fs.fsDirBinding);
+        this.bindings.set('fs_event_wrap', fs.fsEventWrapBinding);
+      } else {
+        this.bindings.set(name, name === 'util' ? createUtilBinding(this.require) : bindingSurface(internalBinding(name)));
+      }
+    }
+    return this.bindings.get(name);
+  };
+
+  private load(name: string): unknown {
+    const cached = this.modules.get(name);
+    if (cached) return cached.exports;
+    const record = newNodeLibRecord(name);
+    // Insert before evaluation: circular dependencies see this graph's record.
+    this.modules.set(name, record);
+    try {
+      compileNodeLib(name, record, this.require, this.process, this.binding);
+      for (const initialize of moduleInitializers) initialize(name, record.exports, this.require);
+    } catch (error) {
+      this.modules.delete(name);
+      throw error;
+    }
+    return record.exports;
   }
-  return record.exports;
+}
+
+const byOwner = new WeakMap<object, NodeLibScope>();
+function scopeFor(owner: object): NodeLibScope {
+  let scope = byOwner.get(owner);
+  if (!scope) { scope = new NodeLibScope(owner); byOwner.set(owner, scope); }
+  return scope;
+}
+export function loadNodeLibFor(owner: object, name: string): any {
+  return scopeFor(owner).require(name);
+}
+export function hasNodeLibModule(name: string): boolean {
+  return NODE_LIB_SOURCES[name] !== undefined || nodeLibPublic(name) !== undefined
+    || ['path/posix', 'path/win32', 'assert/strict', 'util/types', 'fs/promises', 'timers/promises', 'dns/promises'].includes(name);
+}
+export function nativeModuleFor(owner: object, name: string, create: () => unknown): unknown {
+  return scopeFor(owner).surface(name, create);
 }
 
 function newNodeLibRecord(name: string): NodeLibModule {
@@ -285,15 +403,16 @@ function newNodeLibRecord(name: string): NodeLibModule {
 }
 
 /** The scope Node's `BuiltinModule.compileForInternalLoader` gives a builtin. */
-function compileNodeLib(name: string, record: NodeLibModule): void {
+function compileNodeLib(name: string, record: NodeLibModule, require: NodeLibRequire = nodeLibRequire,
+  process: object = nodeLibProcessOf(), binding: (name: string) => unknown = internalBinding): void {
   // eslint-disable-next-line no-new-func
   const compiled = new Function(
     'exports', 'require', 'module', 'process', 'internalBinding', 'primordials',
     `${NODE_LIB_SOURCES[name]}\n//# sourceURL=node:${name}`,
   );
-  compiled(record.exports, nodeLibRequire, record, nodeLibProcessOf(), internalBinding, primordialsOf());
+  compiled(record.exports, require, record, process, binding, primordialsOf());
   record.loaded = true;
-  bootstrapNodeLib(name, record.exports);
+  bootstrapNodeLib(name, record.exports, process);
 }
 
 /**
@@ -307,38 +426,27 @@ function compileNodeLib(name: string, record: NodeLibModule): void {
  * `testEnabled`. The engine has no bootstrap file, so the step lives here,
  * beside the compile it belongs to.
  */
-function bootstrapNodeLib(name: string, exports: unknown): void {
+function bootstrapNodeLib(name: string, exports: unknown, process: object): void {
   if (name === 'events') {
-    // Node's own `EventTarget` sets its listener ceiling on itself in its
-    // constructor, and `events.getMaxListeners` reads that field back. The
-    // realm's `EventTarget` -- the DOM's in a tab, Node's own where the
-    // engine runs inside a Node -- has no such field, and either way it is
-    // keyed by a symbol THIS `events.js` minted, not the one the realm's
-    // class was built against. So the default goes on the prototype under
-    // this file's own keys, where `getMaxListeners` looks, and a target given
-    // its own ceiling shadows it, which is what an own property does.
-    const events = exports as { kMaxEventTargetListeners?: symbol; kMaxEventTargetListenersWarned?: symbol };
-    const target = (globalThis as { EventTarget?: { prototype: object } }).EventTarget;
-    const defaults: Array<[symbol | undefined, unknown]> = [
-      [events.kMaxEventTargetListeners, 10],
-      [events.kMaxEventTargetListenersWarned, false],
-    ];
-    if (target) {
-      for (const [key, fallback] of defaults) {
-        if (!key || key in target.prototype) continue;
-        Object.defineProperty(target.prototype, key, {
-          configurable: true,
-          get(): unknown { return fallback; },
-          set(this: object, value: unknown) {
-            Object.defineProperty(this, key, { value, writable: true, configurable: true });
-          },
-        });
-      }
-    }
+    // Browser EventTargets do not carry Node's process-local listener symbol.
+    // Adapt that native boundary without installing a new pair of symbols on
+    // the shared EventTarget prototype for every short-lived guest process.
+    const events = exports as {
+      kMaxEventTargetListeners: symbol;
+      defaultMaxListeners: number;
+      getMaxListeners: (target: any) => number;
+    };
+    const original = events.getMaxListeners;
+    events.getMaxListeners = (target) => {
+      if (typeof EventTarget !== 'undefined' && target instanceof EventTarget
+        && typeof (target as any).getMaxListeners !== 'function'
+        && (target as any)[events.kMaxEventTargetListeners] === undefined) return events.defaultMaxListeners;
+      return original(target);
+    };
     return;
   }
   if (name === 'internal/util/debuglog') {
-    const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;
+    const env = (process as { env?: Record<string, string | undefined> }).env;
     (exports as { initializeDebugEnv?: (value: string) => void }).initializeDebugEnv?.(env?.NODE_DEBUG ?? '');
     return;
   }

package/src/node-lib/module-hooks.ts

@@ -32,7 +32,7 @@
  * - `initialize` is awaited before the first resolution the chain serves,
  *   which is where Node's synchronous `register()` has already blocked for it.
  */
-import { loadNodeLibInstance } from './load';
+import { loadNodeLibFor } from './load';
 
 /** A resolve hook's answer, as `internal/modules/esm/hooks.js` validates one. */
 export interface ResolveResult {
@@ -96,7 +96,10 @@ const ESM_CONDITIONS = ['node', 'import'];
 
 export class RunModuleHooks {
   /** The vendored file's own instance, this run's alone. */
-  readonly sync: CustomizationHooks = loadNodeLibInstance('internal/modules/customization_hooks') as CustomizationHooks;
+  readonly sync: CustomizationHooks;
+  constructor(process: object) {
+    this.sync = loadNodeLibFor(process, 'internal/modules/customization_hooks') as CustomizationHooks;
+  }
   #resolveChain: Link<AsyncResolveHook>[] = [];
   #loadChain: Link<AsyncLoadHook>[] = [];
   #initializing: Promise<unknown>[] = [];

package/src/node-lib/public-modules.ts

@@ -3,7 +3,7 @@
  *
  * Node's own files `require('dns')`, `require('timers')` and the rest as any
  * program does, and get the runtime's modules. Here they get the engine's
- * shims — the same objects the engine's module table hands a guest — so a
+ * shims through the requesting process's module graph, so a
  * `net.Socket` is a `stream.Duplex` of the same `stream` the guest imports,
  * and an `instanceof` across the two holds. A name that is itself a vendored
  * file — `events`, `util`, `buffer`, `stream` — is never asked of this table:
@@ -13,11 +13,11 @@
  * this module is loaded, so a cycle between a shim and the loader settles
  * before either is used.
  */
-import * as dnsShim from '../shims/dns';
+import { createDnsModule } from '../shims/dns';
 import * as clusterShim from '../shims/cluster';
 import * as dgramShim from '../shims/dgram';
 import asyncHooksShim from '../shims/async_hooks';
-import stringDecoderShim from '../shims/string_decoder';
+import stringDecoderShim, { createStringDecoderModule } from '../shims/string_decoder';
 import v8Shim from '../shims/v8';
 import * as pathShim from '../shims/path';
 import * as tlsShim from '../shims/tls';
@@ -28,57 +28,21 @@ import * as http2Shim from '../shims/http2';
 import * as inspectorShim from '../shims/inspector';
 import * as perfHooksShim from '../shims/perf_hooks';
 import { nodeLibInternalRequire } from './load';
-import { nodeTimeout, timerHandleOf } from './timers';
+import { createTimersModule } from './timers';
+import { guestTimerFunctions } from '../guest-timers';
 import { AsyncResource } from './internals/runtime';
 
-/**
- * `timers`: the realm's own, called on the realm and answering Node's shape.
- *
- * This is the module Node's own files take their timers from --
- * `_http_server.js` opens with `const { setInterval, clearInterval } =
- * require('timers')` and then writes `setInterval(...).unref()` the moment a
- * server listens -- so what it answers has to be Node's `Timeout`
- * ({@link nodeTimeout}), not a browser's number. It handed back the realm's
- * raw function, and in the tab every guest that called `listen` died with
- * `setInterval(...).unref is not a function`, openvscode-server among them.
- * The function is also called on the realm here: a worker's `setInterval`
- * invoked with this module as its receiver throws `Illegal invocation`, which
- * is what a guest's own `require('timers').setInterval` did.
- *
- * A guest's global timers are the same shape, built per run in
- * `src/runtime.ts` where they are counted against that run's loop; a timer
- * made through either is cleared through either, which is why the shape has
- * one home.
- */
-const timersModule = {
-  setTimeout(fn: (...a: unknown[]) => void, ms?: number, ...rest: unknown[]) {
-    return nodeTimeout(globalThis.setTimeout(fn as () => void, ms, ...rest));
-  },
-  clearTimeout(id: unknown) { return globalThis.clearTimeout(timerHandleOf(id) as number); },
-  setInterval(fn: (...a: unknown[]) => void, ms?: number, ...rest: unknown[]) {
-    return nodeTimeout(globalThis.setInterval(fn as () => void, ms, ...rest));
-  },
-  clearInterval(id: unknown) { return globalThis.clearInterval(timerHandleOf(id) as number); },
-  setImmediate(fn: (...a: unknown[]) => void, ...args: unknown[]) {
-    const realm = globalThis as unknown as { setImmediate?: (fn: (...a: unknown[]) => void, ...args: unknown[]) => unknown };
-    return nodeTimeout(realm.setImmediate
-      ? realm.setImmediate(fn, ...args)
-      : globalThis.setTimeout(fn as () => void, 0, ...args));
-  },
-  clearImmediate(id: unknown) {
-    const realm = globalThis as unknown as { clearImmediate?: (id: unknown) => void };
-    const handle = timerHandleOf(id);
-    return realm.clearImmediate ? realm.clearImmediate(handle) : globalThis.clearTimeout(handle as number);
-  },
-};
-
 /** Built on the first ask, for the reason `./binding/index.ts` gives. */
 // eslint-disable-next-line no-var, vars-on-top
 var __table: Record<string, () => unknown> | undefined;
-export function nodeLibPublic(name: string): (() => unknown) | undefined {
+export function nodeLibPublic(name: string, require?: (name: string) => any, _process?: object): (() => unknown) | undefined {
+  if (_process && name === 'timers') return () => createTimersModule(guestTimerFunctions(_process, globalThis as unknown as Record<string, unknown>));
+  if (require && name === 'crypto') return () => cryptoShim.createCryptoModule(require);
+  if (require && name === 'tls') return () => tlsShim.createTlsModule(require);
+  if (require && name === 'string_decoder') return () => createStringDecoderModule(() => require('buffer').Buffer);
   __table ??= {
-  timers: () => timersModule,
-  dns: () => dnsShim,
+  timers: createTimersModule,
+  dns: createDnsModule,
   cluster: () => clusterShim,
   string_decoder: () => stringDecoderShim,
   v8: () => v8Shim,

package/src/node-lib/sources.ts

@@ -8,6 +8,8 @@
  * text; `load.ts` evaluates it in the scope Node's `BuiltinModule` gives a
  * builtin.
  */
+import NAVIGATOR from './internal/navigator.js?raw';
+import PATH from './path.js?raw';
 import NET from './net.js?raw';
 import BUFFER from './buffer.js?raw';
 import INTERNAL_BUFFER from './internal/buffer.js?raw';
@@ -105,6 +107,8 @@ import INTERNAL_EVENTS_SYMBOLS from './internal/events/symbols.js?raw';
 export const NODE_LIB_VERSION = 'v22.18.0';
 
 export const NODE_LIB_SOURCES: Record<string, string> = {
+  'internal/navigator': NAVIGATOR,
+  path: PATH,
   'net': NET,
   'buffer': BUFFER,
   'internal/buffer': INTERNAL_BUFFER,

package/src/node-lib/timers.ts

@@ -31,3 +31,96 @@ export function nodeTimeout(id: unknown): unknown {
 export function timerHandleOf(id: unknown): unknown {
   return id && typeof id === "object" && "_id" in (id as object) ? (id as { _id: unknown })._id : id;
 }
+
+/** Native timers surface shared by both builtin loaders, fresh for each graph. */
+export function createTimersModule(owned?: {
+  setTimeout(fn: (...args: unknown[]) => void, ms?: number, ...args: unknown[]): unknown;
+  clearTimeout(id: unknown): void;
+  setInterval(fn: (...args: unknown[]) => void, ms?: number, ...args: unknown[]): unknown;
+  clearInterval(id: unknown): void;
+}) {
+  const schedule = owned?.setTimeout ?? globalThis.setTimeout.bind(globalThis);
+  const cancel = owned?.clearTimeout ?? ((id: unknown) => globalThis.clearTimeout(timerHandleOf(id) as number));
+  // Node's legacy timer list API, deprecated (DEP0095) and still exported:
+  // an object with `_onTimeout` is enrolled for a duration, made active to
+  // start or restart its countdown, and unenrolled to stop it.
+  type Enrolled = { _onTimeout?: () => void; _idleTimeout?: number; _idleTimeoutId?: unknown };
+  const unenroll = (item: Enrolled): void => {
+    if (item._idleTimeoutId) cancel(item._idleTimeoutId);
+    item._idleTimeoutId = null;
+    item._idleTimeout = -1;
+  };
+  const enroll = (item: Enrolled, msecs: number): void => {
+    if (item._idleTimeoutId) cancel(item._idleTimeoutId);
+    item._idleTimeoutId = null;
+    item._idleTimeout = msecs;
+  };
+  const active = (item: Enrolled): void => {
+    const msecs = item._idleTimeout;
+    if (typeof msecs !== 'number' || msecs < 0) return;
+    if (item._idleTimeoutId) cancel(item._idleTimeoutId);
+    item._idleTimeoutId = schedule(() => { item._idleTimeoutId = null; if (typeof item._onTimeout === 'function') item._onTimeout(); }, msecs);
+  };
+  const abortError = () => {
+    const error = new Error("The operation was aborted") as Error & { code?: string };
+    error.name = "AbortError";
+    error.code = "ABORT_ERR";
+    return error;
+  };
+  // timers/promises.setInterval was the global setInterval, which answers a
+  // handle rather than the async generator Node does, so "for await" over it
+  // never yielded; setTimeout dropped the value it was given, and neither took
+  // a signal.
+  const timersPromises = {
+    setTimeout: (delay: any, value: any, options: any) => new Promise((resolve, reject) => {
+      const signal = options && options.signal;
+      if (signal && signal.aborted) { reject(abortError()); return; }
+      const onAbort = () => { cancel(handle); reject(abortError()); };
+      const handle = schedule(() => {
+        if (signal) signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      }, delay);
+      if (signal) signal.addEventListener("abort", onAbort, { once: true });
+    }),
+    setImmediate: (value: any, options: any) => timersPromises.setTimeout(0, value, options),
+    setInterval: async function* setInterval(delay: any, value: any, options: any) {
+      const signal = options && options.signal;
+      for (;;) {
+        await timersPromises.setTimeout(delay, void 0, options);
+        if (signal && signal.aborted) return;
+        yield value;
+      }
+    },
+    scheduler: {
+      wait: (delay: any, options: any) => timersPromises.setTimeout(delay, void 0, options),
+      yield: () => timersPromises.setTimeout(0, void 0, void 0)
+    }
+  };
+  return {
+    setTimeout(fn: (...a: unknown[]) => void, ms?: number, ...rest: unknown[]) {
+      return nodeTimeout(globalThis.setTimeout(fn as () => void, ms, ...rest));
+    },
+    clearTimeout(id: unknown) { return globalThis.clearTimeout(timerHandleOf(id) as number); },
+    setInterval(fn: (...a: unknown[]) => void, ms?: number, ...rest: unknown[]) {
+      return nodeTimeout(globalThis.setInterval(fn as () => void, ms, ...rest));
+    },
+    clearInterval(id: unknown) { return globalThis.clearInterval(timerHandleOf(id) as number); },
+    setImmediate(fn: (...a: unknown[]) => void, ...args: unknown[]) {
+      const realm = globalThis as unknown as { setImmediate?: (fn: (...a: unknown[]) => void, ...args: unknown[]) => unknown };
+      return nodeTimeout(realm.setImmediate
+        ? realm.setImmediate(fn, ...args)
+        : globalThis.setTimeout(fn as () => void, 0, ...args));
+    },
+    clearImmediate(id: unknown) {
+      const realm = globalThis as unknown as { clearImmediate?: (id: unknown) => void };
+      const handle = timerHandleOf(id);
+      return realm.clearImmediate ? realm.clearImmediate(handle) : globalThis.clearTimeout(handle as number);
+    },
+    ...(owned ? {
+      ...owned,
+      setImmediate: (fn: (...args: unknown[]) => void, ...args: unknown[]) => owned.setTimeout(fn, 0, ...args),
+      clearImmediate: owned.clearTimeout,
+    } : {}),
+    active, enroll, unenroll, promises: timersPromises,
+  };
+}

package/src/node-process-host.ts

@@ -0,0 +1,124 @@
+import type { ProcessIdentity } from './process-registry';
+import type { NativeStreamDescriptor } from './native-stream-owner';
+import type { RunStreams } from './shims/child_process';
+import type { VirtualFS } from './virtual-fs';
+
+/** Trusted launch data, before Node options or the script execute in a realm. */
+export interface NodeProcessLaunch {
+  token: string;
+  identity: ProcessIdentity;
+  /** Arguments after the Node executable, preserving each parsed word. */
+  argv: readonly string[];
+  cwd: string;
+  /** This entry's filesystem view, including any host-prepared entry wrapper. */
+  filesystem: VirtualFS;
+  env: Record<string, string>;
+  stdin?: string;
+  stdinStream?: AsyncIterable<Uint8Array>;
+  streams?: RunStreams;
+  inherited: readonly { fd: number; handle: NativeStreamDescriptor }[];
+}
+
+export interface NodeProcessHost {
+  run(launch: NodeProcessLaunch): Promise<{ stdout: string; stderr: string; exitCode: number }>;
+}
+
+let host: NodeProcessHost | undefined;
+let installed = false;
+let started = false;
+let localToken: string | undefined;
+let localStarted = false;
+
+export function nodeProcessHostInstalled(): boolean { return installed; }
+
+/** Only a worker with one admitted local entry has an unambiguous realm owner. */
+export function nodeProcessRealmToken(): string | null { return localStarted ? localToken ?? null : null; }
+
+const HostTransformStream = globalThis.TransformStream;
+const HostTextEncoder = globalThis.TextEncoder;
+
+/** Adapt the engine's push sink to the worker bridge's pull-based input. */
+export function nodeProcessInput(streams: RunStreams | undefined): {
+  stream?: AsyncIterable<Uint8Array>;
+  dispose(): void;
+} {
+  if (streams?.stdinStream) return { stream: streams.stdinStream, dispose() {} };
+  if (!streams || (!streams.stdinOpen && !streams.held)) return { dispose() {} };
+  let inputController!: TransformStreamDefaultController<Uint8Array>;
+  const pipe = new HostTransformStream<Uint8Array, Uint8Array>({
+    start(controller) { inputController = controller; },
+  });
+  const writer = pipe.writable.getWriter();
+  // Cancellation is delivered through the readable side and pending writes.
+  // The host's bookkeeping promise must not become a guest rejection.
+  void writer.closed.catch(() => {});
+  const encoder = new HostTextEncoder();
+  let disposed = false;
+  let ended = false;
+  const write = (chunk: string | Uint8Array | null): Promise<void> => {
+    if (chunk === null) {
+      if (ended) return Promise.resolve();
+      ended = true;
+      return writer.close();
+    }
+    if (ended || disposed) return Promise.reject(new Error('Node process input is closed.'));
+    const bytes = typeof chunk === 'string' ? encoder.encode(chunk) : new Uint8Array(chunk);
+    return writer.write(bytes);
+  };
+  const dispose = (): void => {
+    if (disposed) return;
+    disposed = true;
+    streams.signal?.removeEventListener('abort', dispose);
+    // Error both sides, which also releases a write waiting for readable
+    // demand. Aborting only the writer can wait behind that blocked write.
+    inputController.error(streams.signal?.reason ?? new Error('Node process input stopped.'));
+  };
+  streams.signal?.addEventListener('abort', dispose, { once: true });
+  if (streams.signal?.aborted) dispose();
+  streams.stdin = {
+    emit() {},
+    // The host's legacy sendInput is fire-and-forget. Forked pipes use the
+    // acknowledged door below and stop reading while its promise is pending.
+    push(chunk) { void write(chunk).catch(dispose); return (writer.desiredSize ?? 0) > 0; },
+    writeAsync: write,
+  };
+  return {
+    stream: {
+      async *[Symbol.asyncIterator]() {
+        const reader = pipe.readable.getReader();
+        void reader.closed.catch(() => {});
+        let completed = false;
+        try {
+          for (;;) {
+            const next = await reader.read();
+            if (next.done) { completed = true; return; }
+            yield next.value;
+          }
+        } finally { reader.releaseLock(); if (!completed) dispose(); }
+      },
+    },
+    dispose,
+  };
+}
+
+/** Host bootstrap only. A process worker admits exactly one local Node entry. */
+export function installNodeProcessHost(next: NodeProcessHost, token?: string): void {
+  if (installed || started) throw new Error('Node process host must be installed once before Node execution.');
+  if (typeof next?.run !== 'function' || (token !== undefined && (typeof token !== 'string' || !token.length))) {
+    throw new Error('Invalid Node process host.');
+  }
+  host = next;
+  localToken = token;
+  installed = true;
+}
+
+/** Called by the common Node command entry, including engine-first forks. */
+export function nodeProcessHostFor(token: string | null): NodeProcessHost | undefined {
+  started = true;
+  if (!host) return undefined;
+  if (token === null) throw new Error('Isolated Node execution requires a named run.');
+  if (token !== localToken) return host;
+  if (localStarted) throw new Error('This worker has already executed its admitted Node process.');
+  localStarted = true;
+  return undefined;
+}