@orkestrel/process 0.0.9 → 0.0.10

package/dist/src/core/index.js

@@ -1,11 +1,11 @@
 import { holds, isError } from "@orkestrel/contract";
 //#region src/core/constants.ts
-/** The default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
+/** Names the default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
 var PROCESS_GRACE = 5e3;
-/** The window in milliseconds a termination waits for the child's native exit after the final kill. */
+/** Names the window in milliseconds a termination waits for the child's native exit after the final kill. */
 var PROCESS_CONFIRMATION = 5e3;
 /**
-* The default window in milliseconds the package waits for the child's read ends to close after
+* Names the default window in milliseconds the package waits for the child's read ends to close after
 * the child's native exit or after a termination this package initiated, before cutting them off.
 *
 * @remarks
@@ -20,17 +20,17 @@ var PROCESS_CONFIRMATION = 5e3;
 * finite close measured, and it keeps an unreachable descendant from stretching a shutdown.
 */
 var PROCESS_DRAIN = 1e3;
-/** The default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
+/** Names the default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
 var PROCESS_EVIDENCE = 2048;
-/** The default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */
+/** Names the default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */
 var PROCESS_BACKLOG = 10485760;
-/** The default maximum captured bytes for a one-shot run's stdout and stderr, each. */
+/** Names the default maximum captured bytes for a one-shot run's stdout and stderr, each. */
 var PROCESS_OUTPUT = 10485760;
-/** The largest timer delay in milliseconds the host schedules without truncating it to one. */
+/** Names the largest timer delay in milliseconds the host schedules without truncating it to one. */
 var PROCESS_TIMER = 2147483647;
-/** The executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */
+/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */
 var PROCESS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
