@orkestrel/process 0.0.3 → 0.0.4

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

@@ -10,6 +10,20 @@ import { EmitterInterface } from '@orkestrel/emitter';
  */
 export declare function createDuplicateError(id: string): ProcessError;
 
+/**
+ * Creates the failure raised when a run does not complete successfully and rejection is requested.
+ *
+ * @remarks
+ * The category is `timeout` only when the run's own timeout elapsed; every other failure,
+ * including an abort and an output overflow, is a `spawn` failure carrying its
+ * {@link ExecuteResult}.
+ *
+ * @param result - The buffered run outcome that failed
+ * @param cause - The underlying host fault, when one ended the run
+ * @returns A typed run failure carrying its {@link ExecuteResult}
+ */
+export declare function createExecuteError(result: ExecuteResult, cause?: unknown): ProcessError;
+
 /**
  * Creates the failure raised when a public input is refused before anything is spawned.
  *
@@ -32,19 +46,6 @@ export declare function createInvalidError(subject: string, value: unknown): Pro
  */
 export declare function createProtocolError(id: string): ProcessError;
 
-/**
- * Creates the failure raised when a run does not complete successfully and rejection is requested.
- *
- * @remarks
- * The category is `timeout` only when the run's own timeout elapsed; every other failure, including
- * an abort and an output overflow, is a `spawn` failure carrying its {@link RunResult}.
- *
- * @param result - The buffered run outcome that failed
- * @param cause - The underlying host fault, when one ended the run
- * @returns A typed run failure carrying its {@link RunResult}
- */
-export declare function createRunError(result: RunResult, cause?: unknown): ProcessError;
-
 /**
  * Options for a detached fire-and-forget spawn.
  *
@@ -71,9 +72,137 @@ export declare interface ExecutableOptions {
     readonly environment?: Readonly<Record<string, string | undefined>>;
 }
 
+/**
+ * The captured bytes and terminal facts one settled {@link ExecuteResult} is built from.
+ *
+ * @remarks
+ * Each byte field is trimmed to `limit` on a code-point boundary when the result is built, so a
+ * caller passes the raw retained head and never a decoded string. `cause` carries the host fault
+ * that ended the run, when one did; its presence alone marks the run failed.
+ */
+export declare interface ExecuteInput {
+    /** The diagnostic command line. */
+    readonly command: string;
+    /** The retained standard-output bytes. */
+    readonly stdout: Uint8Array;
+    /** The retained standard-error bytes. */
+    readonly stderr: Uint8Array;
+    readonly code: number | null;
+    readonly signal: string | null;
+    /** If `true`, the run's own timeout elapsed; if `false`, it did not. */
+    readonly expired: boolean;
+    /** If `true`, the caller's signal aborted the run; if `false`, it did not. */
+    readonly aborted: boolean;
+    /** If `true`, a stream exceeded `limit`; if `false`, neither did. */
+    readonly truncated: boolean;
+    /** The maximum retained bytes for each stream. */
+    readonly limit: number;
+    /** The host fault that ended the run, when one did. */
+    readonly cause?: unknown;
+}
+
+/**
+ * Options for a one-shot run.
+ *
+ * @remarks
+ * A run is a fire-and-collect function, not a lifecycle entity, so it carries no emitter. `strict`
+ * decides how a failure is delivered: by default a non-zero exit rejects with a
+ * {@link ProcessError} carrying the {@link ExecuteResult}; `strict: false` resolves with the result
+ * instead, so the caller inspects `failed`. An invalid option or command rejects before the child is
+ * spawned, with a {@link ProcessError} coded `invalid`. `input` is standard-input payload and carries
+ * no NUL restriction. An unbounded run awaits stdio completion rather than process exit, so give
+ * `timeout` a value wherever a descendant may inherit the child's stdio and hold the pipe open past
+ * the child's own exit. Every option is read once, before the child is spawned, so the value
+ * validated is the value spawned and a caller's own getter runs while nothing has started: a getter
+ * that throws strands no process.
+ */
+export declare interface ExecuteOptions {
+    /** The working directory. Default: the current working directory. */
+    readonly workspace?: string;
+    /** Environment overrides merged over the parent environment; an `undefined` value unsets a key. */
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    /** Standard-input payload written to the child, including any NUL characters. */
+    readonly input?: string;
+    /** Milliseconds before the child is terminated. `0` or omitted disables the timeout. */
+    readonly timeout?: number;
+    /** Cooperative POSIX window between `SIGTERM` and `SIGKILL` when terminating. Default: {@link PROCESS_GRACE}. */
+    readonly grace?: number;
+    /** Aborting this signal terminates the run and reports `aborted`. */
+    readonly signal?: AbortSignal;
+    /** If `false`, resolve with the result on failure instead of rejecting. Default: `true`. */
+    readonly strict?: boolean;
+    /** Maximum captured bytes for stdout and for stderr, each. Default: {@link PROCESS_OUTPUT}. */
+    readonly limit?: number;
+}
+
+/**
+ * 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`.
+ */
+export declare interface ExecuteResult {
+    /** The command line that was run, for diagnostics. */
+    readonly command: string;
+    /** The captured standard output, byte-bounded by `limit`. */
+    readonly stdout: string;
+    /** The captured standard error, byte-bounded by `limit`. */
+    readonly stderr: string;
+    /** The exit code. A spawn fault reports the host's negative errno for `execute` and `null` for `executeSync`. */
+    readonly code: number | null;
+    readonly signal: string | null;
+    /** True if the run did not complete successfully. */
+    readonly failed: boolean;
+    /** True if the run's `timeout` elapsed before completion. */
+    readonly expired: boolean;
+    /** True if the caller's `signal` aborted the run before completion. */
+    readonly aborted: boolean;
+    /** True when either captured stream omitted output because it exceeded `limit`. */
+    readonly truncated: boolean;
+}
+
+/**
+ * Options for a synchronous one-shot run.
+ *
+ * @remarks
+ * The synchronous host offers neither a cooperative termination window nor in-flight cancellation,
+ * so this contract carries no `grace` and no `signal`. A `timeout` ends only the root process and can
+ * leave descendants running; use `execute` or {@link ProcessInterface} when timeout must terminate the
+ * tree. A `timeout` and an output overflow both end the root with `SIGKILL`; an overflow reports
+ * `truncated` and `failed` together, which is where `execute` and `executeSync` genuinely differ.
+ * `input` is standard-input payload and carries no NUL restriction.
+ */
+export declare interface ExecuteSyncOptions {
+    /** The working directory. Default: the current working directory. */
+    readonly workspace?: string;
+    /** Environment overrides merged over the parent environment; an `undefined` value unsets a key. */
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    /** Standard-input payload written to the child, including any NUL characters. */
+    readonly input?: string;
+    /** Milliseconds before the host kills the root process alone. `0` or omitted disables the timeout. */
+    readonly timeout?: number;
+    /** If `false`, return the result on failure instead of throwing. Default: `true`. */
+    readonly strict?: boolean;
+    /** Maximum captured bytes for stdout and for stderr, each. Default: {@link PROCESS_OUTPUT}. */
+    readonly limit?: number;
+}
+
 /**
  * Checks whether an unknown value is a {@link ProcessError}.
  *
+ * @remarks
+ * Recognition combines a global own-property brand with the native `Error` base, the subclass
+ * prototype, the fixed name, and a code {@link PROCESS_ERROR_CODES} declares. The brand is
+ * recognized across duplicate installations and ESM/CommonJS module copies at 0.0.4 or later. A copy
+ * earlier than 0.0.4 stamps no brand, so an error it throws stays outside the type, and so does a
+ * plain or property-only lookalike.
+ *
  * @param value - The value to inspect
  * @returns True only for a `ProcessError` instance; false otherwise
  *
@@ -91,6 +220,9 @@ 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 machine-readable failure categories a {@link ProcessError} carries, in declaration order. */
+export declare const PROCESS_ERROR_CODES: readonly ["spawn", "timeout", "duplicate", "protocol", "invalid"];
+
 /** The default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
 export declare const PROCESS_EVIDENCE = 2048;
 
@@ -110,13 +242,13 @@ export declare const PROCESS_TIMER = 2147483647;
  * The public contracts for `@orkestrel/process`: a typed child-process toolkit.
  *
  * @remarks
- * Three tiers, smallest to largest:
+ * The tiers divide by lifetime:
  *
  * - **{@link ProcessInterface}** — one supervised child with framed stdout lines under a bounded
  *   backlog, a byte-bounded stderr tail, a live stderr event, a writable stdin channel, a typed
  *   lifecycle {@link ProcessEventMap} emitter, and bounded termination. The low-level streaming
  *   primitive.
- * - **{@link RunResult} / run** — a one-shot runner that buffers a child to completion and settles
+ * - **{@link ExecuteResult} / execute** — a one-shot spawn that buffers a child to completion and settles
  *   with its output and exit, the ergonomic layer for fire-and-collect commands.
  * - **{@link ProcessManagerInterface}** — a keyed registry of live {@link ProcessInterface}
  *   children, launched and stopped by id, observed through its own {@link ProcessManagerEventMap}.
@@ -131,16 +263,19 @@ export declare const PROCESS_TIMER = 2147483647;
  * @remarks
  * `environment` merges over the parent process environment unless `isolated` is `true`, and an
  * `undefined` value unsets a key. On Windows the merge is case-insensitive and the last writer
- * wins, matching how the host resolves an environment variable. `input` is written to the child's
- * stdin immediately after spawn. Every string here is spawn-bound: an empty `file`, or a NUL
- * character anywhere, is refused with a {@link ProcessError} coded `invalid`.
+ * wins, matching how the host resolves an environment variable. `input` is standard-input payload
+ * written immediately after spawn, so it carries no NUL restriction. Every spawn-bound string here
+ * is validated: an empty `file`, or a NUL character in `file`, `arguments`, or `environment`, is
+ * refused with a {@link ProcessError} coded `invalid`. On a POSIX host, `isolated: true` leaves no
+ * `PATH`, so pass an absolute `file` or include `PATH` in `environment`. On Windows, libuv injects a
+ * host environment set even when `isolated` is `true`.
  */
 export declare interface ProcessCommand {
     readonly file: string;
     readonly arguments: readonly string[];
     readonly environment?: Readonly<Record<string, string | undefined>>;
     readonly input?: string;
-    /** If `true`, the child environment is `environment` alone; if `false` or omitted, it merges over the parent environment. */
+    /** If `true`, exclude the parent environment; on POSIX this leaves no `PATH`, while Windows libuv still injects a host set. */
     readonly isolated?: boolean;
 }
 
