@orkestrel/process 0.0.10 → 0.0.11

package/dist/src/server/index.d.cts

@@ -1,31 +1,24 @@
 import { Buffer as Buffer_2 } from 'node:buffer';
-import { DetachOptions } from '@orkestrel/process';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { ExecutableOptions } from '@orkestrel/process';
-import { ExecuteInput } from '@orkestrel/process';
-import { ExecuteOptions } from '@orkestrel/process';
-import { ExecuteResult } from '@orkestrel/process';
-import { ExecuteSyncOptions } from '@orkestrel/process';
-import { ProcessCommand } from '@orkestrel/process';
-import { ProcessEventMap } from '@orkestrel/process';
-import { ProcessExit } from '@orkestrel/process';
-import { ProcessExit as ProcessExit_2 } from '@orkestrel/process';
-import { ProcessInterface } from '@orkestrel/process';
-import { ProcessInterface as ProcessInterface_2 } from '@orkestrel/process';
-import { ProcessManagerEventMap } from '@orkestrel/process';
-import { ProcessManagerInterface } from '@orkestrel/process';
-import { ProcessManagerInterface as ProcessManagerInterface_2 } from '@orkestrel/process';
-import { ProcessManagerOptions } from '@orkestrel/process';
-import { ProcessManagerOptions as ProcessManagerOptions_2 } from '@orkestrel/process';
-import { ProcessOptions } from '@orkestrel/process';
-import { ProcessOptions as ProcessOptions_2 } from '@orkestrel/process';
-import { Readable } from 'node:stream';
-import { SessionEventMap } from '@orkestrel/process';
-import { SessionInterface } from '@orkestrel/process';
-import { SessionInterface as SessionInterface_2 } from '@orkestrel/process';
-import { SessionOptions } from '@orkestrel/process';
-import { SessionOptions as SessionOptions_2 } from '@orkestrel/process';
-import { SpawnInput } from '@orkestrel/process';
+import type { DetachOptions } from '@orkestrel/process';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { ExecutableOptions } from '@orkestrel/process';
+import type { ExecuteInput } from '@orkestrel/process';
+import type { ExecuteOptions } from '@orkestrel/process';
+import type { ExecuteResult } from '@orkestrel/process';
+import type { ExecuteSyncOptions } from '@orkestrel/process';
+import type { ProcessCommand } from '@orkestrel/process';
+import type { ProcessEventMap } from '@orkestrel/process';
+import type { ProcessExit } from '@orkestrel/process';
+import type { ProcessInterface } from '@orkestrel/process';
+import type { ProcessManagerEventMap } from '@orkestrel/process';
+import type { ProcessManagerInterface } from '@orkestrel/process';
+import type { ProcessManagerOptions } from '@orkestrel/process';
+import type { ProcessOptions } from '@orkestrel/process';
+import type { Readable } from 'node:stream';
+import type { SessionEventMap } from '@orkestrel/process';
+import type { SessionInterface } from '@orkestrel/process';
+import type { SessionOptions } from '@orkestrel/process';
+import type { SpawnInput } from '@orkestrel/process';
 
 /**
  * Builds the executable candidates an explicit platform would search.
@@ -151,26 +144,37 @@ export declare function buildSpawn(command: ProcessCommand, options?: Executable
 export declare function captureChunk(chunk: unknown, room: number): Buffer_2 | undefined;
 
 /**
- * Creates one supervised child process.
+ * Creates one supervised child process and returns it as a {@link ProcessInterface}, so a caller
+ * holds the published contract rather than the `Process` class.
  *
  * @param options - Command, workspace, termination, evidence, stdin, and observation settings
  * @returns The launched {@link ProcessInterface}
  *
- * @example
+ * @example Supervise a child and read its lines
  * ```ts
  * import { createProcess } from '@orkestrel/process/server'
  *
  * const child = createProcess({
- * 	command: { file: 'node', arguments: ['--version'] },
+ * 	command: { file: 'node', arguments: ['-e', 'console.log("ready"); console.log("done")'] },
  * 	workspace: process.cwd(),
- * 	grace: 5000,
+ * 	grace: 5_000, // POSIX only: the window between SIGTERM and SIGKILL
  * })
+ *
+ * const lines: string[] = []
+ * for await (const line of child.lines) lines.push(line)
+ * lines // ['ready', 'done']
+ *
+ * const exit = await child.exit
+ * exit.code // 0
+ * await child.destroy()
  * ```
  */
 export declare function createProcess(options: ProcessOptions): ProcessInterface;
 
 /**
- * Creates one keyed registry of supervised child processes.
+ * Creates one empty keyed registry of supervised child processes and returns it as a
+ * {@link ProcessManagerInterface}, so a caller holds the published contract rather than the
+ * `ProcessManager` class.
  *
  * @param options - Initial fleet-level observation hooks and listener-error handling
  * @returns The {@link ProcessManagerInterface} registry
@@ -185,7 +189,8 @@ export declare function createProcess(options: ProcessOptions): ProcessInterface
 export declare function createProcessManager(options?: ProcessManagerOptions): ProcessManagerInterface;
 
 /**
- * Creates one raw byte session over a supervised child process.
+ * Creates one raw byte session over a supervised child process and returns it as a
+ * {@link SessionInterface}, so a caller holds the published contract rather than the `Session` class.
  *
  * @param options - Command, workspace, termination, evidence, stdin, and observation settings
  * @returns The launched {@link SessionInterface}
@@ -416,7 +421,8 @@ export declare function mergeEnvironment(isolated: boolean, base?: Readonly<Reco
 export declare function mergePlatformEnvironment(platform: NodeJS.Platform, parent: Readonly<Record<string, string | undefined>>, isolated: boolean, base?: Readonly<Record<string, string | undefined>>, override?: Readonly<Record<string, string | undefined>>): NodeJS.ProcessEnv;
 
 /**
- * Supervises one child while keeping every observation channel aligned at termination.
+ * Supervises one child, frames its standard output into lines under a bounded backlog, and keeps
+ * every observation channel aligned at termination.
  *
  * @remarks
  * The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
@@ -446,7 +452,7 @@ export declare function mergePlatformEnvironment(platform: NodeJS.Platform, pare
  * await child.destroy()
  * ```
  */
