@orkestrel/scaffold 0.0.119 → 0.0.121
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.
- package/dist/bin/main.js +19 -19
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
- package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +52 -51
- package/dist/host/claude/rules/tests.md +2 -2
- package/dist/host/claude/rules/typescript.md +2 -3
- package/dist/host/guides/abort.md +0 -4
- package/dist/host/guides/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/console.md +4 -30
- package/dist/host/guides/contract.md +23 -44
- package/dist/host/guides/csv.md +86 -93
- package/dist/host/guides/database.md +0 -4
- package/dist/host/guides/emitter.md +0 -2
- package/dist/host/guides/form.md +26 -47
- package/dist/host/guides/guide.md +0 -1
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +148 -144
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- package/dist/host/guides/sqlite.md +0 -4
- package/dist/host/guides/sse.md +6 -10
- package/dist/host/guides/table.md +481 -493
- package/dist/host/guides/template.md +0 -4
- package/dist/host/guides/terminal.md +0 -26
- package/dist/host/guides/test.md +46 -66
- package/dist/host/guides/timeout.md +0 -6
- package/dist/host/guides/tool.md +2 -6
- package/dist/host/guides/toolbox.md +0 -10
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +64 -909
- package/dist/src/core/index.cjs +128 -181
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +213 -213
- package/dist/src/core/index.d.ts +213 -213
- package/dist/src/core/index.js +117 -170
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +35 -34
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +62 -58
- package/dist/src/server/index.d.ts +62 -58
- package/dist/src/server/index.js +36 -35
- package/dist/src/server/index.js.map +1 -1
- package/package.json +13 -13
|
@@ -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 `
|
|
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. `
|
|
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 `
|
|
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
|
-
| `
|
|
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
|
-
| `
|
|
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
|
-
| `
|
|
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
|
-
| `
|
|
209
|
-
| `
|
|
210
|
-
| `
|
|
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 `
|
|
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
|
|
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, `
|
|
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
|
-
#### `
|
|
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 `
|
|
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
|
|
371
|
+
### Byte duplexes
|
|
380
372
|
|
|
381
|
-
`
|
|
382
|
-
host delivers becomes one `stdout` event carrying an owned `Uint8Array` — the
|
|
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. `
|
|
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
|
-
`
|
|
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
|
-
`
|
|
399
|
-
|
|
400
|
-
| Option | Type
|
|
401
|
-
| ----------- |
|
|
402
|
-
| `command` | `ProcessCommand`
|
|
403
|
-
| `workspace` | `string`
|
|
404
|
-
| `grace` | `number`
|
|
405
|
-
| `drain` | `number`
|
|
406
|
-
| `evidence` | `number`
|
|
407
|
-
| `delivery` | `number`
|
|
408
|
-
| `signal` | `AbortSignal`
|
|
409
|
-
| `on` | `EmitterHooks<
|
|
410
|
-
| `error` | `EmitterErrorHandler`
|
|
411
|
-
|
|
412
|
-
A
|
|
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 {
|
|
417
|
+
import { createDuplex } from '@orkestrel/process/server'
|
|
426
418
|
|
|
427
|
-
const
|
|
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
|
-
|
|
425
|
+
duplex.emitter.on('stdout', (chunk) => received.push(chunk))
|
|
434
426
|
|
|
435
|
-
await
|
|
436
|
-
await
|
|
437
|
-
await
|
|
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
|
|
432
|
+
const exit = await duplex.exit
|
|
441
433
|
exit.code // 0
|
|
442
|
-
|
|
443
|
-
await
|
|
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
|
-
`
|
|
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 `
|
|
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
|
|
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 `
|
|
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
|
|
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
|
|
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
|
-
`
|
|
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 `
|
|
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.
|
|
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`, `
|
|
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
|
-
| `
|
|
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 `
|
|
1250
|
-
raw bytes the host delivered. The `stdout` payload is the
|
|
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
|
|
1294
|
+
### Close a byte duplex cooperatively
|
|
1303
1295
|
|
|
1304
|
-
The fence that follows ends the
|
|
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 {
|
|
1299
|
+
import { createDuplex } from '@orkestrel/process/server'
|
|
1308
1300
|
|
|
1309
|
-
const
|
|
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([
|
|
1317
|
-
const finished = flushed ? await Promise.race([
|
|
1318
|
-
if (!finished) await
|
|
1319
|
-
await
|
|
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 `
|
|
1433
|
-
length-prefixed header, a binary payload, or a NUL byte survives no line framer. A
|
|
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
|
|
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
|
-
| `
|
|
1476
|
-
| `Supervisor` | The spawn, capture, channel, and termination engine `Process` and `
|
|
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 `
|
|
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/
|
|
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
|
|
@@ -123,8 +123,6 @@ manager.destroy()
|
|
|
123
123
|
|
|
124
124
|
### Types
|
|
125
125
|
|
|
126
|
-
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 `\|`.
|
|
127
|
-
|
|
128
126
|
| Name | Kind | Signature | Summary |
|
|
129
127
|
| ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
130
128
|
| `Decision` | type | `'approved' \| 'denied' \| 'submitted'` | Identifies a final authority outcome, derived from global eligibility. |
|
|
@@ -143,7 +141,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
143
141
|
| `ProgramDefinition` | interface | `{ id, name, description?, qualification, rating?, notices?, authority?, aggregate?, metadata? }` | Describes a pure authored program definition. |
|
|
144
142
|
| `ProgramResult` | interface | `{ id, name, eligibility, status, decision?, qualification, rating?, determinations, success, trace, errors }` | Describes one subject's complete program outcome. |
|
|
145
143
|
| `AggregateResult` | interface | `{ id, name, subjects, determinations, groups, tallies, count, sums, success, trace, errors }` | Describes a batch program outcome across every subject. |
|
|
146
|
-
| `ProgramValidationResult` | interface | `{ valid, errors, warnings }` | Describes semantic definition validation. |
|
|
147
144
|
| `ProgramEventMap` | type | `{ readonly qualify: readonly [result: QualificationResult]; readonly rate: readonly [result: RatingResult]; readonly determine: readonly [result: Determination]; readonly decide: readonly [decision: Decision, result: ProgramResult]; readonly execute: readonly [result: ProgramResult]; readonly aggregate: readonly [result: AggregateResult]; readonly destroy: readonly []; }` | Describes the push observation surface of a `ProgramInterface`. |
|
|
148
145
|
| `ProgramOptions` | interface | `{ qualifier?, rater?, engine?, validate?, labels?, on?, error? }` | Describes the options for `createProgram` / the `Program` constructor. |
|
|
149
146
|
| `ProgramInterface` | interface | `{ id, name, definition, emitter, execute(), validate(), destroy() }` | Defines one compiled program that composes one qualifier and one rater over a shared reason engine. |
|
|
@@ -155,13 +152,12 @@ Every public data member is `readonly`, every optional key is omitted rather tha
|
|
|
155
152
|
`undefined`, and each name is single-word within its entity. Qualifier
|
|
156
153
|
supplies `Eligibility`, `Premise`, `QualificationDefinition`, and `QualificationResult`;
|
|
157
154
|
rater supplies `RatingDefinition` and `RatingResult`; reason supplies
|
|
158
|
-
`LogicalDefinition`, `Subject`,
|
|
155
|
+
`LogicalDefinition`, `Subject`, the engine, and the `ReasonValidationResult` type
|
|
156
|
+
`validate` returns; contract supplies `FieldPath` and
|
|
159
157
|
`JSONValue`; the emitter supplies the observation types.
|
|
160
158
|
|
|
161
159
|
### Constants
|
|
162
160
|
|
|
163
|
-
A `Shape` cell holds the constant's declared type.
|
|
164
|
-
|
|
165
161
|
| Name | Kind | Signature | Summary |
|
|
166
162
|
| -------------------------- | ----- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
167
163
|
| `DEFAULT_PROGRAM_VALIDATE` | const | `true` | Names the default definition validation policy, `true`, for `createProgram` / `ProgramManager.add`. |
|
|
@@ -213,27 +209,24 @@ except the string-dictionary leaves (`sums`, `scopes`), which certify own member
|
|
|
213
209
|
only — a value carrying them on a prototype is admitted unchecked.
|
|
214
210
|
Holding `isProgramResult` therefore also holds qualifier's published
|
|
215
211
|
`isQualificationResult` closure and rater's published `isRatingResult` closure.
|
|
216
|
-
`
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
|
222
|
-
|
|
|
223
|
-
| `
|
|
224
|
-
| `
|
|
225
|
-
| `
|
|
226
|
-
| `
|
|
227
|
-
| `
|
|
228
|
-
| `
|
|
229
|
-
| `
|
|
230
|
-
| `
|
|
231
|
-
| `
|
|
232
|
-
| `
|
|
233
|
-
| `
|
|
234
|
-
| `isProgramResult` | const | `Guard<ProgramResult>` | Determines whether a value is an open `ProgramResult`. |
|
|
235
|
-
| `isAggregateResult` | const | `Guard<AggregateResult>` | Determines whether a value is an open `AggregateResult`. |
|
|
236
|
-
| `isProgramValidationResult` | const | `Guard<ProgramValidationResult>` | Determines whether a value is an open `ProgramValidationResult`. |
|
|
212
|
+
A `validate` result belongs to `@orkestrel/reason`, so narrow one with the
|
|
213
|
+
`isReasonValidationResult` guard from that package.
|
|
214
|
+
|
|
215
|
+
| Name | Kind | Signature | Summary |
|
|
216
|
+
| ----------------------- | -------- | --------------------------------------------------------------- | -------------------------------------------------------------------- |
|
|
217
|
+
| `isDecision` | const | `Guard<Decision>` | Determines whether a value is a `Decision` literal. |
|
|
218
|
+
| `isStatus` | const | `Guard<Status>` | Determines whether a value is a `Status` literal. |
|
|
219
|
+
| `isProgramEffect` | const | `Guard<ProgramEffect>` | Determines whether a value is a `ProgramEffect` literal. |
|
|
220
|
+
| `isNotice` | function | `(value: unknown) => value is Notice` | Determines whether a value is an exact `Notice` record. |
|
|
221
|
+
| `isAggregateDefinition` | function | `(value: unknown) => value is AggregateDefinition` | Determines whether a value is an exact `AggregateDefinition` record. |
|
|
222
|
+
| `isProgramDefinition` | function | `(value: unknown) => value is ProgramDefinition` | Determines whether a value is an exact `ProgramDefinition` record. |
|
|
223
|
+
| `isProgramSums` | function | `(value: unknown) => value is Readonly<Record<string, number>>` | Determines whether a value is an open program sums record. |
|
|
224
|
+
| `isDetermination` | const | `Guard<Determination>` | Determines whether a value is an open result-side `Determination`. |
|
|
225
|
+
| `isAggregateGroup` | const | `Guard<AggregateGroup>` | Determines whether a value is an open result-side `AggregateGroup`. |
|
|
226
|
+
| `isTally` | const | `Guard<Tally>` | Determines whether a value is an open result-side `Tally`. |
|
|
227
|
+
| `isTallies` | function | `(value: unknown) => value is Readonly<Record<Status, Tally>>` | Determines whether a value is a total open status-tally record. |
|
|
228
|
+
| `isProgramResult` | const | `Guard<ProgramResult>` | Determines whether a value is an open `ProgramResult`. |
|
|
229
|
+
| `isAggregateResult` | const | `Guard<AggregateResult>` | Determines whether a value is an open `AggregateResult`. |
|
|
237
230
|
|
|
238
231
|
`isProgramSums` checks every own string-named member, including non-enumerable
|
|
239
232
|
members, as a JavaScript `number`; it ignores inherited and symbol-named members.
|
|
@@ -249,7 +242,6 @@ import {
|
|
|
249
242
|
isNotice,
|
|
250
243
|
isProgramDefinition,
|
|
251
244
|
isProgramResult,
|
|
252
|
-
isProgramValidationResult,
|
|
253
245
|
isStatus,
|
|
254
246
|
} from '@orkestrel/program'
|
|
255
247
|
|
|
@@ -261,7 +253,6 @@ isProgramDefinition(definition) // true
|
|
|
261
253
|
isDetermination({ id: 'audit', effect: 'notice', applied: true, premises: [] }) // true
|
|
262
254
|
isProgramResult(program.execute(subject)) // true
|
|
263
255
|
isAggregateResult(program.execute(subjects)) // true
|
|
264
|
-
isProgramValidationResult(program.validate()) // true
|
|
265
256
|
```
|
|
266
257
|
|
|
267
258
|
`isProgramDefinition` establishes exact shape only. `Program.validate` additionally
|
|
@@ -288,10 +279,10 @@ never destroyed — it holds no state to tear down) purely to drive that reuse.
|
|
|
288
279
|
| `buildOutcomeProjection` | function | `(result: ProgramResult) => Readonly<Record<string, unknown>>` | Builds the private authority outcome projection from an assembled program result. |
|
|
289
280
|
| `buildQualificationSubject` | function | `(subject: Subject, aggregate?: AggregateProjection) => Subject` | Adds optional aggregate context to a private subject copy for qualification. |
|
|
290
281
|
| `findMissingScopes` | function | `(definition: ProgramDefinition) => readonly string[]` | Returns authored scopes (qualification ruling scopes or notice scopes) that name no rating line on the program. |
|
|
291
|
-
| `
|
|
282
|
+
| `hasProgramKey` | function | `(subject: Readonly<Record<string, unknown>>) => boolean` | Determines whether a caller subject already carries a reserved program key. |
|
|
292
283
|
| `assertProgramSubject` | function | `(subject: unknown) => asserts subject is Subject` | Asserts a value is a valid program `Subject`, narrowing it in place. |
|
|
293
284
|
| `assertProgramDefinition` | function | `(definition: ProgramDefinition) => void` | Asserts a program definition's always-on construction invariants — missing scope references and duplicate rating-line or notice ids. |
|
|
294
|
-
| `validateProgramDefinition` | function | `(definition: ProgramDefinition, qualifier: QualifierInterface, engine: ReasonInterface) =>
|
|
285
|
+
| `validateProgramDefinition` | function | `(definition: ProgramDefinition, qualifier: QualifierInterface, engine: ReasonInterface) => ReasonValidationResult` | Validates a program definition's shape, references, and nested definitions. |
|
|
295
286
|
| `formatGroupKey` | function | `(subject: Subject, partition: FieldPath) => string` | Coerces a subject's partition-key field to its group-key string. |
|
|
296
287
|
| `sumFields` | function | `(sums: Readonly<Record<string, number>>, subject: Subject, fields: readonly FieldPath[]) => Readonly<Record<string, number>>` | Folds one subject's finite aggregate field values into a sums record. |
|
|
297
288
|
| `aggregateSums` | function | `(subjects: readonly Subject[], fields: readonly FieldPath[]) => Readonly<Record<string, number>>` | Sums aggregate fields across a batch of subjects. |
|
|
@@ -315,12 +306,12 @@ import {
|
|
|
315
306
|
assertProgramDefinition,
|
|
316
307
|
assertProgramSubject,
|
|
317
308
|
decideEligibility,
|
|
318
|
-
|
|
309
|
+
hasProgramKey,
|
|
319
310
|
selectProgramLines,
|
|
320
311
|
} from '@orkestrel/program'
|
|
321
312
|
|
|
322
|
-
|
|
323
|
-
|
|
313
|
+
hasProgramKey({ id: 'r1' }) // false
|
|
314
|
+
hasProgramKey({ id: 'r1', aggregate: {} }) // true
|
|
324
315
|
assertProgramSubject({ id: 'r1' }) // narrows to Subject; throws ProgramError('RESERVED') on a reserved key
|
|
325
316
|
assertProgramDefinition(definition) // throws ProgramError('MISSING' | 'DUPLICATE') at construction, regardless of options.validate
|
|
326
317
|
selectProgramLines(lines, { wind: 'ineligible' }) // every line except the 'wind' line
|
|
@@ -415,7 +406,7 @@ than qualification or rating alone.
|
|
|
415
406
|
| Method | Returns | Summary |
|
|
416
407
|
| ---------- | ------------------------------------ | ---------------------------------------------------------------- |
|
|
417
408
|
| `execute` | `AggregateResult` or `ProgramResult` | Executes a subject list as one aggregate-aware batch. |
|
|
418
|
-
| `validate` | `
|
|
409
|
+
| `validate` | `ReasonValidationResult` | Validates this program's definition and every nested definition. |
|
|
419
410
|
| `destroy` | `void` | Destroys this program, idempotently. |
|
|
420
411
|
|
|
421
412
|
```ts
|