@@ -150,7 +285,7 @@ export declare class ProcessError extends Error {
     readonly code: ProcessErrorCode;
     readonly context?: ProcessErrorContext;
     /** The buffered run outcome, present when a one-shot run produced the failure. */
-    readonly result?: RunResult;
+    readonly result?: ExecuteResult;
     /**
      * Create a process error.
      *
@@ -160,8 +295,8 @@ export declare class ProcessError extends Error {
     constructor(message: string, options: ProcessErrorOptions);
 }
 
-/** The machine-readable {@link ProcessError} categories. */
-export declare type ProcessErrorCode = 'spawn' | 'timeout' | 'duplicate' | 'protocol' | 'invalid';
+/** The machine-readable {@link ProcessError} categories, derived from {@link PROCESS_ERROR_CODES}. */
+export declare type ProcessErrorCode = (typeof PROCESS_ERROR_CODES)[number];
 
 /** Structured context carried by a {@link ProcessError}. */
 export declare interface ProcessErrorContext {
@@ -185,8 +320,8 @@ export declare interface ProcessErrorOptions {
     readonly context?: ProcessErrorContext;
     /** The underlying cause, when one exists. */
     readonly cause?: unknown;
-    /** The buffered run outcome, present when a {@link RunResult} produced the failure. */
-    readonly result?: RunResult;
+    /** The buffered run outcome, present when an {@link ExecuteResult} produced the failure. */
+    readonly result?: ExecuteResult;
 }
 
 /**
@@ -210,7 +345,7 @@ export declare type ProcessEventMap = {
 
 /** The observed terminal state of a child process: its exit code, or the signal that ended it. */
 export declare interface ProcessExit {
-    /** The exit code, or `null` when a signal ended the process. */
+    /** 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;
@@ -221,24 +356,43 @@ export declare interface ProcessExit {
  *
  * @remarks
  * `lines` is pumped as soon as the child writes, and it is a single-consumer stream: each line goes
- * to exactly one waiting iterator, so two iterators split the output between them rather than each
- * receiving all of it. The policy for an unconsumed backlog follows
- * consumer intent. Once an iterator has been requested, stdout pauses at the `backlog` mark and
- * resumes at half of it, so the consumer loses nothing and the child feels real backpressure. While
+ * to exactly one waiting iterator, so concurrent iterators split the output between them rather
+ * than each receiving all of it. The policy for an unconsumed backlog follows consumer intent. After an iterator has been requested, stdout pauses at the `backlog` mark and
+ * resumes at half of it, so the consumer loses nothing before termination and the child feels real
+ * backpressure. Termination never reapplies the pause, so from the moment a stop begins retention is
+ * capped at twice `backlog` and later lines are dropped. While
  * no iterator has ever been requested, stdout keeps draining so `exit` still resolves, and retention
  * stops at the mark: a consumer attaching after that point receives the retained head, a gap, then
  * the live stream. `evidence` is the decoded, byte-bounded stderr tail — the diagnostic to attach to
- * a failed exit. 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.
+ * a failed exit. `truncated` reports that the `lines` stream omitted output, because a retention
+ * bound was reached; the one-shot `ExecuteResult` carries the same name for the same fact against
+ * 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 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.
  */
 export declare interface ProcessInterface {
+    /** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+    readonly pid: number | undefined;
+    /** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. A spawn fault reports the host's negative errno. */
+    readonly code: number | null;
+    /** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+    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. */
     readonly lines: AsyncIterable<string>;
     /** The decoded byte-bounded stderr tail. */
     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. */
     readonly exit: Promise<ProcessExit>;
     /**
@@ -331,8 +485,9 @@ export declare interface ProcessManagerInterface {
      * 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 `destroy` barrier settled
-     * before the refusal, so awaiting it does not cover that teardown.
+     * 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.
      *
      * @param id - The registry key, unique among live children
      * @param options - The child construction options
@@ -393,10 +548,14 @@ export declare interface ProcessManagerOptions {
  * `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.
- * `on` installs initial {@link ProcessEventMap} listeners and `error` receives isolated listener
- * failures. Every numeric option is validated at construction: a timer value outside
+ * 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
+ * option is validated at construction: a timer value outside
  * `[0, PROCESS_TIMER]`, a negative or fractional byte value, or a `backlog` below `1` throws a
- * {@link ProcessError} coded `invalid`.
+ * {@link ProcessError} coded `invalid`. POSIX detachment creates the process group used for tree
+ * termination, so the child survives the supervisor's `SIGKILL` and does not receive the terminal's
+ * `SIGINT`. A consumer must call `stop` or `destroy` during an orderly shutdown.
  */
 export declare interface ProcessOptions {
     readonly on?: EmitterHooks<ProcessEventMap>;
@@ -408,7 +567,7 @@ export declare interface ProcessOptions {
     readonly grace?: 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. Default: {@link PROCESS_BACKLOG}. */
+    /** 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;
     /** If `true`, stdin stays open for {@link ProcessInterface.send}; if `false` or omitted, stdin closes after any initial `input`. */
     readonly writable?: boolean;
@@ -416,119 +575,6 @@ export declare interface ProcessOptions {
     readonly signal?: AbortSignal;
 }
 
-/**
- * The captured bytes and terminal facts one settled {@link RunResult} is built from.
- *
- * @remarks
- * Both byte fields are trimmed to `limit` on a code-point boundary when the result is built, so a
- * caller passes the raw retained head and never a decoded string. `cause` carries the host fault
- * that ended the run, when one did; its presence alone marks the run failed.
- */
-export declare interface RunInput {
-    /** The diagnostic command line. */
-    readonly command: string;
-    /** The retained standard-output bytes. */
-    readonly stdout: Uint8Array;
-    /** The retained standard-error bytes. */
-    readonly stderr: Uint8Array;
-    readonly code: number | null;
-    readonly signal: string | null;
-    /** If `true`, the run's own timeout elapsed; if `false`, it did not. */
-    readonly expired: boolean;
-    /** If `true`, the caller's signal aborted the run; if `false`, it did not. */
-    readonly aborted: boolean;
-    /** If `true`, a stream exceeded `limit`; if `false`, both fit. */
-    readonly truncated: boolean;
-    /** The maximum retained bytes for each stream. */
-    readonly limit: number;
-    /** The host fault that ended the run, when one did. */
-    readonly cause?: unknown;
-}
-
-/**
- * Options for a one-shot run.
- *
- * @remarks
- * A run is a fire-and-collect function, not a lifecycle entity, so it carries no emitter. `strict`
- * decides how a failure is delivered: by default a non-zero exit rejects with a
- * {@link ProcessError} carrying the {@link RunResult}; `strict: false` resolves with the result
- * instead, so the caller inspects `failed`. An invalid option or command rejects before the child is
- * spawned, with a {@link ProcessError} coded `invalid`. An unbounded run awaits stdio completion
- * rather than process exit, so give `timeout` a value wherever a descendant may inherit the child's
- * stdio and hold the pipe open past the child's own exit.
- */
-export declare interface RunOptions {
-    /** The working directory. Default: the current working directory. */
-    readonly workspace?: string;
-    /** Environment overrides merged over the parent environment; an `undefined` value unsets a key. */
-    readonly environment?: Readonly<Record<string, string | undefined>>;
-    /** Standard input written to the child. */
-    readonly input?: string;
-    /** Milliseconds before the child is terminated. `0` or omitted disables the timeout. */
-    readonly timeout?: number;
-    /** Cooperative POSIX window between `SIGTERM` and `SIGKILL` when terminating. Default: {@link PROCESS_GRACE}. */
-    readonly grace?: number;
-    /** Aborting this signal terminates the run and reports `aborted`. */
-    readonly signal?: AbortSignal;
-    /** If `false`, resolve with the result on failure instead of rejecting. Default: `true`. */
-    readonly strict?: boolean;
-    /** Maximum captured bytes for stdout and for stderr, each. Default: {@link PROCESS_OUTPUT}. */
-    readonly limit?: number;
-}
-
-/**
- * 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` are the two ways the run ended the child rather than the
- * child ending itself, and only the first of them observed is recorded. `truncated` is independent of
- * both: it reports that a stream exceeded `limit`, which fails a synchronous run and does not fail an
- * asynchronous one.
- */
-export declare interface RunResult {
-    /** The command line that was run, for diagnostics. */
-    readonly command: string;
-    /** The captured standard output, byte-bounded by `limit`. */
-    readonly stdout: string;
-    /** The captured standard error, byte-bounded by `limit`. */
-    readonly stderr: string;
-    readonly code: number | null;
-    readonly signal: string | null;
-    /** True if the run did not complete successfully. */
-    readonly failed: boolean;
-    /** True if the run's `timeout` elapsed before completion. */
-    readonly expired: boolean;
-    /** True if the caller's `signal` aborted the run before completion. */
-    readonly aborted: boolean;
-    /** True if either stream exceeded `limit`, so the captured text is the retained head. */
-    readonly truncated: boolean;
-}
-
-/**
- * Options for a synchronous one-shot run.
- *
- * @remarks
- * The synchronous host offers neither a cooperative termination window nor in-flight cancellation,
- * so this contract carries no `grace` and no `signal`. A `timeout` and an output overflow both end
- * the child with `SIGKILL`; an overflow reports `truncated` and `failed` together, which is where
- * the synchronous and asynchronous runners genuinely differ.
- */
-export declare interface RunSyncOptions {
-    /** The working directory. Default: the current working directory. */
-    readonly workspace?: string;
-    /** Environment overrides merged over the parent environment; an `undefined` value unsets a key. */
-    readonly environment?: Readonly<Record<string, string | undefined>>;
-    /** Standard input written to the child. */
-    readonly input?: string;
-    /** Milliseconds before the host kills the child. `0` or omitted disables the timeout. */
-    readonly timeout?: number;
-    /** If `false`, return the result on failure instead of throwing. Default: `true`. */
-    readonly strict?: boolean;
-    /** Maximum captured bytes for stdout and for stderr, each. Default: {@link PROCESS_OUTPUT}. */
-    readonly limit?: number;
-}
-
 /**
  * The resolved spawn form of one command: the executable to launch, the argument vector to pass,
  * and whether the host receives that vector verbatim.

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { holds } from "@orkestrel/contract";
+import { holds, isError } from "@orkestrel/contract";
 //#region src/core/constants.ts
 /** The default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
 var PROCESS_GRACE = 5e3;
@@ -14,6 +14,14 @@ var PROCESS_OUTPUT = 10485760;
 var PROCESS_TIMER = 2147483647;
 /** 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. */
+var PROCESS_ERROR_CODES = Object.freeze([
+	"spawn",
+	"timeout",
+	"duplicate",
+	"protocol",
+	"invalid"
+]);
 //#endregion
 //#region src/core/errors.ts
 /** A child-process failure with a stable machine-readable category. */
@@ -32,6 +40,7 @@ var ProcessError = class extends Error {
 	constructor(message, options) {
 		const cause = options.cause;
 		super(message, cause === void 0 ? void 0 : { cause });
+		Object.defineProperty(this, Symbol.for("@orkestrel/process.error"), { value: true });
 		this.code = options.code;
 		if (options.context !== void 0) this.context = options.context;
 		if (options.result !== void 0) this.result = options.result;
@@ -40,6 +49,13 @@ var ProcessError = class extends Error {
 /**
 * Checks whether an unknown value is a {@link ProcessError}.
 *
+* @remarks
+* Recognition combines a global own-property brand with the native `Error` base, the subclass
+* prototype, the fixed name, and a code {@link PROCESS_ERROR_CODES} declares. The brand is
+* recognized across duplicate installations and ESM/CommonJS module copies at 0.0.4 or later. A copy
+* earlier than 0.0.4 stamps no brand, so an error it throws stays outside the type, and so does a
+* plain or property-only lookalike.
+*
 * @param value - The value to inspect
 * @returns True only for a `ProcessError` instance; false otherwise
 *
@@ -50,7 +66,14 @@ var ProcessError = class extends Error {
 * ```
 */
 function isProcessError(value) {
-	return holds(() => value instanceof ProcessError);
+	if (!isError(value)) return false;
+	return holds(() => {
+		if (Object.getPrototypeOf(value) === Error.prototype) return false;
+		if (value.name !== "ProcessError" || !("code" in value)) return false;
+		if (Object.getOwnPropertyDescriptor(value, Symbol.for("@orkestrel/process.error"))?.value !== true) return false;
+		const code = value.code;
+		return PROCESS_ERROR_CODES.some((declared) => declared === code);
+	});
 }
 /**
 * Creates the failure raised when a manager launch reuses a live id.
@@ -98,14 +121,15 @@ function createInvalidError(subject, value) {
 * Creates the failure raised when a run does not complete successfully and rejection is requested.
 *
 * @remarks
-* The category is `timeout` only when the run's own timeout elapsed; every other failure, including
-* an abort and an output overflow, is a `spawn` failure carrying its {@link RunResult}.
+* The category is `timeout` only when the run's own timeout elapsed; every other failure,
+* including an abort and an output overflow, is a `spawn` failure carrying its
+* {@link ExecuteResult}.
 *
 * @param result - The buffered run outcome that failed
 * @param cause - The underlying host fault, when one ended the run
-* @returns A typed run failure carrying its {@link RunResult}
+* @returns A typed run failure carrying its {@link ExecuteResult}
 */
-function createRunError(result, cause) {
+function createExecuteError(result, cause) {
 	let reason = `exited with code ${String(result.code)}`;
 	if (result.signal !== null) reason = `was killed by ${result.signal}`;
 	if (result.truncated) reason = "exceeded its output limit";
@@ -123,6 +147,6 @@ function createRunError(result, cause) {
 	});
 }
 //#endregion
-export { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, PROCESS_PATHEXT, PROCESS_TIMER, ProcessError, createDuplicateError, createInvalidError, createProtocolError, createRunError, isProcessError };
+export { PROCESS_BACKLOG, PROCESS_CONFIRMATION, 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","import { holds } from '@orkestrel/contract'\nimport type {\n\tProcessErrorCode,\n\tProcessErrorContext,\n\tProcessErrorOptions,\n\tRunResult,\n} from './types.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?: RunResult\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\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 * @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\treturn holds(() => value instanceof ProcessError)\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, including\n * an abort and an output overflow, is a `spawn` failure carrying its {@link RunResult}.\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 RunResult}\n */\nexport function createRunError(result: RunResult, 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;;;;ACV/B,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,KAAK,OAAO,QAAQ;EACpB,IAAI,QAAQ,YAAY,KAAA,GAAW,KAAK,UAAU,QAAQ;EAC1D,IAAI,QAAQ,WAAW,KAAA,GAAW,KAAK,SAAS,QAAQ;CACzD;AACD;;;;;;;;;;;;;AAcA,SAAgB,eAAe,OAAuC;CACrE,OAAO,YAAY,iBAAiB,YAAY;AACjD;;;;;;;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;;;;;;;;;;;;AAaA,SAAgB,eAAe,QAAmB,OAA+B;CAChF,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/** 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"}