@orkestrel/scaffold 0.0.119 → 0.0.120

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.
Files changed (49) hide show
  1. package/dist/bin/main.js +15 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  4. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  6. package/dist/host/claude/agents/orkestrel.md +27 -26
  7. package/dist/host/claude/rules/tests.md +2 -2
  8. package/dist/host/claude/rules/typescript.md +2 -3
  9. package/dist/host/guides/abort.md +0 -4
  10. package/dist/host/guides/budget.md +1 -5
  11. package/dist/host/guides/codec.md +18 -3
  12. package/dist/host/guides/contract.md +23 -44
  13. package/dist/host/guides/csv.md +86 -93
  14. package/dist/host/guides/database.md +0 -4
  15. package/dist/host/guides/emitter.md +0 -2
  16. package/dist/host/guides/form.md +26 -47
  17. package/dist/host/guides/html.md +3 -7
  18. package/dist/host/guides/indexeddb.md +28 -32
  19. package/dist/host/guides/jsonrpc.md +187 -0
  20. package/dist/host/guides/markdown.md +132 -141
  21. package/dist/host/guides/msg.md +47 -63
  22. package/dist/host/guides/ndjson.md +0 -4
  23. package/dist/host/guides/pool.md +0 -4
  24. package/dist/host/guides/process.md +71 -79
  25. package/dist/host/guides/reason.md +30 -36
  26. package/dist/host/guides/router.md +11 -18
  27. package/dist/host/guides/scaffold.md +136 -136
  28. package/dist/host/guides/sqlite.md +0 -4
  29. package/dist/host/guides/sse.md +6 -10
  30. package/dist/host/guides/table.md +481 -493
  31. package/dist/host/guides/template.md +0 -4
  32. package/dist/host/guides/test.md +46 -66
  33. package/dist/host/guides/timeout.md +0 -6
  34. package/dist/host/guides/tool.md +2 -6
  35. package/dist/host/guides/websocket.md +0 -4
  36. package/dist/host/manifest.json +39 -464
  37. package/dist/src/core/index.cjs +162 -177
  38. package/dist/src/core/index.cjs.map +1 -1
  39. package/dist/src/core/index.d.cts +213 -213
  40. package/dist/src/core/index.d.ts +213 -213
  41. package/dist/src/core/index.js +151 -166
  42. package/dist/src/core/index.js.map +1 -1
  43. package/dist/src/server/index.cjs +25 -25
  44. package/dist/src/server/index.cjs.map +1 -1
  45. package/dist/src/server/index.d.cts +50 -50
  46. package/dist/src/server/index.d.ts +50 -50
  47. package/dist/src/server/index.js +26 -26
  48. package/dist/src/server/index.js.map +1 -1
  49. package/package.json +9 -9
@@ -1,13 +1,13 @@
1
1
  # Process
2
2
 
3
3
  > A typed child-process toolkit in tiers: the supervised `Process` with framed stdout lines and a
4
- > writable stdin channel, the byte-oriented `Session`, the buffered `execute` and `executeSync`
4
+ > writable stdin channel, the byte-oriented `Duplex`, the buffered `execute` and `executeSync`
5
5
  > runs, the fire-and-forget `detach`, and the keyed `ProcessManager` registry, none of them spawning
6
6
  > through a shell.
7
7
 
8
8
  `Process` holds its framed lines under a bounded backlog, keeps a byte-bounded stderr tail as
9
9
  `evidence` beside a live `stderr` event, publishes a typed lifecycle emitter, and ends every
10
- observation channel at one terminal moment through a bounded termination. `Session` publishes one
10
+ observation channel at one terminal moment through a bounded termination. `Duplex` publishes one
11
11
  owned `Uint8Array` per stdout chunk instead, with an `end` that closes stdin without terminating
12
12
  anything and the child's own `ended` beside the terminal `exit`. A buffered run settles with an
13
13
  `ExecuteResult` carrying the captured output and the exit, while a detached child owns no stdio and
@@ -22,7 +22,7 @@ rather than syntax. The host-independent contracts, errors, constants, and types
22
22
  ## Surface
23
23
 
24
24
  The tiers divide by lifetime. Reach for `Process` when you need the live stream, the stdin
25
- channel, or the lifecycle events. Reach for `Session` when the child speaks a protocol and you need
25
+ channel, or the lifecycle events. Reach for `Duplex` when the child speaks a protocol and you need
26
26
  its exact bytes rather than framed lines. Reach for `execute` or `executeSync` when you want the
27
27
  buffered output and the exit in one call. Reach for `ProcessManager` when you supervise several
28
28
  children by id.
@@ -56,7 +56,7 @@ The interface-oriented constructors, from `@orkestrel/process/server`.
56
56
  | Name | Kind | Signature | Summary |
57
57
  | ---------------------- | -------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58
58
  | `createProcess` | function | `(options: ProcessOptions) => ProcessInterface` | Creates one supervised child process and returns it as a `ProcessInterface`, so a caller holds the published contract rather than the `Process` class. |
