@orkestrel/process 0.0.4 → 0.0.6

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

@@ -139,13 +139,15 @@ export declare interface ExecuteOptions {
  * The settled outcome of a one-shot run: the buffered output and the terminal state.
  *
  * @remarks
- * `failed` is `true` when the child exited non-zero, was killed by a signal, expired, was aborted, or
- * failed to spawn. `expired` and `aborted` name the ways the run ended the child rather than the
- * child ending itself, and only the earliest observed is recorded. `truncated` is independent of
- * both: it reports that a captured stream omitted output because it exceeded `limit`, which fails a
- * synchronous run and does not fail an asynchronous one. `ProcessInterface` carries the same name for
- * the same fact against a supervised child's retention bounds. A spawn fault reports the host's negative errno for `execute`. A spawn fault reports
- * `null` for `executeSync`.
+ * `failed` is `true` when the run timed out, was aborted, ended on a host fault, was ended by a
+ * signal, or exited with a code other than `0`. `expired` and `aborted` name the ways the run ended
+ * the child rather than the child ending itself, and only the earliest observed is recorded.
+ * `truncated` reports that a captured stream omitted output because it exceeded `limit`, which
+ * fails a synchronous run and does not fail an asynchronous one. `ProcessInterface` carries the
+ * same name for the same fact against a supervised child's retention bounds. For a `strict: false`
+ * caller, `failed: true` with `expired`, `aborted`, and `truncated` false, `code: 0`, and
+ * `signal: null` is the residual signature that a host fault ended the run. A spawn fault reports
+ * the host's negative errno for `execute`. A spawn fault reports `null` for `executeSync`.
  */
 export declare interface ExecuteResult {
     /** The command line that was run, for diagnostics. */
@@ -220,8 +222,25 @@ export declare const PROCESS_BACKLOG = 10485760;
 /** The window in milliseconds a termination waits for the child's native exit after the final kill. */
 export declare const PROCESS_CONFIRMATION = 5000;
 
+/**
+ * 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
+ * Measured on Windows 11 with Node v24.18.1 on 2026-08-21, spawning the `tests/src/server/fixtures`
+ * child modes as real children and timing the host `close` event against the host `exit` event.
+ * Every ordinary run closed within 0.02ms of the native exit, whether the child ended itself or a
+ * kill ended it, and a `taskkill /F /T` that reaped a descendant while the root was still alive
+ * closed within 0.01ms. The only finite late close came from a descendant that outlived its root and
+ * then ended on its own, at 127.44ms to 193.41ms — that lag is the descendant's own remaining life
+ * rather than a flush cost. A descendant that never ends never closes, so the distribution has no
+ * finite tail to cover and this value bounds it instead: 1000ms is over five times the slowest
+ * finite close measured, and it keeps an unreachable descendant from stretching a shutdown.
+ */
+export declare const PROCESS_DRAIN = 1000;
+
 /** The machine-readable failure categories a {@link ProcessError} carries, in declaration order. */
-export declare const PROCESS_ERROR_CODES: readonly ["spawn", "timeout", "duplicate", "protocol", "invalid"];
+export declare const PROCESS_ERROR_CODES: readonly ["spawn", "timeout", "input", "duplicate", "protocol", "invalid"];
 
 /** The default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
 export declare const PROCESS_EVIDENCE = 2048;
@@ -330,25 +349,41 @@ export declare interface ProcessErrorOptions {
  *
  * @remarks
  * Declared as a `type` alias so it satisfies the emitter's `EventMap` constraint structurally. The
- * `error` event carries a child fault — a failure to spawn or a process-level error. It is distinct
- * from the `error` handler in {@link ProcessOptions}: a listener throw is isolated by the emitter and
+ * `error` event carries a child fault — a failure to spawn, a process-level error, or a
+ * host-reported standard-input channel fault after the constructor input phase. A fault arising
+ * from the constructor-supplied `input` write or its closing `end` stays quiet because the package
+ * initiated that sequence. A surfaced standard-input fault is wrapped in a
+ * {@link ProcessError} coded `protocol` with the host fault as its cause. The event is distinct from
+ * the `error` handler in {@link ProcessOptions}: a listener throw is isolated by the emitter and
  * routed to that handler, never emitted as this `error` event.
  */
 export declare type ProcessEventMap = {
     /** A decoded standard-error chunk arrived. */
     readonly stderr: readonly [chunk: string];
-    /** The child emitted an error — a spawn fault or process-level failure — carrying its cause. */
+    /** The child or its open standard-input channel reported a fault, carrying the host cause directly or through a `protocol` {@link ProcessError}. */
     readonly error: readonly [error: unknown];
     /** The child settled — its terminal state, delivered once. */
     readonly exit: readonly [exit: ProcessExit];
 };
 
-/** The observed terminal state of a child process: its exit code, or the signal that ended it. */
+/**
+ * The observed terminal state of a child process: its exit code or the signal that ended it, and
+ * how its observation ended.
+ *
+ * @remarks
+ * This value exists only at the terminal moment, so every field on it is already final and no
+ * consumer can read one too early. `drained` reports whether the diagnostics are complete;
+ * {@link ProcessInterface.truncated} reports that the `lines` stream omitted stdout lines. They are
+ * independent facts about different streams, and one child reports both when a retention bound
+ * dropped lines and the drain bound cut stderr off.
+ */
 export declare interface ProcessExit {
     /** The exit code, or `null` when a signal ended the process. A spawn fault reports the host's negative errno for `Process` and `execute`. */
     readonly code: number | null;
     /** The terminating signal name, or `null` when the process exited on its own. */
     readonly signal: string | null;
+    /** True when the terminal moment arrived because the child's streams closed; false when the `drain` bound elapsed first and later diagnostics may have existed. */
+    readonly drained: boolean;
 }
 
 /**
@@ -369,14 +404,22 @@ export declare interface ProcessExit {
  * its own capture `limit`. The typed `emitter` carries the live `stderr` chunks, the child `error` cause, and the
  * terminal `exit`, alongside the `exit` promise. `stop` and `destroy` are idempotent and never reject.
  *
+ * The same terminal moment governs every observation surface. It arrives when the child's streams close,
+ * or when the `drain` bound armed by the native exit or by a termination this package initiated
+ * elapses first, and
+ * {@link ProcessExit.drained} reports which. At that moment `evidence` freezes, `lines` ends, `exit`
+ * settles, and `settled` turns true — together, so a consumer reading `evidence` and a consumer
+ * iterating `lines` never see a different child. `stop`, `destroy`, an abort of the `signal` option,
+ * a natural exit, and a spawn fault all reach it.
+ *
  * The spawn is eager, so `pid` is fixed by the time construction returns; a spawn that produced no
  * child reports `undefined` for that child's whole lifetime. An assigned id survives the exit and
  * reports no liveness on its own, because the host reuses a dead child's id. Derive liveness as
  * `pid !== undefined && code === null && signal === null`, and derive it again before every use of
  * the id. `code` and `signal` mirror the host child's own terminal record, so they carry the native
- * exit as soon as the host has it, while the `exit` promise settles on stdio close — a descendant
- * holding inherited stdio keeps that close pending past the native exit, and a supervisor inside
- * that window reads the terminal state here.
+ * exit as soon as the host has it, while the `exit` promise settles at the terminal moment — a
+ * descendant holding inherited stdio keeps the stream close pending past the native exit, and a
+ * supervisor inside that window reads the terminal state here.
  */
 export declare interface ProcessInterface {
     /** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
@@ -387,29 +430,88 @@ export declare interface ProcessInterface {
     readonly signal: string | null;
     /** The typed lifecycle observation surface. */
     readonly emitter: EmitterInterface<ProcessEventMap>;
-    /** The captured stdout lines, in arrival order, for one consumer, ending when the child's stdout closes. */
+    /**
+     * The captured stdout lines, in arrival order, for one consumer, ending at the terminal moment.
+     *
+     * @remarks
+     * A line feed, a CRLF pair, and a bare carriage return each terminate a line, and a CRLF split
+     * across delivered chunks joins as one break. A child that redraws a progress bar with a carriage
+     * return therefore yields one line per redraw, and consecutive carriage returns yield an empty
+     * line between them. A final line written with no trailing terminator is delivered when stdout
+     * closes.
+     *
+     * The stream ends at the terminal moment rather than throwing there, so teardown is not an error
+     * path: a pending `next()` resolves `done: true` and a `for await` loop exits normally. Lines
+     * already framed and queued are delivered before that end, so a consumer that stops a chatty
+     * child still reads what the child had produced, and only bytes that would have arrived after the
+     * terminal moment are lost — whether that moment came from the read ends closing, from the
+     * `drain` bound after a native exit, or from a requested termination. An unframed trailing partial
+     * written before an undrained cutoff is not promised, because only the stream's own end flushes
+     * one. A read started after the end yields nothing further.
+     */
     readonly lines: AsyncIterable<string>;
-    /** The decoded byte-bounded stderr tail. */
+    /**
+     * The decoded byte-bounded stderr tail.
+     *
+     * @remarks
+     * The live tail before the terminal moment and the frozen value after it, on every path — a
+     * natural exit, `stop`, `destroy`, an abort of the `signal` option, and a spawn fault. Every read
+     * after that moment returns the same string, so a consumer needs no private copy and cannot
+     * observe the tail moving under it. When {@link ProcessExit.drained} is false the frozen value is
+     * the tail as of the cutoff, and later diagnostics may have existed.
+     */
     readonly evidence: string;
     /** True when the `lines` stream omitted output because a retention bound was reached. */
     readonly truncated: boolean;
-    /** The terminal child state, observed once from the close event. */
+    /**
+     * True after the `exit` promise settled.
+     *
+     * @remarks
+     * The terminal moment has arrived: `evidence` is frozen, `lines` has ended, and the
+     * {@link ProcessExit} value exists. Reached on every path, including a spawn that produced no
+     * child.
+     */
+    readonly settled: boolean;
+    /**
+     * True after a termination began.
+     *
+     * @remarks
+     * Monotonic. It turns true when `stop`, `destroy`, or an abort of the `signal` option begins a
+     * termination, and it stays true from then on, including after `settled` turns true. It reports
+     * that a termination was initiated, not that one is in flight, because the initiation is the fact
+     * a consumer acts on: a child that was asked to end is not a child to send new work to. A child
+     * that exited on its own reports `false` here with `settled` true.
+     */
+    readonly stopping: boolean;
+    /**
+     * The terminal child state, delivered once.
+     *
+     * @remarks
+     * Never rejects. It settles at the terminal moment: when the child's streams close, or when the
+     * `drain` bound elapsed first. The native exit arms that bound as well as an initiated
+     * termination, so a child nobody terminates still settles it within `drain` of ending.
+     */
     readonly exit: Promise<ProcessExit>;
     /**
      * Write one line to the open standard-input channel.
      *
      * @remarks
-     * Never rejects. The promise settles when the host reports the line handled, so a line written
-     * to a child that is not reading stays pending until the child drains it or the channel closes.
-     * Every terminal teardown path destroys stdin, so a pending write always settles by teardown. A
-     * caller that needs its own deadline arms a timer and calls `stop`.
+     * Never rejects. `true` means the host accepted the bytes without reporting a fault; it does not
+     * prove that the child read them. An ordinary write settles when the kernel accepts it. Only a
+     * full pipe can hold the write unconfirmed. The `delivery` option can bound that wait, and every
+     * terminal teardown path settles pending writes. On Windows 11 with Node v24.18.1, measured on
+     * 2026-08-21, a child that closes its own file descriptor 0 can leave the parent pipe writable:
+     * the write can settle `true` without a callback error or a stream error while the child remains
+     * alive. After `stop` or `destroy` begins, a later call settles `false`. Version 0.0.4 could settle
+     * that call `true` before teardown destroyed the pipe; returning `false` avoids claiming delivery
+     * for bytes the package is about to discard.
      *
      * @param text - The line text without its trailing newline
-     * @returns True when the line reached the host without error; false when the channel was closed, destroyed, ended, or the write failed
+     * @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`
      */
     send(text: string): Promise<boolean>;
     /**
-     * Terminate the child process tree and await its observed exit.
+     * Terminate the child process tree, await its observed exit, and reach the terminal moment.
      *
      * @remarks
      * Never rejects. On Windows the whole tree is killed immediately through `taskkill`, with a
@@ -417,16 +519,25 @@ export declare interface ProcessInterface {
      * `SIGKILL` after `grace`. No signal is initiated after the child's native exit is observed; the
      * window between initiating a signal and the host delivering it belongs to the operating system.
      *
+     * Observation ends here as well as under `destroy`, bounded by `drain`: `evidence` freezes,
+     * `lines` ends, and `exit` settles. A caller that stops a child and keeps reading it therefore
+     * reaches the end of the stream instead of waiting on a child it already ended, and needs no
+     * second call to release it.
+     *
      * @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
      */
     stop(): Promise<boolean>;
     /**
-     * Stop the child, close its standard-input channel, and destroy the observation emitter.
+     * Stop the child, close its standard-input channel, reach the terminal moment, and destroy the
+     * observation emitter.
      *
      * @remarks
-     * Always resolves, including when termination was never confirmed. Resolving does not imply the
-     * child's stdio has closed: a descendant holding an inherited pipe keeps the close event pending,
-     * so `exit` and `lines` can still be outstanding after this barrier settles.
+     * Always resolves, including when termination was never confirmed. The barrier settles after the
+     * terminal moment, so `evidence` is frozen, `lines` has ended, and `exit` has settled by the time
+     * a caller resumes. The wait for the child's streams is bounded by `drain`, so a descendant
+     * holding an inherited pipe cannot hold this barrier open, and {@link ProcessExit.drained} reports
+     * which way the moment arrived. The emitter is destroyed after the frozen state exists, so a
+     * consumer watching the `stderr` event and a consumer reading `evidence` end on the same bytes.
      *
      * @returns The stable barrier shared by every call
      */
@@ -483,11 +594,11 @@ export declare interface ProcessManagerInterface {
      * @remarks
      * Every option is read before the child is spawned, so a caller's own option getter runs while
      * nothing has started and a throw from one strands no process. A getter that begins `destroy`
-     * without throwing is the one remaining race, and it leaves a bounded residual: the child is
-     * already spawned, so the launch is refused with `protocol` and that child is torn down
-     * asynchronously, bounded by `grace` plus the confirmation window. The `protocol` refusal throws
-     * synchronously before the `destroy` barrier settles. The barrier does not cover that child's
-     * asynchronous teardown.
+     * without throwing is the one remaining race: the child is already spawned, so the launch is
+     * refused with `protocol` and that child is destroyed rather than adopted, its teardown bounded
+     * by `grace` plus the confirmation window. The `protocol` refusal throws synchronously, and the
+     * `destroy` barrier covers that teardown, so the refused child reaches its terminal moment before
+     * the barrier resolves.
      *
      * @param id - The registry key, unique among live children
      * @param options - The child construction options
@@ -546,8 +657,17 @@ export declare interface ProcessManagerOptions {
  *
  * @remarks
  * `grace` is the cooperative window between `SIGTERM` and `SIGKILL` on a POSIX host; Windows has no
- * cooperative phase, so the value is unused there. There is no completion deadline — a caller that
- * wants one arms its own timer and calls `stop`. `backlog` bounds the unconsumed `lines` backlog.
+ * cooperative phase, so the value is unused there. There is no completion deadline for a running
+ * child: nothing here ends a child that is still working, the `exit` promise carries no deadline of
+ * its own, and a caller that wants one arms its own timer and calls `stop`. `drain` does not weaken
+ * that. It bounds a single window — between the child's ending and the release of that child's read
+ * ends — so it cannot end a running child. The child's native exit arms it, and so does the return
+ * of a termination this package initiated through `stop`, `destroy`, or an abort of `signal`; a
+ * termination whose confirmation window elapsed can therefore reach the cutoff while the child still
+ * runs. The bound exists because a descendant holding an inherited pipe defers the host's stream
+ * close for that descendant's whole life, which the package cannot reach and cannot outwait: without
+ * the bound, a child that ended would hand the caller an unbounded wait.
+ * `backlog` bounds the unconsumed `lines` backlog.
  * During termination, retained lines are capped at twice `backlog`; later lines are dropped without
  * pausing stdout, and {@link ProcessInterface.truncated} reports the omission. `on` installs initial
  * {@link ProcessEventMap} listeners and `error` receives isolated listener failures. Every numeric
@@ -565,10 +685,14 @@ export declare interface ProcessOptions {
     readonly workspace: string;
     /** Cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL`. Default: {@link PROCESS_GRACE}. */
     readonly grace?: number;
+    /** Milliseconds the package waits for the child's read ends to close after the native exit or an initiated termination, before cutting them off; `0` cuts them off as soon as the bound is armed. Default: {@link PROCESS_DRAIN}. */
+    readonly drain?: number;
     /** Maximum retained stderr tail in bytes. Default: {@link PROCESS_EVIDENCE}. */
     readonly evidence?: number;
     /** Soft high-water mark in bytes for the unconsumed `lines` backlog; termination retains at most twice this value. Default: {@link PROCESS_BACKLOG}. */
     readonly backlog?: number;
+    /** Milliseconds an unconfirmed {@link ProcessInterface.send} waits before resolving `false`. `0` or omitted disables the bound. */
+    readonly delivery?: number;
     /** If `true`, stdin stays open for {@link ProcessInterface.send}; if `false` or omitted, stdin closes after any initial `input`. */
     readonly writable?: boolean;
     /** Aborting this signal terminates the child through the same bounded `stop`. */

package/dist/src/core/index.js

@@ -4,6 +4,22 @@ import { holds, isError } from "@orkestrel/contract";
 var PROCESS_GRACE = 5e3;
 /** 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
+* the child's native exit or after a termination this package initiated, before cutting them off.
+*
+* @remarks
+* Measured on Windows 11 with Node v24.18.1 on 2026-08-21, spawning the `tests/src/server/fixtures`
+* child modes as real children and timing the host `close` event against the host `exit` event.
+* Every ordinary run closed within 0.02ms of the native exit, whether the child ended itself or a
+* kill ended it, and a `taskkill /F /T` that reaped a descendant while the root was still alive
+* closed within 0.01ms. The only finite late close came from a descendant that outlived its root and
+* then ended on its own, at 127.44ms to 193.41ms — that lag is the descendant's own remaining life
+* rather than a flush cost. A descendant that never ends never closes, so the distribution has no
+* finite tail to cover and this value bounds it instead: 1000ms is over five times the slowest
+* 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}. */
 var PROCESS_EVIDENCE = 2048;
 /** The default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */
@@ -18,6 +34,7 @@ var PROCESS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
 var PROCESS_ERROR_CODES = Object.freeze([
 	"spawn",
 	"timeout",
+	"input",
 	"duplicate",
 	"protocol",
 	"invalid"
@@ -147,6 +164,6 @@ function createExecuteError(result, cause) {
 	});
 }
 //#endregion
-export { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_ERROR_CODES, PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, PROCESS_PATHEXT, PROCESS_TIMER, ProcessError, createDuplicateError, createExecuteError, createInvalidError, createProtocolError, isProcessError };
+export { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_DRAIN, PROCESS_ERROR_CODES, PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, PROCESS_PATHEXT, PROCESS_TIMER, ProcessError, createDuplicateError, createExecuteError, createInvalidError, createProtocolError, isProcessError };
 
 //# sourceMappingURL=index.js.map

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/** 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'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;;AAGpC,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;AACD,CAAU;;;;AClBV,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":["/** 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"}