-export declare class Process implements ProcessInterface_2 {
+export declare class Process implements ProcessInterface {
     #private;
     /**
      * Spawns one child process and begins stream capture.
@@ -454,7 +460,7 @@ export declare class Process implements ProcessInterface_2 {
      * @param options - Command, workspace, termination, capture, stdin, and observation settings
      * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
      */
-    constructor(options: ProcessOptions_2);
+    constructor(options: ProcessOptions);
     /** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
     get pid(): number | undefined;
     /** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
@@ -474,7 +480,7 @@ export declare class Process implements ProcessInterface_2 {
     /** Reports whether termination began, including after the terminal moment. */
     get stopping(): boolean;
     /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
-    get exit(): Promise<ProcessExit_2>;
+    get exit(): Promise<ProcessExit>;
     /**
      * Writes one line to the open standard-input channel.
      *
@@ -587,7 +593,8 @@ export declare interface ProcessChildInterface {
 }
 
 /**
- * Represents a keyed registry of live supervised child processes.
+ * Launches supervised children under caller-chosen ids, evicts each one as it settles, and destroys
+ * every live child on teardown.
  *
  * @remarks
  * A child launched under an id joins the registry and emits `launch`; when it settles it removes
@@ -615,14 +622,14 @@ export declare interface ProcessChildInterface {
  * await manager.destroy()
  * ```
  */
-export declare class ProcessManager implements ProcessManagerInterface_2 {
+export declare class ProcessManager implements ProcessManagerInterface {
     #private;
     /**
      * Constructs a process registry.
      *
      * @param options - Initial fleet-level observation hooks and listener-error handling
      */
-    constructor(options?: ProcessManagerOptions_2);
+    constructor(options?: ProcessManagerOptions);
     /** Holds the typed fleet-level observation surface. */
     get emitter(): EmitterInterface<ProcessManagerEventMap>;
     /** Counts the live children. */
@@ -633,13 +640,13 @@ export declare class ProcessManager implements ProcessManagerInterface_2 {
      * @param id - The registry key
      * @returns The child, or `undefined`
      */
-    process(id: string): ProcessInterface_2 | undefined;
+    process(id: string): ProcessInterface | undefined;
     /**
      * Returns a snapshot of every live child.
      *
      * @returns The live children in launch order
      */
-    processes(): readonly ProcessInterface_2[];
+    processes(): readonly ProcessInterface[];
     /**
      * Spawns and registers one child under `id`.
      *
@@ -657,7 +664,7 @@ export declare class ProcessManager implements ProcessManagerInterface_2 {
      * @returns The launched child
      * @throws A {@link ProcessError} coded `duplicate` when `id` is already live, `protocol` when the registry is being destroyed, or `invalid` when an option or command string is malformed
      */
-    launch(id: string, options: ProcessOptions_2): ProcessInterface_2;
+    launch(id: string, options: ProcessOptions): ProcessInterface;
     /**
      * Terminates the named children and awaits their exit.
      *
@@ -745,7 +752,8 @@ export declare function readPlatformVariable(environment: Readonly<Record<string
 export declare function readVariable(environment: Readonly<Record<string, string | undefined>>, name: string): string | undefined;
 
 /**
- * Resolves a command file to the executable path the host would launch.
+ * Resolves a command file to the executable path the host would launch, or to `undefined` on a POSIX
+ * host, which performs its own lookup.
  *
  * @param file - The command executable name or path
  * @param options - The directory searched first and the child's effective environment
@@ -789,7 +797,7 @@ export declare function resolveExecutable(file: string, options?: ExecutableOpti
  * })
  * ```
  */
-export declare class Session implements SessionInterface_2 {
+export declare class Session implements SessionInterface {
     #private;
     /**
      * Spawns one child process and begins byte capture.
@@ -797,7 +805,7 @@ export declare class Session implements SessionInterface_2 {
      * @param options - Command, workspace, termination, evidence, stdin, and observation settings
      * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
      */
-    constructor(options: SessionOptions_2);
+    constructor(options: SessionOptions);
     /** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
     get pid(): number | undefined;
     /** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
@@ -815,7 +823,7 @@ export declare class Session implements SessionInterface_2 {
     /** Settles at the child's own ending, awaited without the terminal moment's drain window. */
     get ending(): Promise<void>;
     /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
-    get exit(): Promise<ProcessExit_2>;
+    get exit(): Promise<ProcessExit>;
     /**
      * Writes raw bytes to the open standard-input channel.
      *
@@ -972,7 +980,7 @@ export declare class Supervisor {
      * @param face - The composing face's callbacks for each lifecycle moment
      * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
      */
-    constructor(options: ProcessOptions_2, face: SupervisorFace);
+    constructor(options: ProcessOptions, face: SupervisorFace);
     /** Holds the child's standard-output stream, for the composing face to attach its own consumer to. */
     get stdout(): Readable;
     /** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
@@ -997,7 +1005,7 @@ export declare class Supervisor {
      */
     get ending(): Promise<void>;
     /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
-    get exit(): Promise<ProcessExit_2>;
+    get exit(): Promise<ProcessExit>;
     /**
      * Writes raw bytes to the open standard-input channel.
      *

package/dist/src/server/index.d.ts

@@ -1,31 +1,24 @@
 import { Buffer as Buffer_2 } from 'node:buffer';
-import { DetachOptions } from '@orkestrel/process';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { ExecutableOptions } from '@orkestrel/process';
-import { ExecuteInput } from '@orkestrel/process';
-import { ExecuteOptions } from '@orkestrel/process';
-import { ExecuteResult } from '@orkestrel/process';
-import { ExecuteSyncOptions } from '@orkestrel/process';
-import { ProcessCommand } from '@orkestrel/process';
-import { ProcessEventMap } from '@orkestrel/process';
-import { ProcessExit } from '@orkestrel/process';
-import { ProcessExit as ProcessExit_2 } from '@orkestrel/process';
-import { ProcessInterface } from '@orkestrel/process';
-import { ProcessInterface as ProcessInterface_2 } from '@orkestrel/process';
-import { ProcessManagerEventMap } from '@orkestrel/process';
-import { ProcessManagerInterface } from '@orkestrel/process';
-import { ProcessManagerInterface as ProcessManagerInterface_2 } from '@orkestrel/process';
-import { ProcessManagerOptions } from '@orkestrel/process';
-import { ProcessManagerOptions as ProcessManagerOptions_2 } from '@orkestrel/process';
-import { ProcessOptions } from '@orkestrel/process';
-import { ProcessOptions as ProcessOptions_2 } from '@orkestrel/process';
-import { Readable } from 'node:stream';
-import { SessionEventMap } from '@orkestrel/process';
-import { SessionInterface } from '@orkestrel/process';
-import { SessionInterface as SessionInterface_2 } from '@orkestrel/process';
-import { SessionOptions } from '@orkestrel/process';
-import { SessionOptions as SessionOptions_2 } from '@orkestrel/process';
-import { SpawnInput } from '@orkestrel/process';
+import type { DetachOptions } from '@orkestrel/process';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { ExecutableOptions } from '@orkestrel/process';
+import type { ExecuteInput } from '@orkestrel/process';
+import type { ExecuteOptions } from '@orkestrel/process';
+import type { ExecuteResult } from '@orkestrel/process';
+import type { ExecuteSyncOptions } from '@orkestrel/process';
+import type { ProcessCommand } from '@orkestrel/process';
+import type { ProcessEventMap } from '@orkestrel/process';
+import type { ProcessExit } from '@orkestrel/process';
+import type { ProcessInterface } from '@orkestrel/process';
+import type { ProcessManagerEventMap } from '@orkestrel/process';
+import type { ProcessManagerInterface } from '@orkestrel/process';
+import type { ProcessManagerOptions } from '@orkestrel/process';
+import type { ProcessOptions } from '@orkestrel/process';
+import type { Readable } from 'node:stream';
+import type { SessionEventMap } from '@orkestrel/process';
+import type { SessionInterface } from '@orkestrel/process';
+import type { SessionOptions } from '@orkestrel/process';
+import type { SpawnInput } from '@orkestrel/process';
 
 /**
  * Builds the executable candidates an explicit platform would search.
@@ -151,26 +144,37 @@ export declare function buildSpawn(command: ProcessCommand, options?: Executable
 export declare function captureChunk(chunk: unknown, room: number): Buffer_2 | undefined;
 
 /**
- * Creates one supervised child process.
+ * Creates one supervised child process and returns it as a {@link ProcessInterface}, so a caller
+ * holds the published contract rather than the `Process` class.
  *
  * @param options - Command, workspace, termination, evidence, stdin, and observation settings
  * @returns The launched {@link ProcessInterface}
  *
- * @example
+ * @example Supervise a child and read its lines
  * ```ts
  * import { createProcess } from '@orkestrel/process/server'
  *
  * const child = createProcess({
- * 	command: { file: 'node', arguments: ['--version'] },
+ * 	command: { file: 'node', arguments: ['-e', 'console.log("ready"); console.log("done")'] },
  * 	workspace: process.cwd(),
- * 	grace: 5000,
+ * 	grace: 5_000, // POSIX only: the window between SIGTERM and SIGKILL
  * })
+ *
+ * const lines: string[] = []
+ * for await (const line of child.lines) lines.push(line)
+ * lines // ['ready', 'done']
+ *
+ * const exit = await child.exit
+ * exit.code // 0
+ * await child.destroy()
  * ```
  */
 export declare function createProcess(options: ProcessOptions): ProcessInterface;
 
 /**
- * Creates one keyed registry of supervised child processes.
+ * Creates one empty keyed registry of supervised child processes and returns it as a
+ * {@link ProcessManagerInterface}, so a caller holds the published contract rather than the
+ * `ProcessManager` class.
  *
  * @param options - Initial fleet-level observation hooks and listener-error handling
  * @returns The {@link ProcessManagerInterface} registry
@@ -185,7 +189,8 @@ export declare function createProcess(options: ProcessOptions): ProcessInterface
 export declare function createProcessManager(options?: ProcessManagerOptions): ProcessManagerInterface;
 
 /**
- * Creates one raw byte session over a supervised child process.
+ * Creates one raw byte session over a supervised child process and returns it as a
+ * {@link SessionInterface}, so a caller holds the published contract rather than the `Session` class.
  *
  * @param options - Command, workspace, termination, evidence, stdin, and observation settings
  * @returns The launched {@link SessionInterface}
@@ -416,7 +421,8 @@ export declare function mergeEnvironment(isolated: boolean, base?: Readonly<Reco
 export declare function mergePlatformEnvironment(platform: NodeJS.Platform, parent: Readonly<Record<string, string | undefined>>, isolated: boolean, base?: Readonly<Record<string, string | undefined>>, override?: Readonly<Record<string, string | undefined>>): NodeJS.ProcessEnv;
 
 /**
- * Supervises one child while keeping every observation channel aligned at termination.
+ * Supervises one child, frames its standard output into lines under a bounded backlog, and keeps
+ * every observation channel aligned at termination.
  *
  * @remarks
  * The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
@@ -446,7 +452,7 @@ export declare function mergePlatformEnvironment(platform: NodeJS.Platform, pare
  * await child.destroy()
  * ```
  */
-export declare class Process implements ProcessInterface_2 {
+export declare class Process implements ProcessInterface {
     #private;
     /**
      * Spawns one child process and begins stream capture.
@@ -454,7 +460,7 @@ export declare class Process implements ProcessInterface_2 {
      * @param options - Command, workspace, termination, capture, stdin, and observation settings
      * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
      */
-    constructor(options: ProcessOptions_2);
+    constructor(options: ProcessOptions);
     /** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
     get pid(): number | undefined;
     /** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
@@ -474,7 +480,7 @@ export declare class Process implements ProcessInterface_2 {
     /** Reports whether termination began, including after the terminal moment. */
     get stopping(): boolean;
     /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
-    get exit(): Promise<ProcessExit_2>;
+    get exit(): Promise<ProcessExit>;
     /**
      * Writes one line to the open standard-input channel.
      *
@@ -587,7 +593,8 @@ export declare interface ProcessChildInterface {
 }
 
 /**
- * Represents a keyed registry of live supervised child processes.
+ * Launches supervised children under caller-chosen ids, evicts each one as it settles, and destroys
+ * every live child on teardown.
  *
  * @remarks
  * A child launched under an id joins the registry and emits `launch`; when it settles it removes
@@ -615,14 +622,14 @@ export declare interface ProcessChildInterface {
  * await manager.destroy()
  * ```
  */
-export declare class ProcessManager implements ProcessManagerInterface_2 {
+export declare class ProcessManager implements ProcessManagerInterface {
     #private;
     /**
      * Constructs a process registry.
      *
      * @param options - Initial fleet-level observation hooks and listener-error handling
      */
-    constructor(options?: ProcessManagerOptions_2);
+    constructor(options?: ProcessManagerOptions);
     /** Holds the typed fleet-level observation surface. */
     get emitter(): EmitterInterface<ProcessManagerEventMap>;
     /** Counts the live children. */
@@ -633,13 +640,13 @@ export declare class ProcessManager implements ProcessManagerInterface_2 {
      * @param id - The registry key
      * @returns The child, or `undefined`
      */
-    process(id: string): ProcessInterface_2 | undefined;
+    process(id: string): ProcessInterface | undefined;
     /**
      * Returns a snapshot of every live child.
      *
      * @returns The live children in launch order
      */
-    processes(): readonly ProcessInterface_2[];
+    processes(): readonly ProcessInterface[];
     /**
      * Spawns and registers one child under `id`.
      *
@@ -657,7 +664,7 @@ export declare class ProcessManager implements ProcessManagerInterface_2 {
      * @returns The launched child
      * @throws A {@link ProcessError} coded `duplicate` when `id` is already live, `protocol` when the registry is being destroyed, or `invalid` when an option or command string is malformed
      */
-    launch(id: string, options: ProcessOptions_2): ProcessInterface_2;
+    launch(id: string, options: ProcessOptions): ProcessInterface;
     /**
      * Terminates the named children and awaits their exit.
      *
@@ -745,7 +752,8 @@ export declare function readPlatformVariable(environment: Readonly<Record<string
 export declare function readVariable(environment: Readonly<Record<string, string | undefined>>, name: string): string | undefined;
 
 /**
- * Resolves a command file to the executable path the host would launch.
+ * Resolves a command file to the executable path the host would launch, or to `undefined` on a POSIX
+ * host, which performs its own lookup.
  *
  * @param file - The command executable name or path
  * @param options - The directory searched first and the child's effective environment
@@ -789,7 +797,7 @@ export declare function resolveExecutable(file: string, options?: ExecutableOpti
  * })
  * ```
  */
-export declare class Session implements SessionInterface_2 {
+export declare class Session implements SessionInterface {
     #private;
     /**
      * Spawns one child process and begins byte capture.
@@ -797,7 +805,7 @@ export declare class Session implements SessionInterface_2 {
      * @param options - Command, workspace, termination, evidence, stdin, and observation settings
      * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
      */
-    constructor(options: SessionOptions_2);
+    constructor(options: SessionOptions);
     /** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
     get pid(): number | undefined;
     /** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
@@ -815,7 +823,7 @@ export declare class Session implements SessionInterface_2 {
     /** Settles at the child's own ending, awaited without the terminal moment's drain window. */
     get ending(): Promise<void>;
     /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
-    get exit(): Promise<ProcessExit_2>;
+    get exit(): Promise<ProcessExit>;
     /**
      * Writes raw bytes to the open standard-input channel.
      *
@@ -972,7 +980,7 @@ export declare class Supervisor {
      * @param face - The composing face's callbacks for each lifecycle moment
      * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
      */
-    constructor(options: ProcessOptions_2, face: SupervisorFace);
+    constructor(options: ProcessOptions, face: SupervisorFace);
     /** Holds the child's standard-output stream, for the composing face to attach its own consumer to. */
     get stdout(): Readable;
     /** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
@@ -997,7 +1005,7 @@ export declare class Supervisor {
      */
     get ending(): Promise<void>;
     /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
-    get exit(): Promise<ProcessExit_2>;
+    get exit(): Promise<ProcessExit>;
     /**
      * Writes raw bytes to the open standard-input channel.
      *

package/dist/src/server/index.js

@@ -306,7 +306,8 @@ function buildExecutableCandidates(file, workspace, environment, platform) {
 	return Object.freeze(targets);
 }
 /**
-* Resolves a command file to the executable path the host would launch.
+* Resolves a command file to the executable path the host would launch, or to `undefined` on a POSIX
+* host, which performs its own lookup.
 *
 * @param file - The command executable name or path
 * @param options - The directory searched first and the child's effective environment
@@ -1445,7 +1446,8 @@ var Supervisor = class {
 //#endregion
 //#region src/server/processes/Process.ts
 /**
-* Supervises one child while keeping every observation channel aligned at termination.
+* Supervises one child, frames its standard output into lines under a bounded backlog, and keeps
+* every observation channel aligned at termination.
 *
 * @remarks
 * The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
@@ -1734,7 +1736,8 @@ var Process = class {
 //#endregion
 //#region src/server/processes/ProcessManager.ts
 /**
-* Represents a keyed registry of live supervised child processes.
+* Launches supervised children under caller-chosen ids, evicts each one as it settles, and destroys
+* every live child on teardown.
 *
 * @remarks
 * A child launched under an id joins the registry and emits `launch`; when it settles it removes
@@ -2080,27 +2083,37 @@ var Session = class {
 //#endregion
 //#region src/server/factories.ts
 /**
-* Creates one supervised child process.
+* Creates one supervised child process and returns it as a {@link ProcessInterface}, so a caller
+* holds the published contract rather than the `Process` class.
 *
 * @param options - Command, workspace, termination, evidence, stdin, and observation settings
 * @returns The launched {@link ProcessInterface}
 *
-* @example
+* @example Supervise a child and read its lines
 * ```ts
 * import { createProcess } from '@orkestrel/process/server'
 *
 * const child = createProcess({
-* 	command: { file: 'node', arguments: ['--version'] },
+* 	command: { file: 'node', arguments: ['-e', 'console.log("ready"); console.log("done")'] },
 * 	workspace: process.cwd(),
-* 	grace: 5000,
+* 	grace: 5_000, // POSIX only: the window between SIGTERM and SIGKILL
 * })
+*
+* const lines: string[] = []
+* for await (const line of child.lines) lines.push(line)
+* lines // ['ready', 'done']
+*
+* const exit = await child.exit
+* exit.code // 0
+* await child.destroy()
 * ```
 */
 function createProcess(options) {
 	return new Process(options);
 }
 /**
-* Creates one raw byte session over a supervised child process.
+* Creates one raw byte session over a supervised child process and returns it as a
+* {@link SessionInterface}, so a caller holds the published contract rather than the `Session` class.
 *
 * @param options - Command, workspace, termination, evidence, stdin, and observation settings
 * @returns The launched {@link SessionInterface}
@@ -2120,7 +2133,9 @@ function createSession(options) {
 	return new Session(options);
 }
 /**
-* Creates one keyed registry of supervised child processes.
+* Creates one empty keyed registry of supervised child processes and returns it as a
+* {@link ProcessManagerInterface}, so a caller holds the published contract rather than the
+* `ProcessManager` class.
 *
 * @param options - Initial fleet-level observation hooks and listener-error handling
 * @returns The {@link ProcessManagerInterface} registry