59
- | `createSession` | function | `(options: SessionOptions) => SessionInterface` | Creates one raw byte session over a supervised child process and returns it as a `SessionInterface`, so a caller holds the published contract rather than the `Session` class. |
59
+ | `createDuplex` | function | `(options: DuplexOptions) => DuplexInterface` | Creates one raw byte duplex over a supervised child process and returns it as a `DuplexInterface`, so a caller holds the published contract rather than the `Duplex` class. |
60
60
  | `createProcessManager` | function | `(options?: ProcessManagerOptions) => ProcessManagerInterface` | Creates one empty keyed registry of supervised child processes and returns it as a `ProcessManagerInterface`, so a caller holds the published contract rather than the `ProcessManager` class. |
61
61
 
62
62
  ### Spawns
@@ -79,7 +79,7 @@ in a Surface row.
79
79
  | Name | Kind | Signature | Summary |
80
80
  | ---------------- | ----- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
81
81
  | `Process` | class | `new (options: ProcessOptions) => ProcessInterface` | Supervises one child, frames its standard output into lines under a bounded backlog, and keeps every observation channel aligned at termination. |
82
- | `Session` | class | `new (options: SessionOptions) => SessionInterface` | Supervises one child and publishes its standard output as raw bytes. |
82
+ | `Duplex` | class | `new (options: DuplexOptions) => DuplexInterface` | Supervises one child and publishes its standard output as raw bytes. |
83
83
  | `Supervisor` | class | `new (options: ProcessOptions, face: SupervisorFace) => Supervisor` | Supervises one child process and reports each lifecycle moment to the face composing it. |
84
84
  | `ProcessManager` | class | `new (options?: ProcessManagerOptions) => ProcessManagerInterface` | Launches supervised children under caller-chosen ids, evicts each one as it settles, and destroys every live child on teardown. |
85
85
  | `ProcessError` | class | `new (message: string, options: ProcessErrorOptions) => ProcessError` | Represents a child-process failure with a stable machine-readable category. |
@@ -88,8 +88,6 @@ in a Surface row.
88
88
 
89
89
  The total guard, from `@orkestrel/process`.
90
90
 
91
- In a guard table a `Shape` cell holds the type the guard narrows to.
92
-
93
91
  | Name | Kind | Signature | Summary |
94
92
  | ---------------- | -------- | ------------------------------------------- | ---------------------------------------------------- |
95
93
  | `isProcessError` | function | `(value: unknown) => value is ProcessError` | Checks whether an unknown value is a `ProcessError`. |
@@ -119,7 +117,7 @@ The resolution and environment building blocks every spawn composes, from
119
117
  | `buildPlatformSpawn` | function | `(command: ProcessCommand, file: string, environment: Readonly<Record<string, string \| undefined>>, platform: NodeJS.Platform) => SpawnInput` | Builds a spawn form from a resolved file and an explicit platform. |
120
118
  | `buildExecutableCandidates` | function | `(file: string, workspace: string, environment: Readonly<Record<string, string \| undefined>>, platform: NodeJS.Platform) => readonly string[]` | Builds the executable candidates an explicit platform would search. |
121
119
  | `resolveExecutable` | function | `(file: string, options?: ExecutableOptions) => string \| undefined` | Resolves a command file to the executable path the host would launch, or to `undefined` on a POSIX host, which performs its own lookup. |
122
- | `isFile` | function | `(target: string) => boolean` | Checks whether a path names a regular file. |
120
+ | `namesFile` | function | `(target: string) => boolean` | Checks whether a path names a regular file. |
123
121
  | `readVariable` | function | `(environment: Readonly<Record<string, string \| undefined>>, name: string) => string \| undefined` | Reads one environment variable the way the current host resolves it. |
124
122
  | `readPlatformVariable` | function | `(environment: Readonly<Record<string, string \| undefined>>, name: string, platform: NodeJS.Platform) => string \| undefined` | Reads one environment variable under an explicit platform's key rules. |
125
123
  | `mergeEnvironment` | function | `(isolated: boolean, base?: Readonly<Record<string, string \| undefined>>, override?: Readonly<Record<string, string \| undefined>>) => NodeJS.ProcessEnv` | Merges environment overrides into the environment one child receives on the current host. |
@@ -176,8 +174,6 @@ The input refusals every public entry point runs before it spawns anything, from
176
174
 
177
175
  The defaults and host bounds, from `@orkestrel/process`.
178
176
 
179
- A `Shape` cell holds the constant's declared type.
180
-
181
177
  | Name | Kind | Signature | Summary |
182
178
  | ---------------------- | ----- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
183
179
  | `PROCESS_GRACE` | const | `5000` | Names the default cooperative POSIX window, 5000 ms, between `SIGTERM` and `SIGKILL` during termination. |
@@ -194,8 +190,6 @@ A `Shape` cell holds the constant's declared type.
194
190
 
195
191
  The contracts and options, all from `@orkestrel/process`.
196
192
 
