@volter/tabnode 0.4.0 → 0.5.0

package/dist/node-lib/binding/process_wrap.d.ts

@@ -21,7 +21,8 @@
 import { LibuvStreamWrap } from './stream_wrap';
 import { Pipe } from './pipe_wrap';
 import { type OwnedHandle } from './handles';
-import type { ProcessToken } from '../../process-tokens';
+import { type ProcessToken } from '../../process-tokens';
+import { type TerminalState } from './tty_wrap';
 /** One entry of Node's `options.stdio`, as `getValidStdio` builds it. */
 export interface StdioEntry {
     type: 'pipe' | 'overlapped' | 'ignore' | 'inherit' | 'fd' | 'wrap';
@@ -75,8 +76,17 @@ export interface RunRequest {
     stderrIsPipe: boolean;
     /** True when the child's fd 0 is a pipe whose writer has not closed. */
     stdinIsPipe: boolean;
+    terminal?: TerminalState;
     /** The IPC channel the child is started with, where it has one. */
     channel?: RunChannel;
+    /**
+     * The child's pipes past fd 2 (`stdio: [..., 'pipe', 'pipe']`), each at the
+     * number the child reads or writes it by, with the child's end of it.
+     */
+    descriptors: {
+        fd: number;
+        pipe: Pipe;
+    }[];
     /** Called once, when the run has ended. */
     exit(code: number, signal: string | null): void;
 }
@@ -89,7 +99,7 @@ export interface StartedRun {
     /** libuv's `uv_process_kill`: 0, or `UV_ESRCH` for a run already over. */
     kill(signal: string): number;
     /** Bytes the parent wrote to the child's fd 0. */
-    writeStdin(bytes: Uint8Array): void;
+    writeStdin(bytes: Uint8Array): void | Promise<void>;
     /** The parent closed the child's fd 0. */
     endStdin(): void;
 }
@@ -126,6 +136,7 @@ export declare class Process implements OwnedHandle {
     private closed;
     /** The stdio entries this run was started with, and their far ends. */
     private stdio;
+    private terminalEnds;
     private readonly asyncId;
     constructor();
     getAsyncId(): number;

package/dist/node-lib/binding/stream_wrap.d.ts

@@ -37,11 +37,10 @@ interface Inbound {
  * The base every `TCP` and `Pipe` extends, as `LibuvStreamWrap` is the base of
  * libuv's `uv_stream_t` wrappers.
  *
- * A pairing is two of these with `peer` pointing at each other. A write copies
- * its bytes and hands them to the peer on a microtask, because libuv never
- * delivers a read inside the write that caused it; the peer delivers them to
- * `onread` while it is reading and holds them while it is not, which is what
- * `readStart` and `readStop` mean.
+ * A pairing joins two connection endpoints. Duplicated wrappers reference the
+ * same endpoint and consume its bytes once. A write queues a copy at the peer;
+ * reads are delivered on its own turn while a wrapper is reading, which is
+ * what `readStart` and `readStop` mean.
  */
 export declare class LibuvStreamWrap implements OwnedHandle {
     /** Set by `net.js` to `onStreamRead`; the only way bytes reach a stream. */
@@ -54,8 +53,9 @@ export declare class LibuvStreamWrap implements OwnedHandle {
     writeQueueSize: number;
     /** The engine has no descriptors for a paired handle, as libuv reports -1 for one it has no fd for. */
     fd: number;
-    /** The other end of the pairing, once there is one. */
-    peer: LibuvStreamWrap | null;
+    private streamEndpoint;
+    /** A live wrapper on the other end, including after the original was closed. */
+    get peer(): LibuvStreamWrap | null;
     /** True once `close()` has been called; a closed handle carries nothing. */
     closed: boolean;
     /**
@@ -64,13 +64,14 @@ export declare class LibuvStreamWrap implements OwnedHandle {
      * thing in a pipe's pending-handle queue.
      */
     pendingHandle: unknown;
-    protected inbound: Inbound[];
-    protected inboundEof: boolean;
-    protected inboundError: number | null;
+    protected get inbound(): Inbound[];
+    protected get inboundEof(): boolean;
+    protected get inboundError(): number | null;
     protected eofDelivered: boolean;
     protected userBuffer: Uint8Array | null;
     protected readonly asyncId: number;
     constructor();
+    protected attachNative(kind: 'tcp' | 'pipe', type: number): void;
     getAsyncId(): number;
     ref(): void;
     unref(): void;
@@ -84,18 +85,19 @@ export declare class LibuvStreamWrap implements OwnedHandle {
      * reads EOF. The request completes on its own turn, as libuv's does.
      */
     shutdown(req: ShutdownWrap): number;
-    writeBuffer(req: WriteWrap, buffer: Uint8Array): number;
+    writeBuffer(req: WriteWrap, buffer: Uint8Array, handle?: unknown): number;
     writev(req: WriteWrap, chunks: unknown[], allBuffers: boolean): number;
     writeUtf8String(req: WriteWrap, text: string, handle?: unknown): number;
     writeAsciiString(req: WriteWrap, text: string): number;
     writeLatin1String(req: WriteWrap, text: string): number;
     writeUcs2String(req: WriteWrap, text: string): number;
     /**
-     * libuv's `uv_close`. The peer reads EOF, as it does when the other end of a
-     * socket goes; the callback runs on its own turn, because `net.js` emits
+     * libuv's `uv_close`. The peer reads EOF when the last descriptor closes;
+     * the callback runs on its own turn, because `net.js` emits
      * `close` from it and Node emits that after the turn that destroyed.
      */
     close(callback?: () => void): void;
+    private closeLocal;
     /** What a `TCP` or a `Pipe` gives up beyond the stream: a port, a path. */
     protected onCloseHandle(): void;
     /**
@@ -108,14 +110,22 @@ export declare class LibuvStreamWrap implements OwnedHandle {
      * for both, that close ended the connection the child had just been given
      * and its first write was `EBADF`.
      *
-     * The duplicate takes over this end of the pairing and this end is left
-     * peerless, so closing it announces nothing -- the sender has already given
-     * the socket up (`handleConversion`'s `send` sets `socket._handle = null`
-     * and silences its reads before the write).
+     * Both descriptors share the connection and its unread bytes. Node may
+     * close the sender on acknowledgement or keep it open; the binding must
+     * support either, without knowing the child_process option that chose it.
      */
     duplicate(): LibuvStreamWrap;
     /** Two handles become each other's peer; what one writes the other reads. */
     static pair(a: LibuvStreamWrap, b: LibuvStreamWrap): void;
+    /** A fresh wrapper acquires a descriptor reference on this connection. */
+    protected shareConnectionFrom(other: LibuvStreamWrap): void;
+    /** Native connection resources outlive individual duplicated wrappers. */
+    protected onLastReferenceClose(callback: () => void): void;
+    /** Host transports bound copies waiting in the native receiving queue. */
+    get peerQueuedBytes(): number;
+    get peerQueuedHandles(): number;
+    /** Changes to the same connection end, even after its wrapper is replaced. */
+    onPeerReadCapacity(listener: () => void): () => void;
     /**
      * Take over another handle's end of a pairing, with everything that arrived
      * on it while nobody was holding it. This is what opening a descriptor is
@@ -167,7 +177,6 @@ export declare class LibuvStreamWrap implements OwnedHandle {
      * libuv's loop reads in: everything a writer did in one turn is read in the
      * order it did it, and never from inside the call that did it.
      */
-    private flushScheduled;
     protected scheduleFlush(): void;
     /**
      * Hand what has arrived to `onStreamRead`, in libuv's shape: the byte count

package/dist/node-lib/binding/tcp_wrap.d.ts

@@ -53,7 +53,6 @@ export declare class TCP extends LibuvStreamWrap {
     onconnection: ((status: number, clientHandle: TCP) => void) | null;
     private local;
     private remote;
-    private ephemeral;
     constructor(type?: number);
     bind(address: string, port: number, _flags?: number): number;
     bind6(address: string, port: number, _flags?: number): number;

package/dist/node-lib/binding/tty_wrap.d.ts

@@ -9,10 +9,34 @@
  * when the running program's own `process.stdout.isTTY` says so -- which is
  * what a held run gets, and what a program reads to decide on colour.
  */
-import { LibuvStreamWrap } from './stream_wrap';
+import { LibuvStreamWrap, type WriteWrap } from './stream_wrap';
+export interface TerminalState {
+    columns: number;
+    rows: number;
+    onResize(listener: (columns: number, rows: number) => void): () => void;
+    resize(columns: number, rows: number): void;
+}
+/** One terminal endpoint, shared by independently owned descriptors. */
+declare class TerminalEndpoint {
+    readonly terminal: TerminalState;
+    readonly slave: boolean;
+    readonly descriptors: Set<TTY>;
+    readonly readers: Set<TTY>;
+    readonly input: Uint8Array[];
+    peer?: TerminalEndpoint;
+    eof: boolean;
+    scheduled: boolean;
+    constructor(terminal: TerminalState, slave: boolean);
+    pump(): void;
+    release(descriptor: TTY): void;
+}
 /** libuv's `uv_tty_t`, over the same stream the rest of the binding is. */
 export declare class TTY extends LibuvStreamWrap {
-    readonly fdNumber: number;
+    get fdNumber(): number;
+    readonly descriptor: TTY;
+    private endpoint?;
+    get terminal(): TerminalState | undefined;
+    get slave(): boolean;
     /**
      * Node's `new TTY(fd, ctx)` writes an errno onto `ctx` when the fd is not
      * a terminal, so `tty.WriteStream` refuses to wrap a pipe. A run's stdout
@@ -25,11 +49,28 @@ export declare class TTY extends LibuvStreamWrap {
     /** A terminal the engine does not own has one size and no mode to set. */
     getWindowSize(out: number[]): number;
     setRawMode(_raw: number): number;
+    static allocate(endpoint: TerminalEndpoint): TTY;
+    /** Inheritance duplicates the fd; neither process owns the other's ref. */
+    duplicate(): TTY;
+    readStart(): number;
+    /** Delivered into Node's existing stream binding, preserving backpressure. */
+    deliver(bytes: Uint8Array): void;
+    protected dispatchWrite(req: WriteWrap, bytes: Uint8Array): number;
+    protected onCloseHandle(): void;
 }
+/** Host OS adapter door. The process host retains terminal behavior. */
+export declare function openPty(columns: number, rows: number): {
+    master: number;
+    slave: number;
+    pty: string;
+};
+export declare function resizePty(fd: number, columns: number, rows: number): void;
 /** libuv's `uv_guess_handle(fd) === UV_TTY`, as the running program sees it. */
 export declare function isTTY(fd: number): boolean;
 declare const _default: {
     TTY: typeof TTY;
     isTTY: typeof isTTY;
+    openPty: typeof openPty;
+    resizePty: typeof resizePty;
 };
 export default _default;

package/dist/node-lib/binding/util.d.ts

@@ -123,3 +123,86 @@ export declare const utilBinding: {
     sleep: (milliseconds: number) => void;
 };
 export default utilBinding;
+/** Lazy builtin exports must resolve inside the requesting process. */
+export declare function createUtilBinding(require: (name: string) => unknown): {
+    defineLazyProperties: (target: object, id: string, keys: string[], writable?: boolean) => void;
+    privateSymbols: {
+        arrow_message_private_symbol: symbol;
+        decorated_private_symbol: symbol;
+        untransferable_object_private_symbol: symbol;
+        host_defined_option_symbol: symbol;
+        transfer_mode_private_symbol: symbol;
+    };
+    constants: {
+        ALL_PROPERTIES: number;
+        ONLY_WRITABLE: number;
+        ONLY_ENUMERABLE: number;
+        ONLY_CONFIGURABLE: number;
+        SKIP_STRINGS: number;
+        SKIP_SYMBOLS: number;
+        kPending: number;
+        kFulfilled: number;
+        kRejected: number;
+    };
+    /** Node warns differently for a deprecation raised inside a dependency; nothing here is. */
+    isInsideNodeModules: () => boolean;
+    /**
+     * An object's own properties that are not array indices, filtered the way
+     * V8's `GetOwnNonIndexProperties` filters: `ONLY_ENUMERABLE` keeps the
+     * enumerable ones, `SKIP_SYMBOLS` and `SKIP_STRINGS` drop a kind outright.
+     * `inspect` asks for this to list an array's non-index keys and a typed
+     * array's own properties without walking its elements.
+     */
+    getOwnNonIndexProperties: (target: object, filter?: number) => Array<string | symbol>;
+    /** The promise loss named at the top of this file. */
+    getPromiseDetails: () => [number];
+    /** The proxy loss named at the top of this file. */
+    getProxyDetails: () => undefined;
+    /**
+     * The entries inside a `Map` or a `Set`, which `inspect` prints. V8 reads
+     * them out of the object's own storage; this reads them the way any program
+     * does, which answers for a real map or set. An ITERATOR over one keeps its
+     * position in V8's own state and cannot be previewed without consuming it,
+     * so an iterator previews as empty rather than being spent -- a printed
+     * value is not worth destroying the thing printed.
+     */
+    previewEntries: (value: unknown, isIterator?: boolean) => [unknown[], boolean];
+    /**
+     * The name of the constructor that made a value, as V8 reports it: the
+     * first prototype in the chain with an own `constructor` whose name is not
+     * empty. `inspect` prints it before an object's braces.
+     */
+    getConstructorName: (value: object) => string;
+    /** A pointer's value, printed for an external. A tab has no externals. */
+    getExternalValue: () => bigint;
+    /** What kind of thing a descriptor is, out of the engine's own table. */
+    guessHandleType: typeof guessHandleTypeOfFd;
+    /**
+     * The stack, as `util.getCallSites()` reports it: one entry per frame with
+     * the function's name, the script it is in, and where in that script. V8's
+     * own structured-stack door is what Node reads too -- `Error
+     * .prepareStackTrace` handed an array of call sites -- so this asks the
+     * realm the same question and shapes the answer the same way. The harness
+     * of Node's own tests calls it on every `mustNotCall`, which is why a
+     * missing one showed up as thirty test files at once.
+     */
+    getCallSites: (frameCount?: number) => Array<Record<string, unknown>>;
+    /**
+     * A `.env` file's contents as an object, which `util.parseEnv` returns and
+     * which `--env-file` loads a process's environment from. Node parses it in
+     * C++; the rules are the ones its own fixture states, and they are the
+     * whole of the format: a `KEY=VALUE` per line, `export ` allowed in front
+     * of the key and dropped, a `#` starting a comment outside quotes wherever
+     * it stands -- `a#b` is `a`, no space needed -- and a
+     * value that may be wrapped in single quotes, double quotes or backticks --
+     * a quoted value keeps its spaces and may run over several lines, and only
+     * a double-quoted one expands `\n` and `\r`.
+     */
+    parseEnv: (content: string) => Record<string, string>;
+    /**
+     * A blocking sleep. A tab has one thread and nothing else can run while
+     * this spins, which is exactly what a blocking sleep is; only a program
+     * that asked for one gets it.
+     */
+    sleep: (milliseconds: number) => void;
+};

package/dist/node-lib/binding/uv.d.ts

@@ -23,9 +23,13 @@ export declare const UV_ENOTCONN: number;
 export declare const UV_ECANCELED: number;
 export declare const UV_ENOTSUP: number;
 export declare const UV_EBADF: number;
+export declare const UV_EIO: number;
 export declare const UV_ENOSYS: number;
 export declare const UV_EADDRNOTAVAIL: number;
 export declare const UV_EACCES: number;
 export declare const UV_ENOBUFS: number;
+export declare const UV_EMFILE: number;
+export declare const UV_EBUSY: number;
+export declare const UV_EALREADY: number;
 export declare const UV_ESRCH: number;
 export default uvBinding;

package/dist/node-lib/fs-module.d.ts

@@ -1,4 +1,5 @@
 export declare const fsModule: Record<string, unknown>;
 export declare const fsPromisesModule: Record<string, unknown>;
+/** Every guest, including the first, owns its builtin graph. */
 export declare function fsModuleFor(process: object): unknown;
 export default fsModule;

package/dist/node-lib/internals/buffer-and-streams.d.ts

@@ -72,24 +72,37 @@ export declare const internalFile: {
  * not guessed at.
  */
 type AnyStream = Record<string, (...args: never[]) => unknown> & Record<string, unknown>;
-declare function newReadableStreamFromStreamReadable(readable: AnyStream): ReadableStream;
-declare function newStreamReadableFromReadableStream(web: ReadableStream): AnyStream;
-declare function newWritableStreamFromStreamWritable(writable: AnyStream): WritableStream;
-declare function newStreamWritableFromWritableStream(web: WritableStream): AnyStream;
-declare function newReadableWritablePairFromDuplex(duplex: AnyStream): {
-    readable: ReadableStream;
-    writable: WritableStream;
+/** Capture the owning graph; callbacks must not fall back to the host loader. */
+export declare function createWebStreamsAdapters(require?: (name: string) => unknown): {
+    newReadableStreamFromStreamReadable: (readable: AnyStream, options?: {
+        strategy?: QueuingStrategy;
+    }) => ReadableStream;
+    newStreamReadableFromReadableStream: (web: ReadableStream) => AnyStream;
+    newWritableStreamFromStreamWritable: (writable: AnyStream) => WritableStream;
+    newStreamWritableFromWritableStream: (web: WritableStream) => AnyStream;
+    newReadableWritablePairFromDuplex: (duplex: AnyStream) => {
+        readable: ReadableStream;
+        writable: WritableStream;
+    };
+    newStreamDuplexFromReadableWritablePair: (pair: {
+        readable: ReadableStream;
+        writable: WritableStream;
+    }) => AnyStream;
 };
-declare function newStreamDuplexFromReadableWritablePair(pair: {
-    readable: ReadableStream;
-    writable: WritableStream;
-}): AnyStream;
 export declare const internalWebStreamsAdapters: {
-    newReadableStreamFromStreamReadable: typeof newReadableStreamFromStreamReadable;
-    newStreamReadableFromReadableStream: typeof newStreamReadableFromReadableStream;
-    newWritableStreamFromStreamWritable: typeof newWritableStreamFromStreamWritable;
-    newStreamWritableFromWritableStream: typeof newStreamWritableFromWritableStream;
-    newReadableWritablePairFromDuplex: typeof newReadableWritablePairFromDuplex;
-    newStreamDuplexFromReadableWritablePair: typeof newStreamDuplexFromReadableWritablePair;
+    newReadableStreamFromStreamReadable: (readable: AnyStream, options?: {
+        strategy?: QueuingStrategy;
+    }) => ReadableStream;
+    newStreamReadableFromReadableStream: (web: ReadableStream) => AnyStream;
+    newWritableStreamFromStreamWritable: (writable: AnyStream) => WritableStream;
+    newStreamWritableFromWritableStream: (web: WritableStream) => AnyStream;
+    newReadableWritablePairFromDuplex: (duplex: AnyStream) => {
+        readable: ReadableStream;
+        writable: WritableStream;
+    };
+    newStreamDuplexFromReadableWritablePair: (pair: {
+        readable: ReadableStream;
+        writable: WritableStream;
+    }) => AnyStream;
 };
 export {};

package/dist/node-lib/internals/index.d.ts

@@ -1 +1 @@
-export declare function nodeLibInternal(name: string): (() => unknown) | undefined;
+export declare function nodeLibInternal(name: string, require?: (name: string) => any, process?: any): (() => unknown) | undefined;

package/dist/node-lib/load.d.ts

@@ -7,11 +7,24 @@ export declare function nodeLibProcessOf(): Record<string, unknown>;
  * partly-filled `exports` rather than looping.
  */
 export declare function loadNodeLib(name: string): unknown;
-export declare function esmNamespaceOf(mod: unknown): Record<string, unknown>;
+export declare function esmNamespaceOf(mod: unknown, owner?: object): Record<string, unknown>;
 /** Node's `module.syncBuiltinESMExports`: newly assigned CJS keys appear on the namespace. */
-export declare function syncBuiltinESMExports(): void;
+export declare function syncBuiltinESMExports(owner?: object): void;
 export declare function loadNodeLibInstance(name: string): unknown;
-export declare function loadNodeLibFor(owner: object, name: string): unknown;
+/**
+ * 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.
+ */
+export type NodeLibRequire = (name: string) => any;
+type ModuleInitializer = (name: string, value: any, require: NodeLibRequire) => void;
+/** Host bootstrap adapters are applied to each newly compiled builtin. */
+export declare function onNodeLibLoaded(initialize: ModuleInitializer): () => void;
+/** Native implementations can be shared; their exported module records cannot. */
+export declare function moduleSurface(value: any, seen?: Map<object, any>): any;
+export declare function loadNodeLibFor(owner: object, name: string): any;
+export declare function hasNodeLibModule(name: string): boolean;
+export declare function nativeModuleFor(owner: object, name: string, create: () => unknown): unknown;
 /**
  * What a hand-bound internal, a binding or `./lazy.ts` calls to reach a
  * vendored file.
@@ -24,3 +37,4 @@ export declare function loadNodeLibFor(owner: object, name: string): unknown;
  * in its temporal dead zone and the engine failed to load at all.
  */
 export declare function nodeLibInternalRequire(specifier: string): unknown;
+export {};

package/dist/node-lib/module-hooks.d.ts

@@ -47,6 +47,7 @@ export declare class RunModuleHooks {
     #private;
     /** The vendored file's own instance, this run's alone. */
     readonly sync: CustomizationHooks;
+    constructor(process: object);
     /**
      * Which chain has anything in it. The loader asks before it builds
      * anything: a run that registered no hook pays for none, which is the fast

package/dist/node-lib/public-modules.d.ts

@@ -1 +1 @@
-export declare function nodeLibPublic(name: string): (() => unknown) | undefined;
+export declare function nodeLibPublic(name: string, require?: (name: string) => any, _process?: object): (() => unknown) | undefined;

package/dist/node-lib/timers.d.ts

@@ -16,3 +16,41 @@
 export declare function nodeTimeout(id: unknown): unknown;
 /** The realm's own id inside a {@link nodeTimeout}, for the clear that takes one. */
 export declare function timerHandleOf(id: unknown): unknown;
+/** Native timers surface shared by both builtin loaders, fresh for each graph. */
+export declare 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;
+}): {
+    active: (item: {
+        _onTimeout?: () => void;
+        _idleTimeout?: number;
+        _idleTimeoutId?: unknown;
+    }) => void;
+    enroll: (item: {
+        _onTimeout?: () => void;
+        _idleTimeout?: number;
+        _idleTimeoutId?: unknown;
+    }, msecs: number) => void;
+    unenroll: (item: {
+        _onTimeout?: () => void;
+        _idleTimeout?: number;
+        _idleTimeoutId?: unknown;
+    }) => void;
+    promises: {
+        setTimeout: (delay: any, value: any, options: any) => Promise<unknown>;
+        setImmediate: (value: any, options: any) => Promise<unknown>;
+        setInterval: (delay: any, value: any, options: any) => AsyncGenerator<any, void, unknown>;
+        scheduler: {
+            wait: (delay: any, options: any) => Promise<unknown>;
+            yield: () => Promise<unknown>;
+        };
+    };
+    setImmediate: (fn: (...a: unknown[]) => void, ...args: unknown[]) => unknown;
+    clearImmediate: (id: unknown) => void;
+    setTimeout: (fn: (...args: unknown[]) => void, ms?: number, ...args: unknown[]) => unknown;
+    clearTimeout: (id: unknown) => void;
+    setInterval: (fn: (...a: unknown[]) => void, ms?: number, ...rest: unknown[]) => unknown;
+    clearInterval: (id: unknown) => void;
+};

package/dist/node-process-host.d.ts

@@ -0,0 +1,41 @@
+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;
+    }>;
+}
+export declare function nodeProcessHostInstalled(): boolean;
+/** Only a worker with one admitted local entry has an unambiguous realm owner. */
+export declare function nodeProcessRealmToken(): string | null;
+/** Adapt the engine's push sink to the worker bridge's pull-based input. */
+export declare function nodeProcessInput(streams: RunStreams | undefined): {
+    stream?: AsyncIterable<Uint8Array>;
+    dispose(): void;
+};
+/** Host bootstrap only. A process worker admits exactly one local Node entry. */
+export declare function installNodeProcessHost(next: NodeProcessHost, token?: string): void;
+/** Called by the common Node command entry, including engine-first forks. */
+export declare function nodeProcessHostFor(token: string | null): NodeProcessHost | undefined;

package/dist/process-registry.d.ts

@@ -0,0 +1,39 @@
+/** Native process identity shared by the container's worker realms. */
+export interface ProcessIdentity {
+    readonly pid: number;
+    readonly ppid: number;
+}
+/** A run already admitted by the container owner into this realm's scope. */
+export interface InitialProcessRegistration {
+    readonly token: string;
+    readonly identity: ProcessIdentity;
+}
+/** Installed by the trusted embedding host before this realm starts runs. */
+export interface ProcessRegistry {
+    allocate(): number;
+    publish(token: string, identity: ProcessIdentity): void;
+    forget(token: string): void;
+    lookup(pid: number): ProcessIdentity | undefined;
+    /**
+     * `kill(pid, signal)` for a live process of another realm in this container:
+     * whether a process there took the signal. A machine lets a process signal
+     * any process of its user, including one its parent left behind.
+     */
+    signal(pid: number, signal: string): boolean;
+}
+export interface ProcessRegistryScope extends ProcessRegistry {
+    /** Trusted owner only: how this realm answers a signal sent to one of its processes. */
+    receiveSignals(handler: (pid: number, signal: string) => boolean): void;
+    /** Trusted owner handoff before the destination worker starts; not a guest operation. */
+    adoptRun(source: ProcessRegistryScope, sourceToken: string, token: string, parentPid?: number): ProcessIdentity;
+    /** Ends this realm's registrations, including after abrupt worker death. */
+    dispose(): void;
+}
+/**
+ * One container owns the counter and live table. Each realm receives a scope,
+ * so identical local run tokens cannot overwrite or release another realm's
+ * process. Allocation alone does not announce a live process.
+ */
+export declare function createProcessRegistryOwner(): {
+    createScope(): ProcessRegistryScope;
+};

package/dist/process-tokens.d.ts

@@ -14,12 +14,18 @@
  * for both. The guest never sees the variable: the environment the `node`
  * command gives its process has it removed.
  */
+import type { Process } from './shims/process';
+import { type ProcessRegistry, type ProcessRegistryScope, type InitialProcessRegistration } from './process-registry';
 /** Whatever the embedding runtime uses to name one guest process. */
 export type ProcessToken = string;
 /** The environment variable a run's name travels in, from `exec` to `node`. */
 export declare const PROCESS_TOKEN_ENV = "__TABNODE_PROCESS_TOKEN";
 /** What the engine can answer about one named run. */
 export interface OwnedRun {
+    /** The guest whose cwd and inherited streams belong to this run. */
+    process: Process;
+    stdout(text: string): void;
+    stderr(text: string): void;
     /** The timers the run's guest still holds, as Node's loop counts them. */
     pendingTimers(): number;
     /** Clear those timers, as ending the process clears them. */
@@ -38,6 +44,8 @@ export declare function enterRun<T>(token: ProcessToken, fn: () => T): T;
  * releasing twice is harmless, as a run ends once.
  */
 export declare function __recordRun(token: ProcessToken, run: OwnedRun): () => void;
+/** Bound guest globals retain their actual process across native await turns. */
+export declare function __tokenForProcess(process: Process): ProcessToken | null;
 /** The run recorded under this name, while it lasts. */
 export declare function __runFor(token: ProcessToken): OwnedRun | undefined;
 /**
@@ -56,6 +64,12 @@ export declare function __currentProcessToken(): ProcessToken | null;
  * half, `__releaseOwnedServers`, which calls this for the timers.
  */
 export declare function __stopOwnedProcess(token: ProcessToken): void;
+/** Each child realm gets its own registration authority in this container. */
+export declare function createProcessRegistryScope(): ProcessRegistryScope;
+/** Trusted container owner only; worker clients cannot expose their authority. */
+export declare function ownerProcessRegistryScope(): ProcessRegistryScope;
+/** Startup-only host seam; never swap identity authorities under live runs. */
+export declare function installProcessRegistry(registry: ProcessRegistry, initial?: InitialProcessRegistration): void;
 /** The next process number this engine hands out. */
 export declare function mintPid(): number;
 /** Record the numbers a named run was started with, for the run to read back. */
@@ -69,6 +83,8 @@ export declare function runPid(token: ProcessToken | null | undefined): {
 export declare function forgetRunPid(token: ProcessToken): void;
 /** Whether a live run carries this number, which is what `kill(pid, 0)` asks. */
 export declare function pidIsLive(pid: number): boolean;
+/** `kill(pid, signal)` to another realm's live process; whether one took it. */
+export declare function signalPid(pid: number, signal: string): boolean;
 /** The numbers a live process carries, looked up by its own pid. */
 export declare function processByPid(pid: number): {
     pid: number;

package/dist/promise-ownership.d.ts

@@ -0,0 +1,3 @@
+export declare const intrinsicPromise: PromiseConstructor;
+export declare function promiseOwner(promise: unknown): object | undefined;
+export declare function guestPromise(owner: object): PromiseConstructor;

package/dist/runtime.d.ts

@@ -7,15 +7,7 @@
 import { VirtualFS } from './virtual-fs';
 import type { IExecuteResult } from './runtime-interface';
 import { Process } from './shims/process';
-export declare function pendingGuestTimers(process: Process): number;
-/**
- * Clear every timer a guest still holds, as ending a Node process clears the
- * ones its loop was waiting on. The ids were made by the host's own
- * `setTimeout`/`setInterval` through the guest's global view, so the host's
- * own clears end them; a `Timeout` is cleared by either in Node, and either
- * refusing an id of the other kind is not an error here.
- */
-export declare function stopGuestTimers(process: Process): void;
+export { pendingGuestTimers, stopGuestTimers } from './guest-timers';
 export declare function __substratePendingOf(value: unknown): Promise<void> | undefined;
 export interface Module {
     id: string;
@@ -69,6 +61,15 @@ export declare class Runtime {
         exports: unknown;
         module: Module;
     };
+    /**
+     * Runs source that is not a file of the tree -- `node -e`'s, named
+     * `[eval]` in the directory it runs in, as Node names it -- the way
+     * `execute` runs a file's, without writing it anywhere.
+     */
+    evaluate(code: string, filename: string): {
+        exports: unknown;
+        module: Module;
+    };
     /**
      * Execute code as a module (async version for IRuntime interface)
      * Alias: executeSync() is the same as execute() for backward compatibility