batteries/isolation/child_process

Remarks

Node-only. This subpath barrel imports node:child_process directly and will not load in a browser or Web Worker bundle — deliberately, unlike the main @nhtio/adk/batteries/isolation barrel (../index.ts), which stays environment-neutral (zero node:* imports anywhere in its own module graph) so it can be imported from isomorphic code. Import THIS subpath only from node-only entry points (a server process, a build script, a node-targeted worker pool manager) — never from code that might also run in a browser.

Why a child process instead of worker_threads? Both give you a separate V8 isolate and a message-passing channel, but they differ in exactly the failure mode this battery exists to contain: a Worker thread shares the host process's address space and, on some native-addon segfaults or a V8 fatal error, can bring the ENTIRE host process down with it — there is no way to "just terminate the worker" once the underlying process has already crashed. A child_process is a genuinely separate OS process: a native crash, an out-of-memory kill, or an uncaught fatal error inside the guest terminates only that process. The host observes it as an ordinary 'exit'/'error' event (surfaced here via @nhtio/adk/batteries/isolation!IsolationTransport.onCrash) and can recycle() a fresh one without the calling process/agent ever going down. For untrusted or native-dependency-heavy guest code (the isolation battery's core use case), that process-level containment is the entire point — trading a bit of IPC overhead and startup latency for a hard fault boundary worker_threads cannot offer.

Interfaces

Interface	Description
ForkIsolatedModuleOptions	The { modulePath, forkOptions? } variant of ForkIsolatedOptions — spawns via this module's own node:child_process.fork() call.
ForkIsolatedResolverOptions	The { spawn } variant of ForkIsolatedOptions — spawns via a caller-supplied ChildResolver instead of this module's own fork().
IsolatedChildLike	The minimal Node ChildProcess-shaped duck this transport drives. Structurally satisfied by BOTH:

Type Aliases

Type Alias	Description
ChildResolver	A BYO-spawner resolver — the seam for callers who need their own process manager (a pool, custom stdio, a sandboxing wrapper, or a library like execa) instead of this module's own default fork(). Invoked once per connect() (including every recycle()), i.e. once per guest spawn.
ForkIsolatedOptions	Options accepted by forkIsolated/createChildProcessTransport — extends host.ts's @nhtio/adk/batteries/isolation!IsolatedServiceOptions with exactly one of the two mutually exclusive spawn shapes: ForkIsolatedModuleOptions (the common fork()-a-module case) or ForkIsolatedResolverOptions (BYO spawner). Supplying both modulePath/forkOptions AND spawn (or neither) fails eager validation with @nhtio/adk/batteries/isolation!E_INVALID_ISOLATION_OPTIONS.

Functions

Function	Description
createChildProcessTransport	Build a real @nhtio/adk/batteries/isolation!IsolationTransport over a node child_process (or BYO-resolved) child. connect() spawns a fresh child every call (including every recycle() — there is no child reuse); terminate() sends SIGTERM (or forkOptions.killSignal/the resolver's own convention) without waiting for exit or imposing any grace period of its own (host.ts already owns that via disposeGraceMs).
forkIsolated	Sugar over createChildProcessTransport + @nhtio/adk/batteries/isolation!createIsolatedService — the one-call entry point most callers want: fork a guest module (or BYO-spawn one) and get back a ready-to-use @nhtio/adk/batteries/isolation!IsolatedService.