-/** The machine-readable failure categories a {@link ProcessError} carries, in declaration order. */
+/** Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order. */
 var PROCESS_ERROR_CODES = Object.freeze([
 	"spawn",
 	"timeout",
@@ -41,15 +41,26 @@ var PROCESS_ERROR_CODES = Object.freeze([
 ]);
 //#endregion
 //#region src/core/errors.ts
-/** A child-process failure with a stable machine-readable category. */
+/**
+* Represents a child-process failure with a stable machine-readable category.
+*
+* @example
+* ```ts
+* const error = new ProcessError('git status refused', {
+* 	code: 'invalid',
+* 	context: { command: 'git status' },
+* })
+* error.code // 'invalid'
+* ```
+*/
 var ProcessError = class extends Error {
 	name = "ProcessError";
 	code;
 	context;
-	/** The buffered run outcome, present when a one-shot run produced the failure. */
+	/** Carries the buffered run outcome, present when a one-shot run produced the failure. */
 	result;
 	/**
-	* Create a process error.
+	* Creates a process error.
 	*
 	* @param message - Human-readable failure description
 	* @param options - Machine-readable category, optional context, optional cause, and optional run result
@@ -74,7 +85,7 @@ var ProcessError = class extends Error {
 * plain or property-only lookalike.
 *
 * @param value - The value to inspect
-* @returns True only for a `ProcessError` instance; false otherwise
+* @returns True if the value is a `ProcessError` instance; false otherwise
 *
 * @example
 * ```ts

package/dist/src/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/constants.ts","../../../src/core/errors.ts"],"sourcesContent":["/** The default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */\nexport const PROCESS_GRACE = 5_000\n\n/** The window in milliseconds a termination waits for the child's native exit after the final kill. */\nexport const PROCESS_CONFIRMATION = 5_000\n\n/**\n * The default window in milliseconds the package waits for the child's read ends to close after\n * the child's native exit or after a termination this package initiated, before cutting them off.\n *\n * @remarks\n * Measured on Windows 11 with Node v24.18.1 on 2026-08-21, spawning the `tests/src/server/fixtures`\n * child modes as real children and timing the host `close` event against the host `exit` event.\n * Every ordinary run closed within 0.02ms of the native exit, whether the child ended itself or a\n * kill ended it, and a `taskkill /F /T` that reaped a descendant while the root was still alive\n * closed within 0.01ms. The only finite late close came from a descendant that outlived its root and\n * then ended on its own, at 127.44ms to 193.41ms — that lag is the descendant's own remaining life\n * rather than a flush cost. A descendant that never ends never closes, so the distribution has no\n * finite tail to cover and this value bounds it instead: 1000ms is over five times the slowest\n * finite close measured, and it keeps an unreachable descendant from stretching a shutdown.\n */\nexport const PROCESS_DRAIN = 1_000\n\n/** The default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */\nexport const PROCESS_EVIDENCE = 2_048\n\n/** The default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */\nexport const PROCESS_BACKLOG = 10_485_760\n\n/** The default maximum captured bytes for a one-shot run's stdout and stderr, each. */\nexport const PROCESS_OUTPUT = 10_485_760\n\n/** The largest timer delay in milliseconds the host schedules without truncating it to one. */\nexport const PROCESS_TIMER = 2_147_483_647\n\n/** The executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */\nexport const PROCESS_PATHEXT = '.COM;.EXE;.BAT;.CMD'\n\n/** The machine-readable failure categories a {@link ProcessError} carries, in declaration order. */\nexport const PROCESS_ERROR_CODES = Object.freeze([\n\t'spawn',\n\t'timeout',\n\t'input',\n\t'duplicate',\n\t'protocol',\n\t'invalid',\n] as const)\n","import type {\n\tProcessErrorCode,\n\tProcessErrorContext,\n\tProcessErrorOptions,\n\tExecuteResult,\n} from './types.js'\nimport { holds, isError } from '@orkestrel/contract'\nimport { PROCESS_ERROR_CODES } from './constants.js'\n\n/** A child-process failure with a stable machine-readable category. */\nexport class ProcessError extends Error {\n\toverride readonly name = 'ProcessError'\n\treadonly code: ProcessErrorCode\n\treadonly context?: ProcessErrorContext\n\t/** The buffered run outcome, present when a one-shot run produced the failure. */\n\treadonly result?: ExecuteResult\n\n\t/**\n\t * Create a process error.\n\t *\n\t * @param message - Human-readable failure description\n\t * @param options - Machine-readable category, optional context, optional cause, and optional run result\n\t */\n\tconstructor(message: string, options: ProcessErrorOptions) {\n\t\tconst cause = options.cause\n\t\tsuper(message, cause === undefined ? undefined : { cause })\n\t\tObject.defineProperty(this, Symbol.for('@orkestrel/process.error'), { value: true })\n\t\tthis.code = options.code\n\t\tif (options.context !== undefined) this.context = options.context\n\t\tif (options.result !== undefined) this.result = options.result\n\t}\n}\n\n/**\n * Checks whether an unknown value is a {@link ProcessError}.\n *\n * @remarks\n * Recognition combines a global own-property brand with the native `Error` base, the subclass\n * prototype, the fixed name, and a code {@link PROCESS_ERROR_CODES} declares. The brand is\n * recognized across duplicate installations and ESM/CommonJS module copies at 0.0.4 or later. A copy\n * earlier than 0.0.4 stamps no brand, so an error it throws stays outside the type, and so does a\n * plain or property-only lookalike.\n *\n * @param value - The value to inspect\n * @returns True only for a `ProcessError` instance; false otherwise\n *\n * @example\n * ```ts\n * isProcessError(new ProcessError('spawn failed', { code: 'spawn' })) // true\n * isProcessError(new Error('spawn failed')) // false\n * ```\n */\nexport function isProcessError(value: unknown): value is ProcessError {\n\tif (!isError(value)) return false\n\treturn holds(() => {\n\t\tif (Object.getPrototypeOf(value) === Error.prototype) return false\n\t\tif (value.name !== 'ProcessError' || !('code' in value)) return false\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(\n\t\t\tvalue,\n\t\t\tSymbol.for('@orkestrel/process.error'),\n\t\t)\n\t\tif (descriptor?.value !== true) return false\n\t\tconst code: unknown = value.code\n\t\treturn PROCESS_ERROR_CODES.some((declared) => declared === code)\n\t})\n}\n\n/**\n * Creates the failure raised when a manager launch reuses a live id.\n *\n * @param id - The id already occupied by a live child\n * @returns A typed duplicate-id failure\n */\nexport function createDuplicateError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' is already live`, {\n\t\tcode: 'duplicate',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the failure raised when a launch is attempted on a registry that is being destroyed.\n *\n * @param id - The id the refused launch asked for\n * @returns A typed protocol failure\n */\nexport function createProtocolError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' cannot launch: the registry is destroyed`, {\n\t\tcode: 'protocol',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the failure raised when a public input is refused before anything is spawned.\n *\n * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`\n * @param value - The rejected value, carried as `context.value`\n * @returns A typed validation failure\n *\n * @example\n * ```ts\n * createInvalidError(\"option 'grace'\", -1).code // 'invalid'\n * ```\n */\nexport function createInvalidError(subject: string, value: unknown): ProcessError {\n\treturn new ProcessError(`Invalid ${subject}`, { code: 'invalid', context: { value } })\n}\n\n/**\n * Creates the failure raised when a run does not complete successfully and rejection is requested.\n *\n * @remarks\n * The category is `timeout` only when the run's own timeout elapsed; every other failure,\n * including an abort and an output overflow, is a `spawn` failure carrying its\n * {@link ExecuteResult}.\n *\n * @param result - The buffered run outcome that failed\n * @param cause - The underlying host fault, when one ended the run\n * @returns A typed run failure carrying its {@link ExecuteResult}\n */\nexport function createExecuteError(result: ExecuteResult, cause?: unknown): ProcessError {\n\tlet reason = `exited with code ${String(result.code)}`\n\tif (result.signal !== null) reason = `was killed by ${result.signal}`\n\tif (result.truncated) reason = 'exceeded its output limit'\n\tif (result.aborted) reason = 'was aborted'\n\tif (result.expired) reason = 'timed out'\n\treturn new ProcessError(`Command '${result.command}' ${reason}`, {\n\t\tcode: result.expired ? 'timeout' : 'spawn',\n\t\tcontext: { command: result.command, code: result.code, signal: result.signal },\n\t\t...(cause === undefined ? {} : { cause }),\n\t\tresult,\n\t})\n}\n"],"mappings":";;;AACA,IAAa,gBAAgB;;AAG7B,IAAa,uBAAuB;;;;;;;;;;;;;;;;AAiBpC,IAAa,gBAAgB;;AAG7B,IAAa,mBAAmB;;AAGhC,IAAa,kBAAkB;;AAG/B,IAAa,iBAAiB;;AAG9B,IAAa,gBAAgB;;AAG7B,IAAa,kBAAkB;;AAG/B,IAAa,sBAAsB,OAAO,OAAO;CAChD;CACA;CACA;CACA;CACA;CACA;AACD,CAAU;;;;ACpCV,IAAa,eAAb,cAAkC,MAAM;CACvC,OAAyB;CACzB;CACA;;CAEA;;;;;;;CAQA,YAAY,SAAiB,SAA8B;EAC1D,MAAM,QAAQ,QAAQ;EACtB,MAAM,SAAS,UAAU,KAAA,IAAY,KAAA,IAAY,EAAE,MAAM,CAAC;EAC1D,OAAO,eAAe,MAAM,OAAO,IAAI,0BAA0B,GAAG,EAAE,OAAO,KAAK,CAAC;EACnF,KAAK,OAAO,QAAQ;EACpB,IAAI,QAAQ,YAAY,KAAA,GAAW,KAAK,UAAU,QAAQ;EAC1D,IAAI,QAAQ,WAAW,KAAA,GAAW,KAAK,SAAS,QAAQ;CACzD;AACD;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,eAAe,OAAuC;CACrE,IAAI,CAAC,QAAQ,KAAK,GAAG,OAAO;CAC5B,OAAO,YAAY;EAClB,IAAI,OAAO,eAAe,KAAK,MAAM,MAAM,WAAW,OAAO;EAC7D,IAAI,MAAM,SAAS,kBAAkB,EAAE,UAAU,QAAQ,OAAO;EAKhE,IAJmB,OAAO,yBACzB,OACA,OAAO,IAAI,0BAA0B,CAElC,CAAA,EAAY,UAAU,MAAM,OAAO;EACvC,MAAM,OAAgB,MAAM;EAC5B,OAAO,oBAAoB,MAAM,aAAa,aAAa,IAAI;CAChE,CAAC;AACF;;;;;;;AAQA,SAAgB,qBAAqB,IAA0B;CAC9D,OAAO,IAAI,aAAa,YAAY,GAAG,oBAAoB;EAC1D,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;AAQA,SAAgB,oBAAoB,IAA0B;CAC7D,OAAO,IAAI,aAAa,YAAY,GAAG,6CAA6C;EACnF,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,SAAiB,OAA8B;CACjF,OAAO,IAAI,aAAa,WAAW,WAAW;EAAE,MAAM;EAAW,SAAS,EAAE,MAAM;CAAE,CAAC;AACtF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,QAAuB,OAA+B;CACxF,IAAI,SAAS,oBAAoB,OAAO,OAAO,IAAI;CACnD,IAAI,OAAO,WAAW,MAAM,SAAS,iBAAiB,OAAO;CAC7D,IAAI,OAAO,WAAW,SAAS;CAC/B,IAAI,OAAO,SAAS,SAAS;CAC7B,IAAI,OAAO,SAAS,SAAS;CAC7B,OAAO,IAAI,aAAa,YAAY,OAAO,QAAQ,IAAI,UAAU;EAChE,MAAM,OAAO,UAAU,YAAY;EACnC,SAAS;GAAE,SAAS,OAAO;GAAS,MAAM,OAAO;GAAM,QAAQ,OAAO;EAAO;EAC7E,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;EACvC;CACD,CAAC;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/constants.ts","../../../src/core/errors.ts"],"sourcesContent":["/** Names the default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */\nexport const PROCESS_GRACE = 5_000\n\n/** Names the window in milliseconds a termination waits for the child's native exit after the final kill. */\nexport const PROCESS_CONFIRMATION = 5_000\n\n/**\n * Names the default window in milliseconds the package waits for the child's read ends to close after\n * the child's native exit or after a termination this package initiated, before cutting them off.\n *\n * @remarks\n * Measured on Windows 11 with Node v24.18.1 on 2026-08-21, spawning the `tests/src/server/fixtures`\n * child modes as real children and timing the host `close` event against the host `exit` event.\n * Every ordinary run closed within 0.02ms of the native exit, whether the child ended itself or a\n * kill ended it, and a `taskkill /F /T` that reaped a descendant while the root was still alive\n * closed within 0.01ms. The only finite late close came from a descendant that outlived its root and\n * then ended on its own, at 127.44ms to 193.41ms — that lag is the descendant's own remaining life\n * rather than a flush cost. A descendant that never ends never closes, so the distribution has no\n * finite tail to cover and this value bounds it instead: 1000ms is over five times the slowest\n * finite close measured, and it keeps an unreachable descendant from stretching a shutdown.\n */\nexport const PROCESS_DRAIN = 1_000\n\n/** Names the default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */\nexport const PROCESS_EVIDENCE = 2_048\n\n/** Names the default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */\nexport const PROCESS_BACKLOG = 10_485_760\n\n/** Names the default maximum captured bytes for a one-shot run's stdout and stderr, each. */\nexport const PROCESS_OUTPUT = 10_485_760\n\n/** Names the largest timer delay in milliseconds the host schedules without truncating it to one. */\nexport const PROCESS_TIMER = 2_147_483_647\n\n/** Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */\nexport const PROCESS_PATHEXT = '.COM;.EXE;.BAT;.CMD'\n\n/** Lists the machine-readable failure categories a {@link ProcessError} carries, in declaration order. */\nexport const PROCESS_ERROR_CODES = Object.freeze([\n\t'spawn',\n\t'timeout',\n\t'input',\n\t'duplicate',\n\t'protocol',\n\t'invalid',\n] as const)\n","import type {\n\tProcessErrorCode,\n\tProcessErrorContext,\n\tProcessErrorOptions,\n\tExecuteResult,\n} from './types.js'\nimport { holds, isError } from '@orkestrel/contract'\nimport { PROCESS_ERROR_CODES } from './constants.js'\n\n/**\n * Represents a child-process failure with a stable machine-readable category.\n *\n * @example\n * ```ts\n * const error = new ProcessError('git status refused', {\n * \tcode: 'invalid',\n * \tcontext: { command: 'git status' },\n * })\n * error.code // 'invalid'\n * ```\n */\nexport class ProcessError extends Error {\n\toverride readonly name = 'ProcessError'\n\treadonly code: ProcessErrorCode\n\treadonly context?: ProcessErrorContext\n\t/** Carries the buffered run outcome, present when a one-shot run produced the failure. */\n\treadonly result?: ExecuteResult\n\n\t/**\n\t * Creates a process error.\n\t *\n\t * @param message - Human-readable failure description\n\t * @param options - Machine-readable category, optional context, optional cause, and optional run result\n\t */\n\tconstructor(message: string, options: ProcessErrorOptions) {\n\t\tconst cause = options.cause\n\t\tsuper(message, cause === undefined ? undefined : { cause })\n\t\tObject.defineProperty(this, Symbol.for('@orkestrel/process.error'), { value: true })\n\t\tthis.code = options.code\n\t\tif (options.context !== undefined) this.context = options.context\n\t\tif (options.result !== undefined) this.result = options.result\n\t}\n}\n\n/**\n * Checks whether an unknown value is a {@link ProcessError}.\n *\n * @remarks\n * Recognition combines a global own-property brand with the native `Error` base, the subclass\n * prototype, the fixed name, and a code {@link PROCESS_ERROR_CODES} declares. The brand is\n * recognized across duplicate installations and ESM/CommonJS module copies at 0.0.4 or later. A copy\n * earlier than 0.0.4 stamps no brand, so an error it throws stays outside the type, and so does a\n * plain or property-only lookalike.\n *\n * @param value - The value to inspect\n * @returns True if the value is a `ProcessError` instance; false otherwise\n *\n * @example\n * ```ts\n * isProcessError(new ProcessError('spawn failed', { code: 'spawn' })) // true\n * isProcessError(new Error('spawn failed')) // false\n * ```\n */\nexport function isProcessError(value: unknown): value is ProcessError {\n\tif (!isError(value)) return false\n\treturn holds(() => {\n\t\tif (Object.getPrototypeOf(value) === Error.prototype) return false\n\t\tif (value.name !== 'ProcessError' || !('code' in value)) return false\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(\n\t\t\tvalue,\n\t\t\tSymbol.for('@orkestrel/process.error'),\n\t\t)\n\t\tif (descriptor?.value !== true) return false\n\t\tconst code: unknown = value.code\n\t\treturn PROCESS_ERROR_CODES.some((declared) => declared === code)\n\t})\n}\n\n/**\n * Creates the failure raised when a manager launch reuses a live id.\n *\n * @param id - The id already occupied by a live child\n * @returns A typed duplicate-id failure\n */\nexport function createDuplicateError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' is already live`, {\n\t\tcode: 'duplicate',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the failure raised when a launch is attempted on a registry that is being destroyed.\n *\n * @param id - The id the refused launch asked for\n * @returns A typed protocol failure\n */\nexport function createProtocolError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' cannot launch: the registry is destroyed`, {\n\t\tcode: 'protocol',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the failure raised when a public input is refused before anything is spawned.\n *\n * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`\n * @param value - The rejected value, carried as `context.value`\n * @returns A typed validation failure\n *\n * @example\n * ```ts\n * createInvalidError(\"option 'grace'\", -1).code // 'invalid'\n * ```\n */\nexport function createInvalidError(subject: string, value: unknown): ProcessError {\n\treturn new ProcessError(`Invalid ${subject}`, { code: 'invalid', context: { value } })\n}\n\n/**\n * Creates the failure raised when a run does not complete successfully and rejection is requested.\n *\n * @remarks\n * The category is `timeout` only when the run's own timeout elapsed; every other failure,\n * including an abort and an output overflow, is a `spawn` failure carrying its\n * {@link ExecuteResult}.\n *\n * @param result - The buffered run outcome that failed\n * @param cause - The underlying host fault, when one ended the run\n * @returns A typed run failure carrying its {@link ExecuteResult}\n */\nexport function createExecuteError(result: ExecuteResult, cause?: unknown): ProcessError {\n\tlet reason = `exited with code ${String(result.code)}`\n\tif (result.signal !== null) reason = `was killed by ${result.signal}`\n\tif (result.truncated) reason = 'exceeded its output limit'\n\tif (result.aborted) reason = 'was aborted'\n\tif (result.expired) reason = 'timed out'\n\treturn new ProcessError(`Command '${result.command}' ${reason}`, {\n\t\tcode: result.expired ? 'timeout' : 'spawn',\n\t\tcontext: { command: result.command, code: result.code, signal: result.signal },\n\t\t...(cause === undefined ? {} : { cause }),\n\t\tresult,\n\t})\n}\n"],"mappings":";;;AACA,IAAa,gBAAgB;;AAG7B,IAAa,uBAAuB;;;;;;;;;;;;;;;;AAiBpC,IAAa,gBAAgB;;AAG7B,IAAa,mBAAmB;;AAGhC,IAAa,kBAAkB;;AAG/B,IAAa,iBAAiB;;AAG9B,IAAa,gBAAgB;;AAG7B,IAAa,kBAAkB;;AAG/B,IAAa,sBAAsB,OAAO,OAAO;CAChD;CACA;CACA;CACA;CACA;CACA;AACD,CAAU;;;;;;;;;;;;;;;ACzBV,IAAa,eAAb,cAAkC,MAAM;CACvC,OAAyB;CACzB;CACA;;CAEA;;;;;;;CAQA,YAAY,SAAiB,SAA8B;EAC1D,MAAM,QAAQ,QAAQ;EACtB,MAAM,SAAS,UAAU,KAAA,IAAY,KAAA,IAAY,EAAE,MAAM,CAAC;EAC1D,OAAO,eAAe,MAAM,OAAO,IAAI,0BAA0B,GAAG,EAAE,OAAO,KAAK,CAAC;EACnF,KAAK,OAAO,QAAQ;EACpB,IAAI,QAAQ,YAAY,KAAA,GAAW,KAAK,UAAU,QAAQ;EAC1D,IAAI,QAAQ,WAAW,KAAA,GAAW,KAAK,SAAS,QAAQ;CACzD;AACD;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,eAAe,OAAuC;CACrE,IAAI,CAAC,QAAQ,KAAK,GAAG,OAAO;CAC5B,OAAO,YAAY;EAClB,IAAI,OAAO,eAAe,KAAK,MAAM,MAAM,WAAW,OAAO;EAC7D,IAAI,MAAM,SAAS,kBAAkB,EAAE,UAAU,QAAQ,OAAO;EAKhE,IAJmB,OAAO,yBACzB,OACA,OAAO,IAAI,0BAA0B,CAElC,CAAA,EAAY,UAAU,MAAM,OAAO;EACvC,MAAM,OAAgB,MAAM;EAC5B,OAAO,oBAAoB,MAAM,aAAa,aAAa,IAAI;CAChE,CAAC;AACF;;;;;;;AAQA,SAAgB,qBAAqB,IAA0B;CAC9D,OAAO,IAAI,aAAa,YAAY,GAAG,oBAAoB;EAC1D,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;AAQA,SAAgB,oBAAoB,IAA0B;CAC7D,OAAO,IAAI,aAAa,YAAY,GAAG,6CAA6C;EACnF,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,SAAiB,OAA8B;CACjF,OAAO,IAAI,aAAa,WAAW,WAAW;EAAE,MAAM;EAAW,SAAS,EAAE,MAAM;CAAE,CAAC;AACtF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,QAAuB,OAA+B;CACxF,IAAI,SAAS,oBAAoB,OAAO,OAAO,IAAI;CACnD,IAAI,OAAO,WAAW,MAAM,SAAS,iBAAiB,OAAO;CAC7D,IAAI,OAAO,WAAW,SAAS;CAC/B,IAAI,OAAO,SAAS,SAAS;CAC7B,IAAI,OAAO,SAAS,SAAS;CAC7B,OAAO,IAAI,aAAa,YAAY,OAAO,QAAQ,IAAI,UAAU;EAChE,MAAM,OAAO,UAAU,YAAY;EACnC,SAAS;GAAE,SAAS,OAAO;GAAS,MAAM,OAAO;GAAM,QAAQ,OAAO;EAAO;EAC7E,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;EACvC;CACD,CAAC;AACF"}

package/dist/src/server/index.cjs

@@ -9,6 +9,42 @@ let _src_core = require("../core/index.cjs");
 let node_readline = require("node:readline");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 let node_string_decoder = require("node:string_decoder");
+//#region src/server/cloners.ts
+/**
+* Takes one owned frozen snapshot of a caller's command.
+*
+* @remarks
+* Every public entry point snapshots before it validates, so the object validated is the object
+* spawned. Each property is read exactly once, because reading one runs the caller's own getter: a
+* command whose `file` changes between reads would otherwise validate one executable and spawn
+* another. The argument vector and the environment record are copied and frozen, so a caller
+* mutating either after the call cannot reach the spawn. An absent optional stays absent rather than
+* becoming an explicit `undefined`.
+*
+* @param command - The caller's command, whose properties may be getters
+* @returns A frozen command carrying the values read at this instant
+*
+* @example
+* ```ts
+* snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
+* ```
+*/
+function snapshotCommand(command) {
+	const file = command.file;
+	const argumentsList = Object.freeze([...command.arguments]);
+	const sourceEnvironment = command.environment;
+	const environment = sourceEnvironment === void 0 ? void 0 : Object.freeze({ ...sourceEnvironment });
+	const input = command.input;
+	const isolated = command.isolated;
+	return Object.freeze({
+		file,
+		arguments: argumentsList,
+		...environment === void 0 ? {} : { environment },
+		...input === void 0 ? {} : { input },
+		...isolated === void 0 ? {} : { isolated }
+	});
+}
+//#endregion
 //#region src/server/helpers.ts
 /**
 * Trims a buffer to at most `limit` trailing bytes without splitting a UTF-8 sequence.
@@ -107,40 +143,6 @@ function captureChunk(chunk, room) {
 	return node_buffer.Buffer.from(chunk.subarray(0, room));
 }
 /**
-* Takes one owned frozen snapshot of a caller's command.
-*
-* @remarks
-* Every public entry point snapshots before it validates, so the object validated is the object
-* spawned. Each property is read exactly once, because reading one runs the caller's own getter: a
-* command whose `file` changes between reads would otherwise validate one executable and spawn
-* another. The argument vector and the environment record are copied and frozen, so a caller
-* mutating either after the call cannot reach the spawn. An absent optional stays absent rather than
-* becoming an explicit `undefined`.
-*
-* @param command - The caller's command, whose properties may be getters
-* @returns A frozen command carrying the values read at this instant
-*
-* @example
-* ```ts
-* snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
-* ```
-*/
-function snapshotCommand(command) {
-	const file = command.file;
-	const argumentsList = Object.freeze([...command.arguments]);
-	const sourceEnvironment = command.environment;
-	const environment = sourceEnvironment === void 0 ? void 0 : Object.freeze({ ...sourceEnvironment });
-	const input = command.input;
-	const isolated = command.isolated;
-	return Object.freeze({
-		file,
-		arguments: argumentsList,
-		...environment === void 0 ? {} : { environment },
-		...input === void 0 ? {} : { input },
-		...isolated === void 0 ? {} : { isolated }
-	});
-}
-/**
 * Renders one command into its diagnostic command line.
 *
 * @param command - The executable and its argument vector
@@ -257,7 +259,7 @@ function mergeEnvironment(isolated, base, override) {
 * command. An unreadable or malformed path reports `false` rather than throwing.
 *
 * @param target - The absolute or relative path to inspect
-* @returns True when the path resolves to a regular file; false otherwise
+* @returns True if the path resolves to a regular file; false otherwise
 *
 * @example
 * ```ts
@@ -530,7 +532,7 @@ function validateWorkspace(workspace) {
 * initiated against a pid the host may have reused.
 *
 * @param child - The child boundary
-* @returns True when the process has exited; false while it is live
+* @returns True if the process has exited; false otherwise
 *
 * @example
 * ```ts
@@ -586,7 +588,7 @@ function killProcess(child, signal) {
 *
 * @param pid - The root process id of the tree to end
 * @param timeout - The milliseconds the utility is given before it is killed
-* @returns True when the utility reported success; false when it failed, was unavailable, or was cut off
+* @returns True if the utility reported success; false otherwise (it failed, was unavailable, or was cut off)
 *
 * @example
 * ```ts
@@ -637,7 +639,7 @@ function waitForExit(child, timeout) {
 *
 * @param child - The child boundary
 * @param timeout - The milliseconds to wait before giving up
-* @returns True when the host close arrived inside the deadline; false otherwise
+* @returns True if the host close arrived inside the deadline; false otherwise
 *
 * @example
 * ```ts
@@ -672,7 +674,7 @@ function waitForClose(child, timeout) {
 * @param child - The child boundary
 * @param grace - The cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL`
 * @param confirm - The milliseconds the native exit is awaited after the final kill
-* @returns True when the native exit was observed; false when `confirm` elapsed without it
+* @returns True if the native exit was observed; false otherwise (`confirm` elapsed without it)
 *
 * @example
 * ```ts
@@ -1030,7 +1032,7 @@ function detach(command, options) {
 	child.unref();
 }
 //#endregion
-//#region src/server/Supervisor.ts
+//#region src/server/processes/Supervisor.ts
 /**
 * Supervises one child process and reports each lifecycle moment to the face composing it.
 *
@@ -1059,6 +1061,25 @@ function detach(command, options) {
 * termination completes. `relieve` is optional because a face that never pauses the child's output
 * holds no backpressure to release, and a face with nothing to do there would otherwise declare an
 * empty method to say so.
+*
+* @example
+* ```ts
+* import { Supervisor } from '@orkestrel/process/server'
+*
+* const engine = new Supervisor(
+* 	{ command: { file: 'node', arguments: ['--version'] }, workspace: process.cwd() },
+* 	{
+* 		chunk: () => undefined,
+* 		fault: () => undefined,
+* 		close: () => undefined,
+* 		terminal: () => undefined,
+* 		teardown: () => undefined,
+* 	},
+* )
+* const exit = await engine.exit
+* exit.code // 0
+* await engine.destroy()
+* ```
 */
 var Supervisor = class {
 	#chunk;
@@ -1088,7 +1109,7 @@ var Supervisor = class {
 	#termination;
 	#destruction;
 	/**
-	* Spawn one child process and begin standard-error capture.
+	* Spawns one child process and begins standard-error capture.
 	*
 	* @remarks
 	* The face's callbacks are captured before anything is read or spawned, so the first moment the
@@ -1165,36 +1186,36 @@ var Supervisor = class {
 			if (signal.aborted) this.stop();
 		}
 	}
-	/** The child's standard-output stream, for the composing face to attach its own consumer to. */
+	/** Holds the child's standard-output stream, for the composing face to attach its own consumer to. */
 	get stdout() {
 		return this.#child.stdout;
 	}
-	/** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+	/** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
 	get pid() {
 		return this.#child.pid;
 	}
-	/** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+	/** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
 	get code() {
 		return this.#child.exitCode;
 	}
-	/** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+	/** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
 	get signal() {
 		return this.#child.signalCode;
 	}
-	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+	/** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
 	get evidence() {
 		return this.#tail.toString("utf8");
 	}
-	/** True after the terminal moment arrived and `exit` settled. */
+	/** Reports whether the terminal moment arrived and `exit` settled. */
 	get settled() {
 		return this.#settled;
 	}
-	/** True after termination began, including after the terminal moment. */
+	/** Reports whether termination began, including after the terminal moment. */
 	get stopping() {
 		return this.#stopping;
 	}
 	/**
-	* The child's own ending, awaited without the terminal moment's drain window.
+	* Settles at the child's own ending, awaited without the terminal moment's drain window.
 	*
 	* @remarks
 	* Never rejects, and resolves no value: `code` and `signal` carry the terminal facts as soon as
@@ -1204,7 +1225,7 @@ var Supervisor = class {
 	get ending() {
 		return this.#ending.promise;
 	}
-	/** The terminal child state, observed once after stream close or the drain cutoff. */
+	/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
 		return this.#exit.promise;
 	}
@@ -1221,7 +1242,30 @@ var Supervisor = class {
 	* discard.
 	*
 	* @param bytes - The payload to write, already framed by the caller
-	* @returns True when the host accepted the bytes without reporting a fault; false when the channel was closed, destroyed, ended, failed, or remained unconfirmed through `delivery`
+	* @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
+	*
+	* @example
+	* ```ts
+	* import { Supervisor } from '@orkestrel/process/server'
+	*
+	* const engine = new Supervisor(
+	* 	{
+	* 		command: { file: 'node', arguments: ['-e', 'process.stdin.pipe(process.stdout)'] },
+	* 		workspace: process.cwd(),
+	* 		writable: true,
+	* 	},
+	* 	{
+	* 		chunk: () => undefined,
+	* 		fault: () => undefined,
+	* 		close: () => undefined,
+	* 		terminal: () => undefined,
+	* 		teardown: () => undefined,
+	* 	},
+	* )
+	* const accepted = await engine.deliver(new TextEncoder().encode('ping\n'))
+	* accepted // true
+	* await engine.destroy()
+	* ```
 	*/
 	deliver(bytes) {
 		const stdin = this.#child.stdin;
@@ -1272,7 +1316,7 @@ var Supervisor = class {
 	* and settles `exit` when they remain open. A cutoff reached before the native exit reports the
 	* `code` and `signal` the host had recorded by then, which is `null` for a child still running.
 	*
-	* @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
+	* @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
 	*/
 	stop() {
 		if (this.#termination !== void 0) return this.#termination;
@@ -1400,7 +1444,7 @@ var Supervisor = class {
 	}
 };
 //#endregion
-//#region src/server/Process.ts
+//#region src/server/processes/Process.ts
 /**
 * Supervises one child while keeping every observation channel aligned at termination.
 *
@@ -1447,7 +1491,7 @@ var Process = class {
 	#truncated = false;
 	#ended = false;
 	/**
-	* Spawn one child process and begin stream capture.
+	* Spawns one child process and begins stream capture.
 	*
 	* @param options - Command, workspace, termination, capture, stdin, and observation settings
 	* @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
@@ -1502,48 +1546,48 @@ var Process = class {
 		this.#reader.on("line", this.#push.bind(this));
 		this.#reader.once("close", this.#finish.bind(this));
 	}
-	/** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+	/** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
 	get pid() {
 		return this.#engine.pid;
 	}
-	/** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+	/** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
 	get code() {
 		return this.#engine.code;
 	}
-	/** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+	/** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
 	get signal() {
 		return this.#engine.signal;
 	}
-	/** The typed lifecycle observation surface. */
+	/** Holds the typed lifecycle observation surface. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
+	/** Yields the captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
 	get lines() {
 		return this.#lines;
 	}
-	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+	/** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
 	get evidence() {
 		return this.#engine.evidence;
 	}
-	/** True when the `lines` stream omitted output after a retention bound was reached. */
+	/** Reports whether the `lines` stream omitted output after a retention bound was reached. */
 	get truncated() {
 		return this.#truncated;
 	}
-	/** True after the terminal moment arrived and `exit` settled. */
+	/** Reports whether the terminal moment arrived and `exit` settled. */
 	get settled() {
 		return this.#engine.settled;
 	}
-	/** True after termination began, including after the terminal moment. */
+	/** Reports whether termination began, including after the terminal moment. */
 	get stopping() {
 		return this.#engine.stopping;
 	}
-	/** The terminal child state, observed once after stream close or the drain cutoff. */
+	/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
 		return this.#engine.exit;
 	}
 	/**
-	* Write one line to the open standard-input channel.
+	* Writes one line to the open standard-input channel.
 	*
 	* @remarks
 	* Never rejects. `true` means the host accepted the bytes without reporting a fault; it does not
@@ -1557,7 +1601,7 @@ var Process = class {
 	* for bytes the package is about to discard.
 	*
 	* @param text - The line text without its trailing newline
-	* @returns True when the host accepted the bytes without reporting a fault; false when the channel was closed, destroyed, ended, failed, or remained unconfirmed through `delivery`
+	* @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
 	*/
 	send(text) {
 		return this.#engine.deliver(node_buffer.Buffer.from(`${text}\n`, "utf8"));
@@ -1571,7 +1615,7 @@ var Process = class {
 	* and settles `exit` when they remain open. A cutoff reached before the native exit reports the
 	* `code` and `signal` the host had recorded by then, which is `null` for a child still running.
 	*
-	* @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
+	* @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
 	*/
 	stop() {
 		return this.#engine.stop();
@@ -1689,9 +1733,9 @@ var Process = class {
 	}
 };
 //#endregion
-//#region src/server/ProcessManager.ts
+//#region src/server/processes/ProcessManager.ts
 /**
-* A keyed registry of live supervised child processes.
+* Represents a keyed registry of live supervised child processes.
 *
 * @remarks
 * A child launched under an id joins the registry and emits `launch`; when it settles it removes
@@ -1727,7 +1771,7 @@ var ProcessManager = class {
 	#destroying = false;
 	#ending;
 	/**
-	* Construct a process registry.
+	* Constructs a process registry.
 	*
 	* @param options - Initial fleet-level observation hooks and listener-error handling
 	*/
@@ -1739,16 +1783,16 @@ var ProcessManager = class {
 			...error === void 0 ? {} : { error }
 		});
 	}
-	/** The typed fleet-level observation surface. */
+	/** Holds the typed fleet-level observation surface. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The number of live children. */
+	/** Counts the live children. */
 	get count() {
 		return this.#children.size;
 	}
 	/**
-	* The live child under `id`, or `undefined` when none is.
+	* Returns the live child under `id`, or `undefined` when none is.
 	*
 	* @param id - The registry key
 	* @returns The child, or `undefined`
@@ -1757,7 +1801,7 @@ var ProcessManager = class {
 		return this.#children.get(id);
 	}
 	/**
-	* A snapshot of every live child.
+	* Returns a snapshot of every live child.
 	*
 	* @returns The live children in launch order
 	*/
@@ -1765,7 +1809,7 @@ var ProcessManager = class {
 		return [...this.#children.values()];
 	}
 	/**
-	* Spawn and register one child under `id`.
+	* Spawns and registers one child under `id`.
 	*
 	* @remarks
 	* {@link Process} reads every option before it spawns, so a caller's own option getter runs while
@@ -1803,7 +1847,7 @@ var ProcessManager = class {
 		return this.#stopMany(target);
 	}
 	/**
-	* Stop every child, then destroy the registry emitter last.
+	* Stops every child, then destroys the registry emitter last.
 	*
 	* @remarks
 	* Always resolves, and refuses a later `launch` with a {@link createProtocolError}. Each child is
@@ -1856,7 +1900,7 @@ var ProcessManager = class {
 	}
 };
 //#endregion
-//#region src/server/Session.ts
+//#region src/server/processes/Session.ts
 /**
 * Supervises one child and publishes its standard output as raw bytes.
 *
@@ -1893,7 +1937,7 @@ var Session = class {
 	#engine;
 	#output;
 	/**
-	* Spawn one child process and begin byte capture.
+	* Spawns one child process and begins byte capture.
 	*
 	* @param options - Command, workspace, termination, evidence, stdin, and observation settings
 	* @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
@@ -1931,39 +1975,39 @@ var Session = class {
 		});
 		this.#engine.stdout.on("data", this.#output);
 	}
-	/** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+	/** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
 	get pid() {
 		return this.#engine.pid;
 	}
-	/** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+	/** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
 	get code() {
 		return this.#engine.code;
 	}
-	/** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+	/** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
 	get signal() {
 		return this.#engine.signal;
 	}
-	/** The typed lifecycle observation surface. */
+	/** Holds the typed lifecycle observation surface. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+	/** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
 	get evidence() {
 		return this.#engine.evidence;
 	}
-	/** True after the terminal moment arrived and `exit` settled. */
+	/** Reports whether the terminal moment arrived and `exit` settled. */
 	get settled() {
 		return this.#engine.settled;
 	}
-	/** True after termination began, including after the terminal moment. `end` never turns it true. */
+	/** Reports whether termination began, including after the terminal moment. `end` never turns it true. */
 	get stopping() {
 		return this.#engine.stopping;
 	}
-	/** The child's own ending, awaited without the terminal moment's drain window. */
+	/** Settles at the child's own ending, awaited without the terminal moment's drain window. */
 	get ending() {
 		return this.#engine.ending;
 	}
-	/** The terminal child state, observed once after stream close or the drain cutoff. */
+	/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
 		return this.#engine.exit;
 	}
@@ -1977,7 +2021,7 @@ var Session = class {
 	* returned promise settles.
 	*
 	* @param bytes - The payload to write, already framed by the caller
-	* @returns True when the host accepted the bytes without reporting a fault; false when the channel was closed, destroyed, ended, failed, or remained unconfirmed through `delivery`
+	* @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
 	*/
 	write(bytes) {
 		return this.#engine.deliver(bytes);
@@ -2001,7 +2045,7 @@ var Session = class {
 	* @remarks
 	* Never rejects, and every call shares one termination bounded by `grace` and `drain`.
 	*
-	* @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
+	* @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
 	*/
 	stop() {
 		return this.#engine.stop();
@@ -2096,6 +2140,7 @@ function createProcessManager(options) {
 exports.Process = Process;
 exports.ProcessManager = ProcessManager;
 exports.Session = Session;
+exports.Supervisor = Supervisor;
 exports.buildExecutableCandidates = buildExecutableCandidates;
 exports.buildExecuteResult = buildExecuteResult;
 exports.buildPlatformSpawn = buildPlatformSpawn;