@orkestrel/process 0.0.9 → 0.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -8,6 +8,42 @@ import { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_DRAIN, PROCESS_EVIDENCE,
8
8
  import { createInterface } from "node:readline";
9
9
  import { Emitter } from "@orkestrel/emitter";
10
10
  import { StringDecoder } from "node:string_decoder";
11
+ //#region src/server/cloners.ts
12
+ /**
13
+ * Takes one owned frozen snapshot of a caller's command.
14
+ *
15
+ * @remarks
16
+ * Every public entry point snapshots before it validates, so the object validated is the object
17
+ * spawned. Each property is read exactly once, because reading one runs the caller's own getter: a
18
+ * command whose `file` changes between reads would otherwise validate one executable and spawn
19
+ * another. The argument vector and the environment record are copied and frozen, so a caller
20
+ * mutating either after the call cannot reach the spawn. An absent optional stays absent rather than
21
+ * becoming an explicit `undefined`.
22
+ *
23
+ * @param command - The caller's command, whose properties may be getters
24
+ * @returns A frozen command carrying the values read at this instant
25
+ *
26
+ * @example
27
+ * ```ts
28
+ * snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
29
+ * ```
30
+ */
31
+ function snapshotCommand(command) {
32
+ const file = command.file;
33
+ const argumentsList = Object.freeze([...command.arguments]);
34
+ const sourceEnvironment = command.environment;
35
+ const environment = sourceEnvironment === void 0 ? void 0 : Object.freeze({ ...sourceEnvironment });
36
+ const input = command.input;
37
+ const isolated = command.isolated;
38
+ return Object.freeze({
39
+ file,
40
+ arguments: argumentsList,
41
+ ...environment === void 0 ? {} : { environment },
42
+ ...input === void 0 ? {} : { input },
43
+ ...isolated === void 0 ? {} : { isolated }
44
+ });
45
+ }
46
+ //#endregion
11
47
  //#region src/server/helpers.ts
12
48
  /**
13
49
  * Trims a buffer to at most `limit` trailing bytes without splitting a UTF-8 sequence.
@@ -106,40 +142,6 @@ function captureChunk(chunk, room) {
106
142
  return Buffer.from(chunk.subarray(0, room));
107
143
  }
108
144
  /**
109
- * Takes one owned frozen snapshot of a caller's command.
110
- *
111
- * @remarks
112
- * Every public entry point snapshots before it validates, so the object validated is the object
113
- * spawned. Each property is read exactly once, because reading one runs the caller's own getter: a
114
- * command whose `file` changes between reads would otherwise validate one executable and spawn
115
- * another. The argument vector and the environment record are copied and frozen, so a caller
116
- * mutating either after the call cannot reach the spawn. An absent optional stays absent rather than
117
- * becoming an explicit `undefined`.
118
- *
119
- * @param command - The caller's command, whose properties may be getters
120
- * @returns A frozen command carrying the values read at this instant
121
- *
122
- * @example
123
- * ```ts
124
- * snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
125
- * ```
126
- */
127
- function snapshotCommand(command) {
128
- const file = command.file;
129
- const argumentsList = Object.freeze([...command.arguments]);
130
- const sourceEnvironment = command.environment;
131
- const environment = sourceEnvironment === void 0 ? void 0 : Object.freeze({ ...sourceEnvironment });
132
- const input = command.input;
133
- const isolated = command.isolated;
134
- return Object.freeze({
135
- file,
136
- arguments: argumentsList,
137
- ...environment === void 0 ? {} : { environment },
138
- ...input === void 0 ? {} : { input },
139
- ...isolated === void 0 ? {} : { isolated }
140
- });
141
- }
142
- /**
143
145
  * Renders one command into its diagnostic command line.
144
146
  *
145
147
  * @param command - The executable and its argument vector
@@ -256,7 +258,7 @@ function mergeEnvironment(isolated, base, override) {
256
258
  * command. An unreadable or malformed path reports `false` rather than throwing.
257
259
  *
258
260
  * @param target - The absolute or relative path to inspect
259
- * @returns True when the path resolves to a regular file; false otherwise
261
+ * @returns True if the path resolves to a regular file; false otherwise
260
262
  *
261
263
  * @example
262
264
  * ```ts
@@ -304,7 +306,8 @@ function buildExecutableCandidates(file, workspace, environment, platform) {
304
306
  return Object.freeze(targets);
305
307
  }
306
308
  /**
307
- * Resolves a command file to the executable path the host would launch.
309
+ * Resolves a command file to the executable path the host would launch, or to `undefined` on a POSIX
310
+ * host, which performs its own lookup.
308
311
  *
309
312
  * @param file - The command executable name or path
310
313
  * @param options - The directory searched first and the child's effective environment
@@ -529,7 +532,7 @@ function validateWorkspace(workspace) {
529
532
  * initiated against a pid the host may have reused.
530
533
  *
531
534
  * @param child - The child boundary
532
- * @returns True when the process has exited; false while it is live
535
+ * @returns True if the process has exited; false otherwise
533
536
  *
534
537
  * @example
535
538
  * ```ts
@@ -585,7 +588,7 @@ function killProcess(child, signal) {
585
588
  *
586
589
  * @param pid - The root process id of the tree to end
587
590
  * @param timeout - The milliseconds the utility is given before it is killed
588
- * @returns True when the utility reported success; false when it failed, was unavailable, or was cut off
591
+ * @returns True if the utility reported success; false otherwise (it failed, was unavailable, or was cut off)
589
592
  *
590
593
  * @example
591
594
  * ```ts
@@ -636,7 +639,7 @@ function waitForExit(child, timeout) {
636
639
  *
637
640
  * @param child - The child boundary
638
641
  * @param timeout - The milliseconds to wait before giving up
639
- * @returns True when the host close arrived inside the deadline; false otherwise
642
+ * @returns True if the host close arrived inside the deadline; false otherwise
640
643
  *
641
644
  * @example
642
645
  * ```ts
@@ -671,7 +674,7 @@ function waitForClose(child, timeout) {
671
674
  * @param child - The child boundary
672
675
  * @param grace - The cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL`
673
676
  * @param confirm - The milliseconds the native exit is awaited after the final kill
674
- * @returns True when the native exit was observed; false when `confirm` elapsed without it
677
+ * @returns True if the native exit was observed; false otherwise (`confirm` elapsed without it)
675
678
  *
676
679
  * @example
677
680
  * ```ts
@@ -1029,7 +1032,7 @@ function detach(command, options) {
1029
1032
  child.unref();
1030
1033
  }
1031
1034
  //#endregion
1032
- //#region src/server/Supervisor.ts
1035
+ //#region src/server/processes/Supervisor.ts
1033
1036
  /**
1034
1037
  * Supervises one child process and reports each lifecycle moment to the face composing it.
1035
1038
  *
@@ -1058,6 +1061,25 @@ function detach(command, options) {
1058
1061
  * termination completes. `relieve` is optional because a face that never pauses the child's output
1059
1062
  * holds no backpressure to release, and a face with nothing to do there would otherwise declare an
1060
1063
  * empty method to say so.
1064
+ *
1065
+ * @example
1066
+ * ```ts
1067
+ * import { Supervisor } from '@orkestrel/process/server'
1068
+ *
1069
+ * const engine = new Supervisor(
1070
+ * { command: { file: 'node', arguments: ['--version'] }, workspace: process.cwd() },
1071
+ * {
1072
+ * chunk: () => undefined,
1073
+ * fault: () => undefined,
1074
+ * close: () => undefined,
1075
+ * terminal: () => undefined,
1076
+ * teardown: () => undefined,
1077
+ * },
1078
+ * )
1079
+ * const exit = await engine.exit
1080
+ * exit.code // 0
1081
+ * await engine.destroy()
1082
+ * ```
1061
1083
  */
1062
1084
  var Supervisor = class {
1063
1085
  #chunk;
@@ -1087,7 +1109,7 @@ var Supervisor = class {
1087
1109
  #termination;
1088
1110
  #destruction;
1089
1111
  /**
1090
- * Spawn one child process and begin standard-error capture.
1112
+ * Spawns one child process and begins standard-error capture.
1091
1113
  *
1092
1114
  * @remarks
1093
1115
  * The face's callbacks are captured before anything is read or spawned, so the first moment the
@@ -1164,36 +1186,36 @@ var Supervisor = class {
1164
1186
  if (signal.aborted) this.stop();
1165
1187
  }
1166
1188
  }
1167
- /** The child's standard-output stream, for the composing face to attach its own consumer to. */
1189
+ /** Holds the child's standard-output stream, for the composing face to attach its own consumer to. */
1168
1190
  get stdout() {
1169
1191
  return this.#child.stdout;
1170
1192
  }
1171
- /** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
1193
+ /** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
1172
1194
  get pid() {
1173
1195
  return this.#child.pid;
1174
1196
  }
1175
- /** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
1197
+ /** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
1176
1198
  get code() {
1177
1199
  return this.#child.exitCode;
1178
1200
  }
1179
- /** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
1201
+ /** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
1180
1202
  get signal() {
1181
1203
  return this.#child.signalCode;
1182
1204
  }
1183
- /** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
1205
+ /** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
1184
1206
  get evidence() {
1185
1207
  return this.#tail.toString("utf8");
1186
1208
  }
1187
- /** True after the terminal moment arrived and `exit` settled. */
1209
+ /** Reports whether the terminal moment arrived and `exit` settled. */
1188
1210
  get settled() {
1189
1211
  return this.#settled;
1190
1212
  }
1191
- /** True after termination began, including after the terminal moment. */
1213
+ /** Reports whether termination began, including after the terminal moment. */
1192
1214
  get stopping() {
1193
1215
  return this.#stopping;
1194
1216
  }
1195
1217
  /**
1196
- * The child's own ending, awaited without the terminal moment's drain window.
1218
+ * Settles at the child's own ending, awaited without the terminal moment's drain window.
1197
1219
  *
1198
1220
  * @remarks
1199
1221
  * Never rejects, and resolves no value: `code` and `signal` carry the terminal facts as soon as
@@ -1203,7 +1225,7 @@ var Supervisor = class {
1203
1225
  get ending() {
1204
1226
  return this.#ending.promise;
1205
1227
  }
1206
- /** The terminal child state, observed once after stream close or the drain cutoff. */
1228
+ /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
1207
1229
  get exit() {
1208
1230
  return this.#exit.promise;
1209
1231
  }
@@ -1220,7 +1242,30 @@ var Supervisor = class {
1220
1242
  * discard.
1221
1243
  *
1222
1244
  * @param bytes - The payload to write, already framed by the caller
1223
- * @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`
1245
+ * @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
1246
+ *
1247
+ * @example
1248
+ * ```ts
1249
+ * import { Supervisor } from '@orkestrel/process/server'
1250
+ *
1251
+ * const engine = new Supervisor(
1252
+ * {
1253
+ * command: { file: 'node', arguments: ['-e', 'process.stdin.pipe(process.stdout)'] },
1254
+ * workspace: process.cwd(),
1255
+ * writable: true,
1256
+ * },
1257
+ * {
1258
+ * chunk: () => undefined,
1259
+ * fault: () => undefined,
1260
+ * close: () => undefined,
1261
+ * terminal: () => undefined,
1262
+ * teardown: () => undefined,
1263
+ * },
1264
+ * )
1265
+ * const accepted = await engine.deliver(new TextEncoder().encode('ping\n'))
1266
+ * accepted // true
1267
+ * await engine.destroy()
1268
+ * ```
1224
1269
  */
1225
1270
  deliver(bytes) {
1226
1271
  const stdin = this.#child.stdin;
@@ -1271,7 +1316,7 @@ var Supervisor = class {
1271
1316
  * and settles `exit` when they remain open. A cutoff reached before the native exit reports the
1272
1317
  * `code` and `signal` the host had recorded by then, which is `null` for a child still running.
1273
1318
  *
1274
- * @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
1319
+ * @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
1275
1320
  */
1276
1321
  stop() {
1277
1322
  if (this.#termination !== void 0) return this.#termination;
@@ -1399,9 +1444,10 @@ var Supervisor = class {
1399
1444
  }
1400
1445
  };
1401
1446
  //#endregion
1402
- //#region src/server/Process.ts
1447
+ //#region src/server/processes/Process.ts
1403
1448
  /**
1404
- * Supervises one child while keeping every observation channel aligned at termination.
1449
+ * Supervises one child, frames its standard output into lines under a bounded backlog, and keeps
1450
+ * every observation channel aligned at termination.
1405
1451
  *
1406
1452
  * @remarks
1407
1453
  * The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
@@ -1446,7 +1492,7 @@ var Process = class {
1446
1492
  #truncated = false;
1447
1493
  #ended = false;
1448
1494
  /**
1449
- * Spawn one child process and begin stream capture.
1495
+ * Spawns one child process and begins stream capture.
1450
1496
  *
1451
1497
  * @param options - Command, workspace, termination, capture, stdin, and observation settings
1452
1498
  * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
@@ -1501,48 +1547,48 @@ var Process = class {
1501
1547
  this.#reader.on("line", this.#push.bind(this));
1502
1548
  this.#reader.once("close", this.#finish.bind(this));
1503
1549
  }
1504
- /** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
1550
+ /** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
1505
1551
  get pid() {
1506
1552
  return this.#engine.pid;
1507
1553
  }
1508
- /** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
1554
+ /** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
1509
1555
  get code() {
1510
1556
  return this.#engine.code;
1511
1557
  }
1512
- /** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
1558
+ /** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
1513
1559
  get signal() {
1514
1560
  return this.#engine.signal;
1515
1561
  }
1516
- /** The typed lifecycle observation surface. */
1562
+ /** Holds the typed lifecycle observation surface. */
1517
1563
  get emitter() {
1518
1564
  return this.#emitter;
1519
1565
  }
1520
- /** The captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
1566
+ /** Yields the captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
1521
1567
  get lines() {
1522
1568
  return this.#lines;
1523
1569
  }
1524
- /** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
1570
+ /** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
1525
1571
  get evidence() {
1526
1572
  return this.#engine.evidence;
1527
1573
  }
1528
- /** True when the `lines` stream omitted output after a retention bound was reached. */
1574
+ /** Reports whether the `lines` stream omitted output after a retention bound was reached. */
1529
1575
  get truncated() {
1530
1576
  return this.#truncated;
1531
1577
  }
1532
- /** True after the terminal moment arrived and `exit` settled. */
1578
+ /** Reports whether the terminal moment arrived and `exit` settled. */
1533
1579
  get settled() {
1534
1580
  return this.#engine.settled;
1535
1581
  }
1536
- /** True after termination began, including after the terminal moment. */
1582
+ /** Reports whether termination began, including after the terminal moment. */
1537
1583
  get stopping() {
1538
1584
  return this.#engine.stopping;
1539
1585
  }
1540
- /** The terminal child state, observed once after stream close or the drain cutoff. */
1586
+ /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
1541
1587
  get exit() {
1542
1588
  return this.#engine.exit;
1543
1589
  }
1544
1590
  /**
1545
- * Write one line to the open standard-input channel.
1591
+ * Writes one line to the open standard-input channel.
1546
1592
  *
1547
1593
  * @remarks
1548
1594
  * Never rejects. `true` means the host accepted the bytes without reporting a fault; it does not
@@ -1556,7 +1602,7 @@ var Process = class {
1556
1602
  * for bytes the package is about to discard.
1557
1603
  *
1558
1604
  * @param text - The line text without its trailing newline
1559
- * @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`
1605
+ * @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
1560
1606
  */
1561
1607
  send(text) {
1562
1608
  return this.#engine.deliver(Buffer.from(`${text}\n`, "utf8"));
@@ -1570,7 +1616,7 @@ var Process = class {
1570
1616
  * and settles `exit` when they remain open. A cutoff reached before the native exit reports the
1571
1617
  * `code` and `signal` the host had recorded by then, which is `null` for a child still running.
1572
1618
  *
1573
- * @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
1619
+ * @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
1574
1620
  */
1575
1621
  stop() {
1576
1622
  return this.#engine.stop();
@@ -1688,9 +1734,10 @@ var Process = class {
1688
1734
  }
1689
1735
  };
1690
1736
  //#endregion
1691
- //#region src/server/ProcessManager.ts
1737
+ //#region src/server/processes/ProcessManager.ts
1692
1738
  /**
1693
- * A keyed registry of live supervised child processes.
1739
+ * Launches supervised children under caller-chosen ids, evicts each one as it settles, and destroys
1740
+ * every live child on teardown.
1694
1741
  *
1695
1742
  * @remarks
1696
1743
  * A child launched under an id joins the registry and emits `launch`; when it settles it removes
@@ -1726,7 +1773,7 @@ var ProcessManager = class {
1726
1773
  #destroying = false;
1727
1774
  #ending;
1728
1775
  /**
1729
- * Construct a process registry.
1776
+ * Constructs a process registry.
1730
1777
  *
1731
1778
  * @param options - Initial fleet-level observation hooks and listener-error handling
1732
1779
  */
@@ -1738,16 +1785,16 @@ var ProcessManager = class {
1738
1785
  ...error === void 0 ? {} : { error }
1739
1786
  });
1740
1787
  }
1741
- /** The typed fleet-level observation surface. */
1788
+ /** Holds the typed fleet-level observation surface. */
1742
1789
  get emitter() {
1743
1790
  return this.#emitter;
1744
1791
  }
1745
- /** The number of live children. */
1792
+ /** Counts the live children. */
1746
1793
  get count() {
1747
1794
  return this.#children.size;
1748
1795
  }
1749
1796
  /**
1750
- * The live child under `id`, or `undefined` when none is.
1797
+ * Returns the live child under `id`, or `undefined` when none is.
1751
1798
  *
1752
1799
  * @param id - The registry key
1753
1800
  * @returns The child, or `undefined`
@@ -1756,7 +1803,7 @@ var ProcessManager = class {
1756
1803
  return this.#children.get(id);
1757
1804
  }
1758
1805
  /**
1759
- * A snapshot of every live child.
1806
+ * Returns a snapshot of every live child.
1760
1807
  *
1761
1808
  * @returns The live children in launch order
1762
1809
  */
@@ -1764,7 +1811,7 @@ var ProcessManager = class {
1764
1811
  return [...this.#children.values()];
1765
1812
  }
1766
1813
  /**
1767
- * Spawn and register one child under `id`.
1814
+ * Spawns and registers one child under `id`.
1768
1815
  *
1769
1816
  * @remarks
1770
1817
  * {@link Process} reads every option before it spawns, so a caller's own option getter runs while
@@ -1802,7 +1849,7 @@ var ProcessManager = class {
1802
1849
  return this.#stopMany(target);
1803
1850
  }
1804
1851
  /**
1805
- * Stop every child, then destroy the registry emitter last.
1852
+ * Stops every child, then destroys the registry emitter last.
1806
1853
  *
1807
1854
  * @remarks
1808
1855
  * Always resolves, and refuses a later `launch` with a {@link createProtocolError}. Each child is
@@ -1855,7 +1902,7 @@ var ProcessManager = class {
1855
1902
  }
1856
1903
  };
1857
1904
  //#endregion
1858
- //#region src/server/Session.ts
1905
+ //#region src/server/processes/Session.ts
1859
1906
  /**
1860
1907
  * Supervises one child and publishes its standard output as raw bytes.
1861
1908
  *
@@ -1892,7 +1939,7 @@ var Session = class {
1892
1939
  #engine;
1893
1940
  #output;
1894
1941
  /**
1895
- * Spawn one child process and begin byte capture.
1942
+ * Spawns one child process and begins byte capture.
1896
1943
  *
1897
1944
  * @param options - Command, workspace, termination, evidence, stdin, and observation settings
1898
1945
  * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
@@ -1930,39 +1977,39 @@ var Session = class {
1930
1977
  });
1931
1978
  this.#engine.stdout.on("data", this.#output);
1932
1979
  }
1933
- /** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
1980
+ /** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
1934
1981
  get pid() {
1935
1982
  return this.#engine.pid;
1936
1983
  }
1937
- /** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
1984
+ /** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
1938
1985
  get code() {
1939
1986
  return this.#engine.code;
1940
1987
  }
1941
- /** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
1988
+ /** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
1942
1989
  get signal() {
1943
1990
  return this.#engine.signal;
1944
1991
  }
1945
- /** The typed lifecycle observation surface. */
1992
+ /** Holds the typed lifecycle observation surface. */
1946
1993
  get emitter() {
1947
1994
  return this.#emitter;
1948
1995
  }
1949
- /** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
1996
+ /** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
1950
1997
  get evidence() {
1951
1998
  return this.#engine.evidence;
1952
1999
  }
1953
- /** True after the terminal moment arrived and `exit` settled. */
2000
+ /** Reports whether the terminal moment arrived and `exit` settled. */
1954
2001
  get settled() {
1955
2002
  return this.#engine.settled;
1956
2003
  }
1957
- /** True after termination began, including after the terminal moment. `end` never turns it true. */
2004
+ /** Reports whether termination began, including after the terminal moment. `end` never turns it true. */
1958
2005
  get stopping() {
1959
2006
  return this.#engine.stopping;
1960
2007
  }
1961
- /** The child's own ending, awaited without the terminal moment's drain window. */
2008
+ /** Settles at the child's own ending, awaited without the terminal moment's drain window. */
1962
2009
  get ending() {
1963
2010
  return this.#engine.ending;
1964
2011
  }
1965
- /** The terminal child state, observed once after stream close or the drain cutoff. */
2012
+ /** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
1966
2013
  get exit() {
1967
2014
  return this.#engine.exit;
1968
2015
  }
@@ -1976,7 +2023,7 @@ var Session = class {
1976
2023
  * returned promise settles.
1977
2024
  *
1978
2025
  * @param bytes - The payload to write, already framed by the caller
1979
- * @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`
2026
+ * @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
1980
2027
  */
1981
2028
  write(bytes) {
1982
2029
  return this.#engine.deliver(bytes);
@@ -2000,7 +2047,7 @@ var Session = class {
2000
2047
  * @remarks
2001
2048
  * Never rejects, and every call shares one termination bounded by `grace` and `drain`.
2002
2049
  *
2003
- * @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
2050
+ * @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
2004
2051
  */
2005
2052
  stop() {
2006
2053
  return this.#engine.stop();
@@ -2036,27 +2083,37 @@ var Session = class {
2036
2083
  //#endregion
2037
2084
  //#region src/server/factories.ts
2038
2085
  /**
2039
- * Creates one supervised child process.
2086
+ * Creates one supervised child process and returns it as a {@link ProcessInterface}, so a caller
2087
+ * holds the published contract rather than the `Process` class.
2040
2088
  *
2041
2089
  * @param options - Command, workspace, termination, evidence, stdin, and observation settings
2042
2090
  * @returns The launched {@link ProcessInterface}
2043
2091
  *
2044
- * @example
2092
+ * @example Supervise a child and read its lines
2045
2093
  * ```ts
2046
2094
  * import { createProcess } from '@orkestrel/process/server'
2047
2095
  *
2048
2096
  * const child = createProcess({
2049
- * command: { file: 'node', arguments: ['--version'] },
2097
+ * command: { file: 'node', arguments: ['-e', 'console.log("ready"); console.log("done")'] },
2050
2098
  * workspace: process.cwd(),
2051
- * grace: 5000,
2099
+ * grace: 5_000, // POSIX only: the window between SIGTERM and SIGKILL
2052
2100
  * })
2101
+ *
2102
+ * const lines: string[] = []
2103
+ * for await (const line of child.lines) lines.push(line)
2104
+ * lines // ['ready', 'done']
2105
+ *
2106
+ * const exit = await child.exit
2107
+ * exit.code // 0
2108
+ * await child.destroy()
2053
2109
  * ```
2054
2110
  */
2055
2111
  function createProcess(options) {
2056
2112
  return new Process(options);
2057
2113
  }
2058
2114
  /**
2059
- * Creates one raw byte session over a supervised child process.
2115
+ * Creates one raw byte session over a supervised child process and returns it as a
2116
+ * {@link SessionInterface}, so a caller holds the published contract rather than the `Session` class.
2060
2117
  *
2061
2118
  * @param options - Command, workspace, termination, evidence, stdin, and observation settings
2062
2119
  * @returns The launched {@link SessionInterface}
@@ -2076,7 +2133,9 @@ function createSession(options) {
2076
2133
  return new Session(options);
2077
2134
  }
2078
2135
  /**
2079
- * Creates one keyed registry of supervised child processes.
2136
+ * Creates one empty keyed registry of supervised child processes and returns it as a
2137
+ * {@link ProcessManagerInterface}, so a caller holds the published contract rather than the
2138
+ * `ProcessManager` class.
2080
2139
  *
2081
2140
  * @param options - Initial fleet-level observation hooks and listener-error handling
2082
2141
  * @returns The {@link ProcessManagerInterface} registry
@@ -2092,6 +2151,6 @@ function createProcessManager(options) {
2092
2151
  return new ProcessManager(options);
2093
2152
  }
2094
2153
  //#endregion
2095
- export { Process, ProcessManager, Session, buildExecutableCandidates, buildExecuteResult, buildPlatformSpawn, buildSpawn, captureChunk, createProcess, createProcessManager, createSession, detach, execute, executeSync, formatCommand, isExited, isFile, killProcess, killTree, mergeEnvironment, mergePlatformEnvironment, quoteArgument, readPlatformVariable, readVariable, resolveExecutable, snapshotCommand, stopChild, trimHead, trimTail, validateBytes, validateCommand, validateEnvironment, validateText, validateTimer, validateWorkspace, waitForClose, waitForExit };
2154
+ export { Process, ProcessManager, Session, Supervisor, buildExecutableCandidates, buildExecuteResult, buildPlatformSpawn, buildSpawn, captureChunk, createProcess, createProcessManager, createSession, detach, execute, executeSync, formatCommand, isExited, isFile, killProcess, killTree, mergeEnvironment, mergePlatformEnvironment, quoteArgument, readPlatformVariable, readVariable, resolveExecutable, snapshotCommand, stopChild, trimHead, trimTail, validateBytes, validateCommand, validateEnvironment, validateText, validateTimer, validateWorkspace, waitForClose, waitForExit };
2096
2155
 
2097
2156
  //# sourceMappingURL=index.js.map