@orkestrel/process 0.0.7 → 0.0.8

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

@@ -16,6 +16,9 @@ import { ProcessManagerEventMap } from '@orkestrel/process';
 import { ProcessManagerInterface } from '@orkestrel/process';
 import { ProcessManagerOptions } from '@orkestrel/process';
 import { ProcessOptions } from '@orkestrel/process';
+import { SessionEventMap } from '@orkestrel/process';
+import { SessionInterface } from '@orkestrel/process';
+import { SessionOptions } from '@orkestrel/process';
 import { SpawnInput } from '@orkestrel/process';
 
 /**
@@ -151,6 +154,25 @@ export declare function createProcess(options: ProcessOptions): ProcessInterface
  */
 export declare function createProcessManager(options?: ProcessManagerOptions): ProcessManagerInterface;
 
+/**
+ * Creates one raw byte session over a supervised child process.
+ *
+ * @param options - Command, workspace, termination, evidence, stdin, and observation settings
+ * @returns The launched {@link SessionInterface}
+ *
+ * @example
+ * ```ts
+ * import { createSession } from '@orkestrel/process/server'
+ *
+ * const session = createSession({
+ * 	command: { file: 'node', arguments: ['server.js', '--stdio'] },
+ * 	workspace: process.cwd(),
+ * 	grace: 5000,
+ * })
+ * ```
+ */
+export declare function createSession(options: SessionOptions): SessionInterface;
+
 /**
  * Spawns one command as a detached process and returns without waiting for it.
  *
@@ -735,6 +757,108 @@ export declare interface RetentionInterface {
     retain(chunk: unknown, limit: number): Buffer_2 | undefined;
 }
 
+/**
+ * Supervises one child and publishes its standard output as raw bytes.
+ *
+ * @remarks
+ * This is the transport face of the supervision engine `Process` also composes. It frames nothing,
+ * retains nothing, and decodes nothing on the output side: every chunk the host delivers becomes one
+ * `stdout` event carrying that chunk's bytes, in arrival order, so a consumer speaking a
+ * length-prefixed or delimiter-framed protocol reads exactly what the child wrote and frames it
+ * itself. Standard error is decoded and forwarded as `stderr`, with the same byte-bounded `evidence`
+ * tail a `Process` retains, because a diagnostic stream is read rather than parsed.
+ *
+ * Each emitted chunk is this session's own copy, and a plain `Uint8Array` rather than the host buffer
+ * the read produced, so a consumer keeps it, mutates it, concatenates it, and reads its whole backing
+ * buffer without reaching memory the host still manages and without depending on a host type.
+ *
+ * The standard-input channel is open from the spawn, and `end` closes it without terminating
+ * anything. That is the member a cooperative protocol reaches for: the child observes end of input
+ * and exits on its own, which `ending` reports. `stop` and `destroy` remain the terminations, and
+ * `exit` remains the terminal moment — the native exit plus at most `drain` while a descendant holds
+ * the inherited read ends.
+ *
+ * @example
+ * ```ts
+ * import { Session } from '@orkestrel/process/server'
+ *
+ * const session = new Session({
+ * 	command: { file: 'node', arguments: ['-e', 'process.stdin.pipe(process.stdout)'] },
+ * 	workspace: process.cwd(),
+ * })
+ * ```
+ */
+export declare class Session implements SessionInterface {
+    #private;
+    /**
+     * Spawn one child process and begin 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
+     */
+    constructor(options: SessionOptions);
+    /** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+    get pid(): number | undefined;
+    /** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+    get 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. */
+    get signal(): string | null;
+    /** The typed lifecycle observation surface. */
+    get emitter(): EmitterInterface<SessionEventMap>;
+    /** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+    get evidence(): string;
+    /** True after the terminal moment arrived and `exit` settled. */
+    get settled(): boolean;
+    /** True after termination began, including after the terminal moment. `end` never turns it true. */
+    get stopping(): boolean;
+    /** The child's own ending, awaited without the terminal moment's drain window. */
+    get ending(): Promise<void>;
+    /** The terminal child state, observed once after stream close or the drain cutoff. */
+    get exit(): Promise<ProcessExit>;
+    /**
+     * Writes raw bytes to the open standard-input channel.
+     *
+     * @remarks
+     * Never rejects, and appends no terminator: the child receives exactly these bytes. `true` means
+     * the host accepted them without reporting a fault; it does not prove that the child read them.
+     * The channel can queue the payload, so treat the array as owned by the channel until the
+     * 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`
+     */
+    write(bytes: Uint8Array): Promise<boolean>;
+    /**
+     * Closes the standard-input channel and leaves the child running.
+     *
+     * @remarks
+     * Never rejects and terminates nothing: `stopping` stays false and the terminal moment does not
+     * arrive. Every call shares one barrier, which resolves after the host flushes the writes it had
+     * already accepted. A later `write` resolves `false`.
+     *
+     * @returns The stable barrier shared by every call
+     */
+    end(): Promise<void>;
+    /**
+     * Terminates the child process tree and reaches the terminal observation moment.
+     *
+     * @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
+     */
+    stop(): Promise<boolean>;
+    /**
+     * Stops the child and destroys the observation emitter after the terminal state freezes.
+     *
+     * @remarks
+     * Always resolves, including when termination was never confirmed. Every call shares one barrier.
+     *
+     * @returns The stable barrier shared by every call
+     */
+    destroy(): Promise<void>;
+}
+
 /**
  * Takes one owned frozen snapshot of a caller's command.
  *

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

@@ -16,6 +16,9 @@ import { ProcessManagerEventMap } from '@orkestrel/process';
 import { ProcessManagerInterface } from '@orkestrel/process';
 import { ProcessManagerOptions } from '@orkestrel/process';
 import { ProcessOptions } from '@orkestrel/process';
+import { SessionEventMap } from '@orkestrel/process';
+import { SessionInterface } from '@orkestrel/process';
+import { SessionOptions } from '@orkestrel/process';
 import { SpawnInput } from '@orkestrel/process';
 
 /**
@@ -151,6 +154,25 @@ export declare function createProcess(options: ProcessOptions): ProcessInterface
  */
 export declare function createProcessManager(options?: ProcessManagerOptions): ProcessManagerInterface;
 