197
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
198
-
199
193
  | Name | Kind | Signature | Summary |
200
194
  | ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
201
195
  | `ProcessCommand` | interface | `{ file, arguments, environment?, input?, isolated? }` | Represents one spawnable command: the executable, its argument vector, and optional environment overrides and initial standard input. |
@@ -205,9 +199,9 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
205
199
  | `ProcessEventMap` | type | `{ readonly stderr: readonly [chunk: string]; readonly error: readonly [error: unknown]; readonly exit: readonly [exit: ProcessExit]; }` | Represents the push observation surface of a `ProcessInterface` — the moments a fire-and-forget observer subscribes to, alongside the `lines` stream and the `exit` promise. |
206
200
  | `ProcessOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, backlog?, delivery?, writable?, signal? }` | Configures one supervised child process. |
207
201
  | `ProcessInterface` | interface | `{ pid, code, signal, emitter, lines, evidence, truncated, settled, terminated, exit, send(), stop(), destroy() }` | Represents one supervised child process with framed output, a bounded backlog, and bounded termination. |
208
- | `SessionEventMap` | type | `{ readonly stdout: readonly [chunk: Uint8Array]; readonly stderr: readonly [chunk: string]; readonly error: readonly [error: unknown]; readonly exit: readonly [exit: ProcessExit]; }` | Represents the push observation surface of a `SessionInterface` — the moments a byte-oriented observer subscribes to, alongside the `ended` and `exit` promises. |
209
- | `SessionOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, delivery?, signal? }` | Configures one raw byte session over a supervised child. |
210
- | `SessionInterface` | interface | `{ pid, code, signal, emitter, evidence, settled, terminated, ended, exit, write(), end(), stop(), destroy() }` | Represents one supervised child process read as raw bytes, with an open standard-input channel and bounded termination. |
202
+ | `DuplexEventMap` | type | `{ readonly stdout: readonly [chunk: Uint8Array]; readonly stderr: readonly [chunk: string]; readonly error: readonly [error: unknown]; readonly exit: readonly [exit: ProcessExit]; }` | Represents the push observation surface of a `DuplexInterface` — the moments a byte-oriented observer subscribes to, alongside the `ended` and `exit` promises. |
203
+ | `DuplexOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, delivery?, signal? }` | Configures one raw byte duplex over a supervised child. |
204
+ | `DuplexInterface` | interface | `{ pid, code, signal, emitter, evidence, settled, terminated, ended, exit, write(), end(), stop(), destroy() }` | Represents one supervised child process read as raw bytes, with an open standard-input channel and bounded termination. |
211
205
  | `ExecuteResult` | interface | `{ command, stdout, stderr, code, signal, failed, expired, aborted, truncated }` | Represents the settled outcome of a one-shot run: the buffered output and the terminal state. |
212
206
  | `ExecuteInput` | interface | `{ command, stdout, stderr, code, signal, expired, aborted, truncated, limit, cause? }` | Represents the captured bytes and terminal facts one settled `ExecuteResult` is built from. |
213
207
  | `ExecuteOptions` | interface | `{ workspace?, environment?, input?, timeout?, grace?, signal?, strict?, limit? }` | Configures a one-shot run. |
@@ -228,8 +222,6 @@ a host-independent contract cannot, and `SupervisorFace` names no Node type but
228
222
  Node-only `Supervisor` engine, so the contract sits with the face that constructs one. See
229
223
  [Vocabulary](#vocabulary) for the `Face` suffix.
230
224
 
231
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
232
-
233
225
  | Name | Kind | Signature | Summary |
234
226
  | ----------------------- | --------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
235
227
  | `ProcessChildInterface` | interface | `{ pid?, exitCode, signalCode, kill(), once(), off() }` | Represents the child boundary the termination helpers drive. |
@@ -237,10 +229,10 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
237
229
 
238
230
  ### Surface notes
239
231
 
240
- Every member a `Shape` cell names before `plus` is a readonly data property, so it stays a Surface
232
+ Every member a `Signature` cell names without parentheses is a readonly data property, so it stays a Surface
241
233
  row. `ended` and `exit` are among them: a promise you await is a value the entity holds, not a call
242
234
  you make. A `SupervisorFace` member is among them too: it holds a function the caller supplies
243
- rather than declaring one the contract implements. The call-signature members after `plus` are
235
+ rather than declaring one the contract implements. The members it names with parentheses are
244
236
  documented under [Methods](#methods).
245
237
 
246
238
  The `Supervisor` class publishes readonly data members of its own: `stdout`, `pid`, `code`, `signal`,
@@ -255,7 +247,7 @@ them off.
255
247
  ## Methods
256
248
 
257
249
  The public methods of each behavioral interface, and of the `Supervisor` class that publishes its
258
- own. `Process` implements `ProcessInterface` exactly, `Session` implements `SessionInterface`
250
+ own. `Process` implements `ProcessInterface` exactly, `Duplex` implements `DuplexInterface`
259
251
  exactly, and `ProcessManager` implements `ProcessManagerInterface` exactly, so each table doubles as
260
252
  the class's instance-method surface.
261
253
 
@@ -273,7 +265,7 @@ one holds a frozen `evidence`, an ended `lines`, and a settled `exit`.
273
265
  | `stop` | `Promise<boolean>` | Terminates the child process tree, awaits its observed exit, and reaches the terminal moment. |
274
266
  | `destroy` | `Promise<void>` | Stops the child, closes its standard-input channel, reaches the terminal moment, and destroys the observation emitter. |
275
267
 
276
- #### `SessionInterface`
268
+ #### `DuplexInterface`
277
269
 
278
270
  `write` puts raw bytes on the open stdin channel and `end` closes that channel; `stop` and `destroy`
279
271
  are the lifecycle verbs. None of them rejects, and each of `end`, `stop`, and `destroy` returns one
@@ -318,7 +310,7 @@ drive `stopChild`, `waitForExit`, and `waitForClose` over a child it spawned its
318
310
  #### `Supervisor`
319
311
 
320
312
  `deliver` writes raw bytes to the open stdin channel and `end` closes that channel; `stop` and
321
- `destroy` are the lifecycle verbs. None of them rejects. `Process` and `Session` each forward their
313
+ `destroy` are the lifecycle verbs. None of them rejects. `Process` and `Duplex` each forward their
322
314
  own member to one of these, so the engine's contract is the one both faces publish under their own
323
315
  names.
324
316
 
@@ -376,10 +368,10 @@ Every option and command property is read once, before the child is spawned. Rea
376
368
  whatever getter you put behind it, so hoisting those reads is what keeps a construction failure from
377
369
  leaving a live child nobody holds: a getter that throws does so while nothing has started.
378
370
 
379
- ### Byte sessions
371
+ ### Byte duplexes
380
372
 
381
- `Session` supervises the same child and publishes its standard output as raw bytes. Each chunk the
382
- host delivers becomes one `stdout` event carrying an owned `Uint8Array` — the session's own copy, and
373
+ `Duplex` supervises the same child and publishes its standard output as raw bytes. Each chunk the
374
+ host delivers becomes one `stdout` event carrying an owned `Uint8Array` — the duplex's own copy, and
383
375
  a plain `Uint8Array` rather than a Node `Buffer` — so you keep it, mutate it, and concatenate it
384
376
  without reaching memory the host still manages and without depending on a host type. Nothing is
385
377
  framed and nothing is decoded on that side. A chunk boundary is the host's, so one event is not one
@@ -387,29 +379,29 @@ message and a line feed inside a payload starts no new event; you frame the conc
387
379
  yourself. Standard error is decoded and forwarded as `stderr` with the same byte-bounded `evidence`
388
380
  tail a `Process` retains, because a diagnostic stream is read rather than parsed.
389
381
 
390
- Choose by what the child's output is. `Process` frames output a person or a log reads. `Session`
382
+ Choose by what the child's output is. `Process` frames output a person or a log reads. `Duplex`
391
383
  delivers output a parser reads — a length-prefixed protocol, a binary payload, anything a line framer
392
384
  would corrupt.
393
385
 
394
- `SessionOptions` is `ProcessOptions` without `backlog` and without `writable`. A session retains no
386
+ `DuplexOptions` is `ProcessOptions` without `backlog` and without `writable`. A duplex retains no
395
387
  lines, so no backlog bound applies to it; its stdin channel is open from the spawn until `end` closes
396
388
  it, so no switch selects whether one exists.
397
389
 
398
- `SessionOptions` requires `command` and `workspace`; the rest are optional:
399
-
400
- | Option | Type | Required | Meaning |
401
- | ----------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
402
- | `command` | `ProcessCommand` | yes | The executable, its argument vector, and optional environment overrides and stdin `input`. |
403
- | `workspace` | `string` | yes | The working directory the child runs in. |
404
- | `grace` | `number` | no | POSIX milliseconds between `SIGTERM` and `SIGKILL`. Default: `PROCESS_GRACE` (`5_000`). |
405
- | `drain` | `number` | no | Milliseconds the package waits for the child's read ends to close after its ended, before cutting them off; `0` cuts them off immediately. Default: `PROCESS_DRAIN` (`1_000`). |
406
- | `evidence` | `number` | no | Maximum retained stderr tail in bytes. Default: `PROCESS_EVIDENCE` (`2_048`). |
407
- | `delivery` | `number` | no | Milliseconds an unconfirmed `write` waits before resolving `false`; `0` or omitted disables the bound. |
408
- | `signal` | `AbortSignal` | no | Aborting this signal terminates the child through the same bounded `stop`. |
409
- | `on` | `EmitterHooks<SessionEventMap>` | no | Initial `stdout`, `stderr`, `error`, and `exit` listeners installed at construction. |
410
- | `error` | `EmitterErrorHandler` | no | Receives a listener's throw, isolated from the engine. |
411
-
412
- A session names the child's ending and the supervision's ending apart, because a transport acts on
390
+ `DuplexOptions` requires `command` and `workspace`; the rest are optional:
391
+
392
+ | Option | Type | Required | Meaning |
393
+ | ----------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
394
+ | `command` | `ProcessCommand` | yes | The executable, its argument vector, and optional environment overrides and stdin `input`. |
395
+ | `workspace` | `string` | yes | The working directory the child runs in. |
396
+ | `grace` | `number` | no | POSIX milliseconds between `SIGTERM` and `SIGKILL`. Default: `PROCESS_GRACE` (`5_000`). |
397
+ | `drain` | `number` | no | Milliseconds the package waits for the child's read ends to close after its ended, before cutting them off; `0` cuts them off immediately. Default: `PROCESS_DRAIN` (`1_000`). |
398
+ | `evidence` | `number` | no | Maximum retained stderr tail in bytes. Default: `PROCESS_EVIDENCE` (`2_048`). |
399
+ | `delivery` | `number` | no | Milliseconds an unconfirmed `write` waits before resolving `false`; `0` or omitted disables the bound. |
400
+ | `signal` | `AbortSignal` | no | Aborting this signal terminates the child through the same bounded `stop`. |
401
+ | `on` | `EmitterHooks<DuplexEventMap>` | no | Initial `stdout`, `stderr`, `error`, and `exit` listeners installed at construction. |
402
+ | `error` | `EmitterErrorHandler` | no | Receives a listener's throw, isolated from the engine. |
403
+
404
+ A duplex names the child's ending and the supervision's ending apart, because a transport acts on
413
405
  each differently. `ended` settles at the child's own native exit and resolves no value: `code` and
414
406
  `signal` already carry the terminal facts, so a second copy of them here could only drift from them.
415
407
  `exit` settles at [the terminal moment](#the-terminal-moment), which is that native exit plus at most
@@ -422,25 +414,25 @@ does not. It is the one member on either face that does not reach the terminal m
422
414
 
423
415
  ```ts
424
416
  import { Buffer } from 'node:buffer'
425
- import { createSession } from '@orkestrel/process/server'
417
+ import { createDuplex } from '@orkestrel/process/server'
426
418
 
427
- const session = createSession({
419
+ const duplex = createDuplex({
428
420
  command: { file: 'node', arguments: ['-e', 'process.stdin.pipe(process.stdout)'] },
429
421
  workspace: process.cwd(),
430
422
  })
431
423
 
432
424
  const received: Uint8Array[] = []
433
- session.emitter.on('stdout', (chunk) => received.push(chunk))
425
+ duplex.emitter.on('stdout', (chunk) => received.push(chunk))
434
426
 
435
- await session.write(new TextEncoder().encode('ping')) // true — the host accepted the bytes
436
- await session.end() // the child sees end of input; nothing terminated it
437
- await session.ended // it exited on its own
427
+ await duplex.write(new TextEncoder().encode('ping')) // true — the host accepted the bytes
428
+ await duplex.end() // the child sees end of input; nothing terminated it
429
+ await duplex.ended // it exited on its own
438
430
 
439
431
  Buffer.concat(received).toString('utf8') // 'ping' — the exact bytes, with no terminator added
440
- const exit = await session.exit
432
+ const exit = await duplex.exit
441
433
  exit.code // 0
442
- session.terminated // false — no termination was initiated
443
- await session.destroy()
434
+ duplex.terminated // false — no termination was initiated
435
+ await duplex.destroy()
444
436
  ```
445
437
 
446
438
  ### The terminal moment
@@ -453,7 +445,7 @@ surface is shaped around.
453
445
  - **The supervision's ending** is the terminal moment: `settled`, `exit`, `evidence`, and `lines`.
454
446
  They reach it together.
455
447
 
456
- `Session` gives the child's exit a member of its own, `ended`, which settles at the native exit
448
+ `Duplex` gives the child's exit a member of its own, `ended`, which settles at the native exit
457
449
  and resolves no value. `Process` carries no such member: a line consumer reads that ending from
458
450
  `code` and `signal`, which have always reported it.
459
451
 
@@ -482,10 +474,10 @@ At the terminal moment every observation surface stops moving, together:
482
474
  - The abort listener registered on the caller's `signal` option is released here, rather than at the
483
475
  `destroy` call that preceded it.
484
476
 
485
- A `Session` reaches the same moment through the same paths, with its byte events in place of `lines`:
477
+ A `Duplex` reaches the same moment through the same paths, with its byte events in place of `lines`:
486
478
  the last `stdout` and `stderr` events are delivered before the `exit` event, and none follows it.
487
479
 
488
- `end` is the one member on either face that does not reach the moment. It closes a session's stdin
480
+ `end` is the one member on either face that does not reach the moment. It closes a duplex's stdin
489
481
  channel and leaves the child running, so `terminated` stays false, no drain window is armed, and `exit`
490
482
  stays pending until the child ends itself or something terminates it. Every other verb here ends the
491
483
  observation; `end` ends only the input.
@@ -630,7 +622,7 @@ await echo.stop() // true — the native exit was observed
630
622
  await echo.destroy()
631
623
  ```
632
624
 
633
- A `Session` opens the same channel with no switch and writes to it with `write` rather than `send`.
625
+ A `Duplex` opens the same channel with no switch and writes to it with `write` rather than `send`.
634
626
  `write` puts the exact bytes on the channel and appends nothing, so a caller framing its own protocol
635
627
  composes the header and the delimiter itself. Every preceding refusal holds for `write` unchanged: it
636
628
  never rejects, and it resolves `false` for a channel that was closed, destroyed, ended, or failed,
@@ -638,11 +630,11 @@ for a write left unconfirmed through `delivery`, and for a call made after `stop
638
630
  The host can queue the payload, so treat the array you passed as owned by the channel until the
639
631
  returned promise settles.
640
632
 
641
- `end` closes a session's channel without terminating anything. Every call shares one barrier, which
633
+ `end` closes a duplex's channel without terminating anything. Every call shares one barrier, which
642
634
  resolves after the host flushes the writes it had already accepted. That flush carries no bound of
643
635
  its own: a child that stops reading its input leaves the accepted bytes in the pipe, and the barrier
644
636
  stays pending for as long as they sit there. Race `end` against a window of your own when you need a
645
- bound, the way [Close a byte session cooperatively](#close-a-byte-session-cooperatively) does, rather
637
+ bound, the way [Close a byte duplex cooperatively](#close-a-byte-duplex-cooperatively) does, rather
646
638
  than awaiting it bare. A `write` after `end` resolves
647
639
  `false`, because the host stops reporting an ended channel writable — that refusal is derived from
648
640
  the channel's state rather than declared by a second flag. The ended channel then stays quiet for its
@@ -668,7 +660,7 @@ the emitter last; it always resolves, including when termination was never confi
668
660
  after the frozen state exists, so a consumer watching the `stderr` event and a consumer reading
669
661
  `evidence` end on the same bytes.
670
662
 
671
- `Session` terminates through the same verbs with the same bounds and the same barriers. Run its
663
+ `Duplex` terminates through the same verbs with the same bounds and the same barriers. Run its
672
664
  cooperative shutdown first where the child supports one: call `end`, race `ended` against a window
673
665
  of your own, and call `stop` when that window expires.
674
666
 
@@ -787,7 +779,7 @@ extensionless name. For an extension-bearing name, it enumerates the literal pat
787
779
  candidates: `report.txt` resolves to a `report.txt` file where one exists, and to `report.txt.cmd`
788
780
  where none does. The lookup reads the child's effective environment, so an overridden `PATH`
789
781
  selects the executable the child would have found, it falls back to `PROCESS_PATHEXT` when the
790
- environment declares no `PATHEXT`, and it accepts a candidate only when `isFile` reports a regular
782
+ environment declares no `PATHEXT`, and it accepts a candidate only when `namesFile` reports a regular
791
783
  file. When no candidate is a regular file, `resolveExecutable` returns `undefined` and `buildSpawn`
792
784
  preserves the command file as written for native spawning.
793
785
 
@@ -1159,7 +1151,7 @@ value with `isProcessError`, then branch on `code`.
1159
1151
  `isProcessError` recognizes an error thrown by another installed copy of the package. It reads a
1160
1152
  global own-property brand rather than `instanceof`, so a duplicate installation and an ESM/CommonJS
1161
1153
  module copy both narrow. Recognition holds across copies that stamp their own identity under
1162
- `Symbol.for('@orkestrel/process.error')` as a non-enumerable, non-writable own property. The guard
1154
+ `Symbol.for('@orkestrel/process.ProcessError')` as a non-enumerable, non-writable own property. The guard
1163
1155
  requires the native `Error` base, a prototype other than `Error.prototype`, a declared code, and
1164
1156
  correctly shaped optional context and result members. It never reads `name`, so subclass instances
1165
1157
  pass. Older boolean brands, transparent proxies, and branded plain objects fail recognition.
@@ -1222,7 +1214,7 @@ createExecuteError(result).result === result // true
1222
1214
 
1223
1215
  ## Observing
1224
1216
 
1225
- `Process`, `Session`, and `ProcessManager` each expose a typed `emitter` for fire-and-forget
1217
+ `Process`, `Duplex`, and `ProcessManager` each expose a typed `emitter` for fire-and-forget
1226
1218
  observers — logging, metrics, tracing. Subscribe through `child.emitter.on(...)` or
1227
1219
  `manager.emitter.on(...)`, or wire initial listeners through the `on` option; supply an `error`
1228
1220
  handler to receive a listener's throw. The `error` handler and the `error` event are distinct: the
@@ -1234,7 +1226,7 @@ observer cannot corrupt the engine.
1234
1226
  | Event map | Events |
1235
1227
  | ------------------------ | ----------------------------------------------------------------- |
1236
1228
  | `ProcessEventMap` | `stderr(chunk)` · `error(cause)` · `exit(exit)` |
1237
- | `SessionEventMap` | `stdout(chunk)` · `stderr(chunk)` · `error(cause)` · `exit(exit)` |
1229
+ | `DuplexEventMap` | `stdout(chunk)` · `stderr(chunk)` · `error(cause)` · `exit(exit)` |
1238
1230
  | `ProcessManagerEventMap` | `launch(id)` · `exit(id, exit)` |
1239
1231
 
1240
1232
  A `Process` emits `stderr` for each decoded standard-error chunk, `error` when the child fails to
@@ -1246,8 +1238,8 @@ a `ProcessError` coded `protocol` whose `cause` is the host fault. A fault arisi
1246
1238
  `ProcessManager` emits `launch` when a child joins the registry and `exit`, with the child's id and
1247
1239
  terminal state, when it settles and leaves.
1248
1240
 
1249
- A `Session` emits the same `stderr`, `error`, and `exit` moments, and adds `stdout` for each chunk of
1250
- raw bytes the host delivered. The `stdout` payload is the session's own owned array, so a listener
1241
+ A `Duplex` emits the same `stderr`, `error`, and `exit` moments, and adds `stdout` for each chunk of
1242
+ raw bytes the host delivered. The `stdout` payload is the duplex's own owned array, so a listener
1251
1243
  can keep it past the call, and no `stdout` event follows the `exit` event.
1252
1244
 
1253
1245
  ```ts
@@ -1299,24 +1291,24 @@ await child.destroy()
1299
1291
  The abort reaches the terminal moment through the same bounded `stop`, so the loop exits on its own
1300
1292
  and the `exit` promise is already settled when the loop returns.
1301
1293
 
1302
- ### Close a byte session cooperatively
1294
+ ### Close a byte duplex cooperatively
1303
1295
 
1304
- The fence that follows ends the session's input, waits out a window of the caller's own, and terminates the child only when that window elapses.
1296
+ The fence that follows ends the duplex's input, waits out a window of the caller's own, and terminates the child only when that window elapses.
1305
1297
 
1306
1298
  ```ts
1307
- import { createSession } from '@orkestrel/process/server'
1299
+ import { createDuplex } from '@orkestrel/process/server'
1308
1300
 
1309
- const session = createSession({
1301
+ const duplex = createDuplex({
1310
1302
  command: { file: 'node', arguments: ['language-server.js', '--stdio'] },
1311
1303
  workspace: process.cwd(),
1312
1304
  })
1313
1305
 
1314
1306
  // …on shutdown: end the input, give the child a window of your own, then terminate if it overruns.
1315
1307
  const window = new Promise<boolean>((resolve) => setTimeout(() => resolve(false), 2_000))
1316
- const flushed = await Promise.race([session.end().then(() => true), window])
1317
- const finished = flushed ? await Promise.race([session.ended.then(() => true), window]) : false
1318
- if (!finished) await session.stop()
1319
- await session.destroy()
1308
+ const flushed = await Promise.race([duplex.end().then(() => true), window])
1309
+ const finished = flushed ? await Promise.race([duplex.ended.then(() => true), window]) : false
1310
+ if (!finished) await duplex.stop()
1311
+ await duplex.destroy()
1320
1312
  ```
1321
1313
 
1322
1314
  The window covers `end` as well as the child's own exit, because the flush `end` awaits carries no
@@ -1429,10 +1421,10 @@ isExited(reporter) // whether the native exit arrived
1429
1421
  after the mark was exceeded receives the retained head, a gap, then the live stream.
1430
1422
  - **Iterate `lines` once and fan out from that loop** — the stream is single-consumer, so another
1431
1423
  iterator takes lines away from the one already iterating rather than repeating them.
1432
- - **Reach for `Session` when the child speaks a protocol** — `lines` frames text, and a
1433
- length-prefixed header, a binary payload, or a NUL byte survives no line framer. A session hands
1424
+ - **Reach for `Duplex` when the child speaks a protocol** — `lines` frames text, and a
1425
+ length-prefixed header, a binary payload, or a NUL byte survives no line framer. A duplex hands
1434
1426
  you the exact bytes and lets you frame them.
1435
- - **Close a session with `end`, then race `ended`, then `stop`** — `end` closes the input and
1427
+ - **Close a duplex with `end`, then race `ended`, then `stop`** — `end` closes the input and
1436
1428
  terminates nothing, `ended` reports the child's own exit, and `stop` is the escalation for a child
1437
1429
  that overruns the window you gave it. Race `ended` rather than `exit`: `exit` waits out `drain`
1438
1430
  for a descendant holding the pipe, so a window raced against it escalates against a child that
@@ -1472,14 +1464,14 @@ Each name on this surface that reads against a house rule is settled here rather
1472
1464
  | `settled` | Derives literally: it is `true` exactly when `exit` has settled. `closed` was refused because it borrows a Node event name into `ProcessInterface`, which is host-independent enough to type `signal` as a `string`. |
1473
1465
  | `terminated` | A latched fact that records an initiated termination. It reports that a termination was initiated, not that one is in flight, because the initiation is what a consumer acts on: a child that was asked to end is not a child to send new work to. |
1474
1466
  | `drain`, `drained` | The option names the window and the result names its outcome, so one concept carries one term across the option and the result. `drain: 0` is an immediate cutoff rather than a disabled bound, unlike the sibling `delivery`, because an unbounded drain is the defect the option prevents. |
1475
- | `Session` | A second entity rather than a byte mode on `Process`, because a mode would falsify `lines`, `truncated`, and `backlog` on half the instances of one class. `Child` collides with the published `ProcessChildInterface` contract, `Channel` is this package's word for the stdin pipe, and `Stream` and `Duplex` borrow Node class names into contracts typed to stay host-independent. |
1476
- | `Supervisor` | The spawn, capture, channel, and termination engine `Process` and `Session` compose. It is barrelled because its constructor takes a `ProcessOptions` and a `SupervisorFace`, and a consumer holds both, so a consumer composing a face of its own reaches the same engine `Process` and `Session` do. |
1467
+ | `Duplex` | A second entity rather than a byte mode on `Process`, because a mode would falsify `lines`, `truncated`, and `backlog` on half the instances of one class. It names the two-way byte channel the entity is: bytes in through `write`, bytes out through `stdout`. `Session` belongs to `@orkestrel/middleware`, `Child` collides with the published `ProcessChildInterface` contract, and `Channel` is this package's word for the stdin pipe. The contract borrows only the word from the Node `Duplex` class and types no host stream. |
1468
+ | `Supervisor` | The spawn, capture, channel, and termination engine `Process` and `Duplex` compose. It is barrelled because its constructor takes a `ProcessOptions` and a `SupervisorFace`, and a consumer holds both, so a consumer composing a face of its own reaches the same engine `Process` and `Duplex` do. |
1477
1469
  | `SupervisorFace` | The callback record a face hands the engine at construction, not a face and not the `Supervisor`'s own face. It carries `Face` rather than the `{Entity}Hooks` form `EmitterHooks` uses, because hooks are optional listeners on an entity that runs without them, while every callback here is a moment the engine must deliver. `{Entity}Interface` was refused because the type declares no behavior of its own: each member holds a function the composing face supplies. It is published because `types.ts` declares it and the server barrel star-exports that module. |
1478
1470
  | `ended`, `exit` | The endings are named apart, because a transport acts on each differently. `ended` is the child's own exit and resolves no value, because `code` and `signal` already carry the facts and a second copy could only drift. `exit` stays on the terminal moment, so `exit`, `settled`, and the `exit` event name one moment on both faces. |
1479
1471
  | `end` | The consistency class of `destroy`: an idempotent lifecycle member returning the barrier every call shares. `close` was refused for borrowing a Node event name, the reason `settled` already records. It resolves `void` because every fact a result could carry is derivable — a later `write` reports `false`, and `ended` reports the exit. |
1480
1472
  | `write`, `send` | Different verbs because they promise different things. `send` frames a line and appends the terminator; `write` puts the exact bytes on the channel and appends nothing. One name over both would hide the terminator at the call site, which is the defect the split prevents. |
1481
1473
  | `stdout`, `stderr` | One face decodes one stream and not the other, because they are read differently. Standard output is a payload a parser consumes, so it stays bytes; standard error is a diagnostic a person reads, so it is decoded, and `evidence` bounds those same bytes. |
1482
- | `backlog`, `writable` | Omitted from `SessionOptions` rather than falsified on it. A session retains no lines, so no backlog bound applies; its channel is open until `end` closes it, so no switch selects whether one exists. An option that could only ever hold one value is a member a consumer must learn and can never use. |
1474
+ | `backlog`, `writable` | Omitted from `DuplexOptions` rather than falsified on it. A duplex retains no lines, so no backlog bound applies; its channel is open until `end` closes it, so no switch selects whether one exists. An option that could only ever hold one value is a member a consumer must learn and can never use. |
1483
1475
 
1484
1476
  ## Tests
1485
1477
 
@@ -1552,7 +1544,7 @@ The pure decision rows do not prove Windows end to end. They prove the decisions
1552
1544
  and longer than a descendant release, `stop` alone reaching the moment with no `destroy` call, the
1553
1545
  latched `terminated` refusing a `send`, the released abort listener, the spawn-fault path, and the
1554
1546
  `drain` refusals at each end of its range.
1555
- - [`tests/src/server/processes/Session.test.ts`](../tests/src/server/processes/Session.test.ts) —
1547
+ - [`tests/src/server/processes/Duplex.test.ts`](../tests/src/server/processes/Duplex.test.ts) —
1556
1548
  the byte face: a binary payload carrying NUL bytes, an invalid UTF-8 sequence, a lone carriage return, and an embedded line
1557
1549
  feed arriving byte-identical in one event, a half-megabyte stream reassembled byte for byte, and
1558
1550
  each emitted chunk read as a plain owned array against a raw spawn of the same child as the