+/**
+ * Creates one raw byte session over a supervised child process.
+ *
+ * @param options - Command, workspace, termination, evidence, stdin, and observation settings
+ * @returns The launched {@link SessionInterface}
+ *
+ * @example
+ * ```ts
+ * import { createSession } from '@orkestrel/process/server'
+ *
+ * const session = createSession({
+ * 	command: { file: 'node', arguments: ['server.js', '--stdio'] },
+ * 	workspace: process.cwd(),
+ * 	grace: 5000,
+ * })
+ * ```
+ */
+export declare function createSession(options: SessionOptions): SessionInterface;
+
 /**
  * Spawns one command as a detached process and returns without waiting for it.
  *
@@ -735,6 +757,108 @@ export declare interface RetentionInterface {
     retain(chunk: unknown, limit: number): Buffer_2 | undefined;
 }
 
+/**
+ * Supervises one child and publishes its standard output as raw bytes.
+ *
+ * @remarks
+ * This is the transport face of the supervision engine `Process` also composes. It frames nothing,
+ * retains nothing, and decodes nothing on the output side: every chunk the host delivers becomes one
+ * `stdout` event carrying that chunk's bytes, in arrival order, so a consumer speaking a
+ * length-prefixed or delimiter-framed protocol reads exactly what the child wrote and frames it
+ * itself. Standard error is decoded and forwarded as `stderr`, with the same byte-bounded `evidence`
+ * tail a `Process` retains, because a diagnostic stream is read rather than parsed.
+ *
+ * Each emitted chunk is this session's own copy, and a plain `Uint8Array` rather than the host buffer
+ * the read produced, so a consumer keeps it, mutates it, concatenates it, and reads its whole backing
+ * buffer without reaching memory the host still manages and without depending on a host type.
+ *
+ * The standard-input channel is open from the spawn, and `end` closes it without terminating
+ * anything. That is the member a cooperative protocol reaches for: the child observes end of input
+ * and exits on its own, which `ending` reports. `stop` and `destroy` remain the terminations, and
+ * `exit` remains the terminal moment — the native exit plus at most `drain` while a descendant holds
+ * the inherited read ends.
+ *
+ * @example
+ * ```ts
+ * import { Session } from '@orkestrel/process/server'
+ *
+ * const session = new Session({
+ * 	command: { file: 'node', arguments: ['-e', 'process.stdin.pipe(process.stdout)'] },
+ * 	workspace: process.cwd(),
+ * })
+ * ```
+ */
+export declare class Session implements SessionInterface {
+    #private;
+    /**
+     * Spawn one child process and begin 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
+     */
+    constructor(options: SessionOptions);
+    /** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+    get pid(): number | undefined;
+    /** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+    get 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. */
+    get signal(): string | null;
+    /** The typed lifecycle observation surface. */
+    get emitter(): EmitterInterface<SessionEventMap>;
+    /** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+    get evidence(): string;
+    /** True after the terminal moment arrived and `exit` settled. */
+    get settled(): boolean;
+    /** True after termination began, including after the terminal moment. `end` never turns it true. */
+    get stopping(): boolean;
+    /** The child's own ending, awaited without the terminal moment's drain window. */
+    get ending(): Promise<void>;
+    /** The terminal child state, observed once after stream close or the drain cutoff. */
+    get exit(): Promise<ProcessExit>;
+    /**
+     * Writes raw bytes to the open standard-input channel.
+     *
+     * @remarks
+     * Never rejects, and appends no terminator: the child receives exactly these bytes. `true` means
+     * the host accepted them without reporting a fault; it does not prove that the child read them.
+     * The channel can queue the payload, so treat the array as owned by the channel until the
+     * 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`
+     */
+    write(bytes: Uint8Array): Promise<boolean>;
+    /**
+     * Closes the standard-input channel and leaves the child running.
+     *
+     * @remarks
+     * Never rejects and terminates nothing: `stopping` stays false and the terminal moment does not
+     * arrive. Every call shares one barrier, which resolves after the host flushes the writes it had
+     * already accepted. A later `write` resolves `false`.
+     *
+     * @returns The stable barrier shared by every call
+     */
+    end(): Promise<void>;
+    /**
+     * Terminates the child process tree and reaches the terminal observation moment.
+     *
+     * @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
+     */
+    stop(): Promise<boolean>;
+    /**
+     * Stops the child and destroys the observation emitter after the terminal state freezes.
+     *
+     * @remarks
+     * Always resolves, including when termination was never confirmed. Every call shares one barrier.
+     *
+     * @returns The stable barrier shared by every call
+     */
+    destroy(): Promise<void>;
+}
+
 /**
  * Takes one owned frozen snapshot of a caller's command.
  *