@orkestrel/scaffold 0.0.113 → 0.0.115
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/agents/skills/orkestrel-publish/scripts/wave.js +83 -16
- package/dist/bin/main.js +71 -23
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +5 -3
- package/dist/host/agents/platforms/windows.md +1 -0
- package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
- package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +7 -7
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +31 -11
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +150 -49
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/astra.md +2 -2
- package/dist/host/claude/agents/builder.md +4 -4
- package/dist/host/claude/agents/opus.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +57 -59
- package/dist/host/claude/agents/planner.md +8 -2
- package/dist/host/claude/rules/campaign.md +2 -1
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/tests.md +13 -8
- package/dist/host/claude/rules/workspace.md +28 -28
- package/dist/host/claude/rules/writing.md +1 -0
- package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +8 -5
- package/dist/host/codex/agents/astra.toml +4 -5
- package/dist/host/codex/agents/builder.toml +5 -5
- package/dist/host/codex/agents/opus.toml +3 -4
- package/dist/host/codex/agents/orkestrel.toml +2 -1
- package/dist/host/codex/agents/planner.toml +8 -5
- package/dist/host/codex/agents/reviewer.toml +5 -4
- package/dist/host/guides/agent.md +13 -13
- package/dist/host/guides/brief.md +4 -0
- package/dist/host/guides/browser.md +162 -44
- package/dist/host/guides/budget.md +1 -1
- package/dist/host/guides/capture.md +4 -0
- package/dist/host/guides/console.md +13 -0
- package/dist/host/guides/contract.md +38 -3
- package/dist/host/guides/csv.md +5 -0
- package/dist/host/guides/database.md +58 -8
- package/dist/host/guides/form.md +17 -0
- package/dist/host/guides/guide.md +36 -33
- package/dist/host/guides/html.md +72 -44
- package/dist/host/guides/indexeddb.md +4 -0
- package/dist/host/guides/lsp.md +49 -8
- package/dist/host/guides/markdown.md +146 -1
- package/dist/host/guides/mcp.md +117 -22
- package/dist/host/guides/middleware.md +194 -26
- package/dist/host/guides/msg.md +9 -5
- package/dist/host/guides/pool.md +8 -1
- package/dist/host/guides/probe.md +13 -1
- package/dist/host/guides/process.md +102 -90
- package/dist/host/guides/program.md +4 -0
- package/dist/host/guides/qualifier.md +4 -0
- package/dist/host/guides/rater.md +4 -0
- package/dist/host/guides/reason.md +6 -4
- package/dist/host/guides/relation.md +4 -0
- package/dist/host/guides/scaffold.md +32 -14
- package/dist/host/guides/server.md +29 -13
- package/dist/host/guides/sqlite.md +6 -0
- package/dist/host/guides/sse.md +6 -0
- package/dist/host/guides/study.md +473 -473
- package/dist/host/guides/table.md +3 -0
- package/dist/host/guides/template.md +3 -0
- package/dist/host/guides/test.md +38 -20
- package/dist/host/guides/tool.md +3 -0
- package/dist/host/guides/toolbox.md +21 -0
- package/dist/host/guides/websocket.md +3 -1
- package/dist/host/guides/workflow.md +103 -11
- package/dist/host/guides/workspace.md +4 -0
- package/dist/host/manifest.json +84 -84
- package/dist/host/tests/config.test.ts +7 -13
- package/dist/src/core/index.cjs +20 -28
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +7 -7
- package/dist/src/core/index.d.ts +7 -7
- package/dist/src/core/index.js +20 -28
- package/dist/src/core/index.js.map +1 -1
- package/package.json +12 -12
package/dist/host/guides/msg.md
CHANGED
|
@@ -112,15 +112,15 @@ A `Shape` cell holds the constant's declared type.
|
|
|
112
112
|
| `MSG_PREFIX_RECIPIENT` | const | `string` | Holds the storage name prefix for a recipient entry (`'__recip_version1.0'`). |
|
|
113
113
|
| `MSG_PREFIX_DOCUMENT` | const | `string` | Holds the stream name prefix for a MAPI property document (substg) entry (`'__substg1.'`). |
|
|
114
114
|
| `MSG_PREFIX_NAMEID` | const | `string` | Holds the storage name of the named-property mapping table (`'__nameid_version1.0'`). |
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
115
|
+
| `MSG_FIELD_NAMES` | const | `Readonly<Record<string, string>>` | Maps a MAPI property tag's hex to its short field name, for example `subject`. |
|
|
116
|
+
| `MSG_FIELD_FULL_NAMES` | const | `Readonly<Record<string, string>>` | Maps a compound tag's full 8-character hex to its fully-qualified field name. |
|
|
117
|
+
| `MSG_FIELD_TYPES` | const | `Readonly<Record<string, MSGFieldType>>` | Maps a MAPI property type tag's hex to its `MSGFieldType` decode tag. |
|
|
118
118
|
| `MSG_FIELD_CLASS_ATTACHMENT_DATA` | const | `string` | Identifies the MAPI tag naming an attachment's binary data stream (`'3701'`). |
|
|
119
119
|
| `MSG_FIELD_DIR_TYPE_INNER_MSG` | const | `string` | Names the MAPI type tag identifying an embedded `.msg` attachment storage (`'000d'`). |
|
|
120
120
|
| `MSG_MAPI_RECIPIENT_TO` | const | `number` | Names the MAPI recipient-type value mapping to `MSGRecipientRole` `'to'` (`1`). |
|
|
121
121
|
| `MSG_MAPI_RECIPIENT_CC` | const | `number` | Names the MAPI recipient-type value mapping to `MSGRecipientRole` `'cc'` (`2`). |
|
|
122
122
|
| `MSG_MAPI_RECIPIENT_BCC` | const | `number` | Names the MAPI recipient-type value mapping to `MSGRecipientRole` `'bcc'` (`3`). |
|
|
123
|
-
| `
|
|
123
|
+
| `MSG_PIDLIDS` | const | `Readonly<Record<string, Readonly<Record<number, string>>>>` | Maps a named-property set GUID to its long-ID-to-field-name table. |
|
|
124
124
|
| `MSG_BURNER_INTS_PER_SECTOR` | const | `number` | Holds the number of 32-bit FAT and DIFAT entries one standard sector carries (128). |
|
|
125
125
|
| `MSG_BURNER_DIFAT_HEADER_SLOTS` | const | `number` | Caps the DIFAT entries stored directly in the CFB header (109). |
|
|
126
126
|
| `MSG_BURNER_FAT_SECTOR_MARKER` | const | `number` | Marks a sector as itself part of the FAT (-3). |
|
|
@@ -157,6 +157,10 @@ try {
|
|
|
157
157
|
}
|
|
158
158
|
```
|
|
159
159
|
|
|
160
|
+
The constructor adds an own, non-enumerable, non-writable symbol brand whose value is the error itself.
|
|
161
|
+
The guard accepts errors from another installed copy and subclasses without requiring a particular name.
|
|
162
|
+
It refuses transparent proxies, unbranded errors, and plain objects carrying the brand.
|
|
163
|
+
|
|
160
164
|
### Helpers
|
|
161
165
|
|
|
162
166
|
Pure, mostly-total leaves from [`helpers.ts`](../src/core/helpers.ts) — the `Result` constructors/guards, the CFB byte/string/UUID readers and magic check `MSG.ts` composes, the format sniffer, and the MIME/text codecs `parsers.ts` and `shapers.ts` compose.
|
|
@@ -299,7 +303,7 @@ parseMIMEPart('Subject: Hi\n\nBody text') // MIMEPart — { headers, body: 'Body
|
|
|
299
303
|
|
|
300
304
|
### Validators
|
|
301
305
|
|
|
302
|
-
The from-unknown guards from [`validators.ts`](../src/core/validators.ts). Each validates an arbitrary `unknown` value from scratch, against the `EmailChain`, `EmailMessage`, or `EmailAttachment` shape, or the `EmailFormat` union, using `isRecord` from `@orkestrel/contract`. `isMSGError`
|
|
306
|
+
The from-unknown guards from [`validators.ts`](../src/core/validators.ts). Each validates an arbitrary `unknown` value from scratch, against the `EmailChain`, `EmailMessage`, or `EmailAttachment` shape, or the `EmailFormat` union, using `isRecord` from `@orkestrel/contract`. `isMSGError` validates the global Error instance, its package brand, its code, and its context.
|
|
303
307
|
|
|
304
308
|
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
305
309
|
|
package/dist/host/guides/pool.md
CHANGED
|
@@ -56,7 +56,7 @@ In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
|
56
56
|
|
|
57
57
|
| API | Kind | Shape | Summary |
|
|
58
58
|
| -------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
59
|
-
| `isPoolError` | function | `PoolError` | Tests whether an unknown value is a `PoolError
|
|
59
|
+
| `isPoolError` | function | `PoolError` | Tests whether an unknown value is a branded `PoolError` with declared code and context. |
|
|
60
60
|
| `isPoolLimit` | function | `number` | Tests whether a value is a positive safe integer for a pool record or lease limit. |
|
|
61
61
|
| `isPoolSignal` | function | `AbortSignal` | Tests whether a value is a native `AbortSignal` for the acquire boundary, returning `false` for hostile proxies. |
|
|
62
62
|
|
|
@@ -306,6 +306,13 @@ The original thrown value is retained as `cause`; aggregate cleanup values are a
|
|
|
306
306
|
`context.failures`. Message construction and `isPoolError` avoid unsafe string coercion and
|
|
307
307
|
return safely for hostile proxies.
|
|
308
308
|
|
|
309
|
+
Recognition requires an own identity brand at `Symbol.for('@orkestrel/pool.PoolError')`,
|
|
310
|
+
the global `Error` base with a subclass prototype, a declared code, and valid optional context.
|
|
311
|
+
The brand is non-enumerable and non-writable. Guards from separate installed copies and module
|
|
312
|
+
formats recognize each other's errors. Subclasses pass without reading `name`; transparent
|
|
313
|
+
proxies, unbranded look-alikes, and plain objects carrying only the brand fail. Errors created
|
|
314
|
+
by older releases without this brand no longer pass the guard.
|
|
315
|
+
|
|
309
316
|
## Observing
|
|
310
317
|
|
|
311
318
|
The composed `Emitter` isolates listener throws through the optional `error` handler and
|
|
@@ -253,7 +253,7 @@ Pure leaves and workspace readers, from [`helpers.ts`](../src/server/helpers.ts)
|
|
|
253
253
|
| `inferDocumentLanguage` | function | `(path: string) => string` | Selects the Language Server Protocol language identifier for a source path. |
|
|
254
254
|
| `buildRevisionPath` | function | `(workspace: string, path: string, revision: string) => string` | Builds the fresh sibling path a revision's file is written at, preserving the test's resolution directory. |
|
|
255
255
|
| `matchesWorkspaceModule` | function | `(path: string) => boolean` | Reports whether a path is a workspace module Vitest can cache. |
|
|
256
|
-
| `matchesLiveProcess` | function | `(id: number) => boolean` | Reports whether
|
|
256
|
+
| `matchesLiveProcess` | function | `(id: number) => boolean` | Reports whether a file's owning host is running or cannot be judged. |
|
|
257
257
|
| `collectWorkspaceFiles` | function | `(workspace: string) => readonly string[]` | Collects every regular file a target workspace holds, skipping the trees no inspection reads. |
|
|
258
258
|
| `filterUniqueIssues` | function | `(issues: readonly Issue[]) => readonly Issue[]` | Filters one issue list to the distinct issues it carries, in the order they arrived. |
|
|
259
259
|
| `describeUnknown` | function | `(value: unknown) => string` | Normalizes a caught or foreign error into readable text. |
|
|
@@ -306,6 +306,11 @@ The stage implements the preceding `StageInterface` contract.
|
|
|
306
306
|
|
|
307
307
|
#### `TypeStageInterface`
|
|
308
308
|
|
|
309
|
+
`destroy()` abandons inspections and awaits Windows compiler tree termination before removing the
|
|
310
|
+
mirror. Each termination utility has the existing `PROBE_DEADLINE` budget of 30,000 ms; the attempts
|
|
311
|
+
run concurrently. POSIX teardown retains `SIGTERM`. Warming settles before mirror removal on either
|
|
312
|
+
host. The termination attempt remains best effort if the host utility fails.
|
|
313
|
+
|
|
309
314
|
| Method | Returns | Summary |
|
|
310
315
|
| --------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- |
|
|
311
316
|
| `start` | `Promise<void>` | Begins the warm or joins the warm already begun. |
|
|
@@ -504,6 +509,9 @@ Measured on 2026-08-20: `computeDigest(workspace, cyclic)` raises
|
|
|
504
509
|
`isProbeError` reads a global brand rather than the constructor, so it admits a failure raised by a
|
|
505
510
|
second copy of this package — a duplicate installation, or the ESM and CommonJS builds loaded
|
|
506
511
|
together — where `instanceof` refuses a failure the other copy raised.
|
|
512
|
+
The own brand holds the error itself. Recognition requires an `Error` with a non-base prototype,
|
|
513
|
+
a declared origin and code, and context members of their declared types. A subclass may replace
|
|
514
|
+
`name`. A transparent proxy, a plain branded object, and a lookalike without the brand are refused.
|
|
507
515
|
|
|
508
516
|
## Prerequisites
|
|
509
517
|
|
|
@@ -952,6 +960,10 @@ the stage, and the mirror is this stage's own tree: where the workspace holds a
|
|
|
952
960
|
draft declares a directory under, the mirrored copy of that file is removed so the draft can be
|
|
953
961
|
written, and the next refresh restores it.
|
|
954
962
|
|
|
963
|
+
The stale-resource sweep retains an owner whose liveness cannot be judged. `matchesLiveProcess`
|
|
964
|
+
keeps its invalid-identity guard and uses process 0.0.16's `inspectProcess` for the host probe. An
|
|
965
|
+
indeterminate answer preserves the resource; only confirmed absence permits the sweep to remove it.
|
|
966
|
+
|
|
955
967
|
**A read is contained lexically only, and that is the reach to plan for.** The mirror carries
|
|
956
968
|
regular files inside the workspace only: a symbolic link is not carried, so a file reached only
|
|
957
969
|
through one is absent from the mirror and the compiler reports what its absence causes, as a
|
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
`evidence` beside a live `stderr` event, publishes a typed lifecycle emitter, and ends every
|
|
10
10
|
observation channel at one terminal moment through a bounded termination. `Session` publishes one
|
|
11
11
|
owned `Uint8Array` per stdout chunk instead, with an `end` that closes stdin without terminating
|
|
12
|
-
anything and the child's own `
|
|
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
|
|
14
14
|
is unreferenced, so nothing in this process observes its outcome. `ProcessManager` launches and
|
|
15
15
|
stops its children by id and reports each moment through its own emitter. An argument a batch
|
|
@@ -141,14 +141,22 @@ The byte-bounding and result-assembly building blocks, from `@orkestrel/process/
|
|
|
141
141
|
The signalling and confirmation building blocks a bounded stop composes, from
|
|
142
142
|
`@orkestrel/process/server`.
|
|
143
143
|
|
|
144
|
-
| API
|
|
145
|
-
|
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
| `
|
|
150
|
-
| `
|
|
151
|
-
| `
|
|
144
|
+
| API | Kind | Summary |
|
|
145
|
+
| ---------------- | -------- | ----------------------------------------------------------------------------------- |
|
|
146
|
+
| `inspectProcess` | function | Reports whether a process or POSIX process group still exists. |
|
|
147
|
+
| `isExited` | function | Checks whether a child process has reached its native exit. |
|
|
148
|
+
| `killProcess` | function | Signals one owned child process, or its detached process group on a POSIX host. |
|
|
149
|
+
| `killTree` | function | Kills one Windows process tree through `taskkill`. |
|
|
150
|
+
| `waitForExit` | function | Waits for one child process's native exit, bounded by a deadline. |
|
|
151
|
+
| `waitForClose` | function | Waits for one child process's streams to close, bounded by a deadline. |
|
|
152
|
+
| `stopChild` | function | Terminates one child process tree and reports whether its native exit was observed. |
|
|
153
|
+
|
|
154
|
+
`inspectProcess` returns `true` while the process or POSIX process group exists, including
|
|
155
|
+
when the host refuses the probe with `EPERM`. It returns `false` after the target is gone
|
|
156
|
+
(`ESRCH`), and `undefined` for any other host failure. It throws a `ProcessError` coded
|
|
157
|
+
`invalid` for a value that is not a safe integer, zero, or minus one. Windows accepts only
|
|
158
|
+
positive process ids and refuses every negative id before the host call. On POSIX, a negative
|
|
159
|
+
id other than minus one probes the process group identified by its magnitude.
|
|
152
160
|
|
|
153
161
|
### Validators
|
|
154
162
|
|
|
@@ -188,29 +196,29 @@ The contracts and options, all from `@orkestrel/process`.
|
|
|
188
196
|
|
|
189
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 `\|`.
|
|
190
198
|
|
|
191
|
-
| API | Kind | Shape
|
|
192
|
-
| ------------------------- | --------- |
|
|
193
|
-
| `ProcessCommand` | interface | `{ file, arguments, environment?, input?, isolated? }`
|
|
194
|
-
| `ProcessExit` | interface | `{ code, signal, drained }`
|
|
195
|
-
| `SpawnInput` | interface | `{ file, arguments, verbatim }`
|
|
196
|
-
| `ExecutableOptions` | interface | `{ workspace?, environment? }`
|
|
197
|
-
| `ProcessEventMap` | type | `{ stderr, error, exit }`
|
|
198
|
-
| `ProcessOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, backlog?, delivery?, writable?, signal? }`
|
|
199
|
-
| `ProcessInterface` | interface | `{ pid, code, signal, emitter, lines, evidence, truncated, settled,
|
|
200
|
-
| `SessionEventMap` | type | `{ stdout, stderr, error, exit }`
|
|
201
|
-
| `SessionOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, delivery?, signal? }`
|
|
202
|
-
| `SessionInterface` | interface | `{ pid, code, signal, emitter, evidence, settled,
|
|
203
|
-
| `ExecuteResult` | interface | `{ command, stdout, stderr, code, signal, failed, expired, aborted, truncated }`
|
|
204
|
-
| `ExecuteInput` | interface | `{ command, stdout, stderr, code, signal, expired, aborted, truncated, limit, cause? }`
|
|
205
|
-
| `ExecuteOptions` | interface | `{ workspace?, environment?, input?, timeout?, grace?, signal?, strict?, limit? }`
|
|
206
|
-
| `ExecuteSyncOptions` | interface | `{ workspace?, environment?, input?, timeout?, strict?, limit? }`
|
|
207
|
-
| `DetachOptions` | interface | `{ workspace? }`
|
|
208
|
-
| `ProcessManagerEventMap` | type | `{ launch, exit }`
|
|
209
|
-
| `ProcessManagerOptions` | interface | `{ on?, error? }`
|
|
210
|
-
| `ProcessManagerInterface` | interface | `{ emitter, count } plus process, processes, launch, stop, destroy`
|
|
211
|
-
| `ProcessErrorCode` | type | `(typeof PROCESS_ERROR_CODES)[number]`
|
|
212
|
-
| `ProcessErrorContext` | interface | `{ id?, command?, code?, signal?, value? }`
|
|
213
|
-
| `ProcessErrorOptions` | interface | `{ code, context?, cause?, result? }`
|
|
199
|
+
| API | Kind | Shape | Summary |
|
|
200
|
+
| ------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
201
|
+
| `ProcessCommand` | interface | `{ file, arguments, environment?, input?, isolated? }` | Represents one spawnable command: the executable, its argument vector, and optional environment overrides and initial standard input. |
|
|
202
|
+
| `ProcessExit` | interface | `{ code, signal, drained }` | Represents the observed terminal state of a child process: its exit code or the signal that ended it, and how its observation ended. |
|
|
203
|
+
| `SpawnInput` | interface | `{ file, arguments, verbatim }` | Represents the resolved spawn form of one command: the executable to launch, the argument vector to pass, and whether the host receives that vector verbatim. |
|
|
204
|
+
| `ExecutableOptions` | interface | `{ workspace?, environment? }` | Supplies the lookup inputs for resolving a command file to an executable path. |
|
|
205
|
+
| `ProcessEventMap` | type | `{ stderr, error, exit }` | 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
|
+
| `ProcessOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, backlog?, delivery?, writable?, signal? }` | Configures one supervised child process. |
|
|
207
|
+
| `ProcessInterface` | interface | `{ pid, code, signal, emitter, lines, evidence, truncated, settled, terminated, exit } plus send, stop, destroy` | Represents one supervised child process with framed output, a bounded backlog, and bounded termination. |
|
|
208
|
+
| `SessionEventMap` | type | `{ stdout, stderr, error, exit }` | 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 } plus write, end, stop, destroy` | Represents one supervised child process read as raw bytes, with an open standard-input channel and bounded termination. |
|
|
211
|
+
| `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
|
+
| `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
|
+
| `ExecuteOptions` | interface | `{ workspace?, environment?, input?, timeout?, grace?, signal?, strict?, limit? }` | Configures a one-shot run. |
|
|
214
|
+
| `ExecuteSyncOptions` | interface | `{ workspace?, environment?, input?, timeout?, strict?, limit? }` | Configures a synchronous one-shot run. |
|
|
215
|
+
| `DetachOptions` | interface | `{ workspace? }` | Configures a detached fire-and-forget spawn. |
|
|
216
|
+
| `ProcessManagerEventMap` | type | `{ launch, exit }` | Represents the push observation surface of a `ProcessManagerInterface` — the fleet-level moments a fire-and-forget observer subscribes to. |
|
|
217
|
+
| `ProcessManagerOptions` | interface | `{ on?, error? }` | Configures a `ProcessManagerInterface`. |
|
|
218
|
+
| `ProcessManagerInterface` | interface | `{ emitter, count } plus process, processes, launch, stop, destroy` | Represents a keyed registry of live supervised child processes. |
|
|
219
|
+
| `ProcessErrorCode` | type | `(typeof PROCESS_ERROR_CODES)[number]` | Names the machine-readable `ProcessError` categories, derived from `PROCESS_ERROR_CODES`: `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`. |
|
|
220
|
+
| `ProcessErrorContext` | interface | `{ id?, command?, code?, signal?, value? }` | Represents structured context carried by a `ProcessError`. |
|
|
221
|
+
| `ProcessErrorOptions` | interface | `{ code, context?, cause?, result? }` | Configures a `ProcessError`. |
|
|
214
222
|
|
|
215
223
|
### Server contracts
|
|
216
224
|
|
|
@@ -230,16 +238,16 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
230
238
|
### Surface notes
|
|
231
239
|
|
|
232
240
|
Every member a `Shape` cell names before `plus` is a readonly data property, so it stays a Surface
|
|
233
|
-
row. `
|
|
241
|
+
row. `ended` and `exit` are among them: a promise you await is a value the entity holds, not a call
|
|
234
242
|
you make. A `SupervisorFace` member is among them too: it holds a function the caller supplies
|
|
235
243
|
rather than declaring one the contract implements. The call-signature members after `plus` are
|
|
236
244
|
documented under [Methods](#methods).
|
|
237
245
|
|
|
238
246
|
The `Supervisor` class publishes readonly data members of its own: `stdout`, `pid`, `code`, `signal`,
|
|
239
|
-
`evidence`, `settled`, `
|
|
247
|
+
`evidence`, `settled`, `terminated`, `ended`, and `exit`. It declares no interface, so they are named
|
|
240
248
|
here rather than in a Surface row. `stdout` holds the child's standard-output stream, and it is the
|
|
241
249
|
stream a composing face attaches its own consumer to, because the engine frames no output and owns
|
|
242
|
-
no observation surface. `pid`, `code`, and `signal` read the host child directly and `
|
|
250
|
+
no observation surface. `pid`, `code`, and `signal` read the host child directly and `ended` settles
|
|
243
251
|
with it, while `evidence`, `settled`, and `exit` reach
|
|
244
252
|
[the terminal moment](#the-terminal-moment) after the read channels close or the `drain` window cuts
|
|
245
253
|
them off.
|
|
@@ -337,19 +345,19 @@ fault, and the terminal `exit`, alongside the `exit` promise.
|
|
|
337
345
|
|
|
338
346
|
`ProcessOptions` requires `command` and `workspace`; the rest are optional:
|
|
339
347
|
|
|
340
|
-
| Option | Type | Required | Meaning
|
|
341
|
-
| ----------- | ------------------------------- | -------- |
|
|
342
|
-
| `command` | `ProcessCommand` | yes | The executable, its argument vector, and optional environment overrides and stdin `input`.
|
|
343
|
-
| `workspace` | `string` | yes | The working directory the child runs in.
|
|
344
|
-
| `grace` | `number` | no | POSIX milliseconds between `SIGTERM` and `SIGKILL`. Default: `PROCESS_GRACE` (`5_000`).
|
|
345
|
-
| `drain` | `number` | no | Milliseconds the package waits for the child's read ends to close after its
|
|
346
|
-
| `evidence` | `number` | no | Maximum retained stderr tail in bytes. Default: `PROCESS_EVIDENCE` (`2_048`).
|
|
347
|
-
| `backlog` | `number` | no | Soft high-water mark in bytes; termination retains at most twice `backlog`. Default: `PROCESS_BACKLOG`.
|
|
348
|
-
| `delivery` | `number` | no | Milliseconds an unconfirmed `send` waits before resolving `false`; `0` or omitted disables the bound.
|
|
349
|
-
| `writable` | `boolean` | no | When `true`, stdin stays open for `send`; when `false` or omitted, stdin closes after any initial `input`.
|
|
350
|
-
| `signal` | `AbortSignal` | no | Aborting this signal terminates the child through the same bounded `stop`.
|
|
351
|
-
| `on` | `EmitterHooks<ProcessEventMap>` | no | Initial `stderr`, `error`, and `exit` listeners installed at construction.
|
|
352
|
-
| `error` | `EmitterErrorHandler` | no | Receives a listener's throw, isolated from the engine.
|
|
348
|
+
| Option | Type | Required | Meaning |
|
|
349
|
+
| ----------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
350
|
+
| `command` | `ProcessCommand` | yes | The executable, its argument vector, and optional environment overrides and stdin `input`. |
|
|
351
|
+
| `workspace` | `string` | yes | The working directory the child runs in. |
|
|
352
|
+
| `grace` | `number` | no | POSIX milliseconds between `SIGTERM` and `SIGKILL`. Default: `PROCESS_GRACE` (`5_000`). |
|
|
353
|
+
| `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`). |
|
|
354
|
+
| `evidence` | `number` | no | Maximum retained stderr tail in bytes. Default: `PROCESS_EVIDENCE` (`2_048`). |
|
|
355
|
+
| `backlog` | `number` | no | Soft high-water mark in bytes; termination retains at most twice `backlog`. Default: `PROCESS_BACKLOG`. |
|
|
356
|
+
| `delivery` | `number` | no | Milliseconds an unconfirmed `send` waits before resolving `false`; `0` or omitted disables the bound. |
|
|
357
|
+
| `writable` | `boolean` | no | When `true`, stdin stays open for `send`; when `false` or omitted, stdin closes after any initial `input`. |
|
|
358
|
+
| `signal` | `AbortSignal` | no | Aborting this signal terminates the child through the same bounded `stop`. |
|
|
359
|
+
| `on` | `EmitterHooks<ProcessEventMap>` | no | Initial `stderr`, `error`, and `exit` listeners installed at construction. |
|
|
360
|
+
| `error` | `EmitterErrorHandler` | no | Receives a listener's throw, isolated from the engine. |
|
|
353
361
|
|
|
354
362
|
There is no completion deadline for a running child. Nothing here ends a child that is still
|
|
355
363
|
working, the `exit` promise carries no deadline of its own, and a caller that wants one arms its own
|
|
@@ -389,24 +397,24 @@ it, so no switch selects whether one exists.
|
|
|
389
397
|
|
|
390
398
|
`SessionOptions` requires `command` and `workspace`; the rest are optional:
|
|
391
399
|
|
|
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
|
|
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<SessionEventMap>` | no | Initial `stdout`, `stderr`, `error`, and `exit` listeners installed at construction.
|
|
402
|
-
| `error` | `EmitterErrorHandler` | no | Receives a listener's throw, isolated from the engine.
|
|
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. |
|
|
403
411
|
|
|
404
412
|
A session names the child's ending and the supervision's ending apart, because a transport acts on
|
|
405
|
-
each differently. `
|
|
413
|
+
each differently. `ended` settles at the child's own native exit and resolves no value: `code` and
|
|
406
414
|
`signal` already carry the terminal facts, so a second copy of them here could only drift from them.
|
|
407
415
|
`exit` settles at [the terminal moment](#the-terminal-moment), which is that native exit plus at most
|
|
408
416
|
`drain` while a descendant holds the inherited read ends. Race a cooperative shutdown window against
|
|
409
|
-
`
|
|
417
|
+
`ended`; a window raced against `exit` escalates against a child that already ended.
|
|
410
418
|
|
|
411
419
|
`end` closes the stdin channel and leaves the child running. That is the cooperative shutdown a
|
|
412
420
|
protocol client runs: end the input, let the child finish its own work, and terminate only when it
|
|
@@ -426,12 +434,12 @@ session.emitter.on('stdout', (chunk) => received.push(chunk))
|
|
|
426
434
|
|
|
427
435
|
await session.write(new TextEncoder().encode('ping')) // true — the host accepted the bytes
|
|
428
436
|
await session.end() // the child sees end of input; nothing terminated it
|
|
429
|
-
await session.
|
|
437
|
+
await session.ended // it exited on its own
|
|
430
438
|
|
|
431
439
|
Buffer.concat(received).toString('utf8') // 'ping' — the exact bytes, with no terminator added
|
|
432
440
|
const exit = await session.exit
|
|
433
441
|
exit.code // 0
|
|
434
|
-
session.
|
|
442
|
+
session.terminated // false — no termination was initiated
|
|
435
443
|
await session.destroy()
|
|
436
444
|
```
|
|
437
445
|
|
|
@@ -445,7 +453,7 @@ surface is shaped around.
|
|
|
445
453
|
- **The supervision's ending** is the terminal moment: `settled`, `exit`, `evidence`, and `lines`.
|
|
446
454
|
They reach it together.
|
|
447
455
|
|
|
448
|
-
`Session` gives the child's
|
|
456
|
+
`Session` gives the child's exit a member of its own, `ended`, which settles at the native exit
|
|
449
457
|
and resolves no value. `Process` carries no such member: a line consumer reads that ending from
|
|
450
458
|
`code` and `signal`, which have always reported it.
|
|
451
459
|
|
|
@@ -478,16 +486,16 @@ A `Session` reaches the same moment through the same paths, with its byte events
|
|
|
478
486
|
the last `stdout` and `stderr` events are delivered before the `exit` event, and none follows it.
|
|
479
487
|
|
|
480
488
|
`end` is the one member on either face that does not reach the moment. It closes a session's stdin
|
|
481
|
-
channel and leaves the child running, so `
|
|
489
|
+
channel and leaves the child running, so `terminated` stays false, no drain window is armed, and `exit`
|
|
482
490
|
stays pending until the child ends itself or something terminates it. Every other verb here ends the
|
|
483
491
|
observation; `end` ends only the input.
|
|
484
492
|
|
|
485
493
|
`stop` reaches the terminal moment as well as `destroy` does. A caller that terminates a child and
|
|
486
494
|
keeps reading it therefore reaches the end of the stream instead of waiting on a child it already
|
|
487
|
-
ended, and needs no second call to release it. `
|
|
495
|
+
ended, and needs no second call to release it. `terminated` reports the initiation rather than the
|
|
488
496
|
arrival: it turns `true` when `stop`, `destroy`, or an abort of `signal` begins a termination, and it stays
|
|
489
497
|
`true` from then on, including after `settled` turns `true`. A child that exited on its own reports
|
|
490
|
-
`
|
|
498
|
+
`terminated` as `false` with `settled` as `true`.
|
|
491
499
|
|
|
492
500
|
A consumer handed the terminal value never reads a child that still reports itself unfinished. The
|
|
493
501
|
latch runs before the `exit` event and before the read ends are released, so a listener on that
|
|
@@ -509,7 +517,7 @@ const child = createProcess({
|
|
|
509
517
|
const exit = await child.exit
|
|
510
518
|
exit.drained // true — the child's own streams closed
|
|
511
519
|
child.settled // true — evidence is frozen and lines has ended
|
|
512
|
-
child.
|
|
520
|
+
child.terminated // false — this child ended on its own
|
|
513
521
|
child.evidence // 'done\n' — the frozen tail every later read returns
|
|
514
522
|
await child.destroy()
|
|
515
523
|
```
|
|
@@ -661,7 +669,7 @@ after the frozen state exists, so a consumer watching the `stderr` event and a c
|
|
|
661
669
|
`evidence` end on the same bytes.
|
|
662
670
|
|
|
663
671
|
`Session` terminates through the same verbs with the same bounds and the same barriers. Run its
|
|
664
|
-
cooperative shutdown first where the child supports one: call `end`, race `
|
|
672
|
+
cooperative shutdown first where the child supports one: call `end`, race `ended` against a window
|
|
665
673
|
of your own, and call `stop` when that window expires.
|
|
666
674
|
|
|
667
675
|
POSIX detachment creates the process group that tree termination signals. The child therefore
|
|
@@ -1150,10 +1158,11 @@ value with `isProcessError`, then branch on `code`.
|
|
|
1150
1158
|
|
|
1151
1159
|
`isProcessError` recognizes an error thrown by another installed copy of the package. It reads a
|
|
1152
1160
|
global own-property brand rather than `instanceof`, so a duplicate installation and an ESM/CommonJS
|
|
1153
|
-
module copy both narrow
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
1161
|
+
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
|
|
1163
|
+
requires the native `Error` base, a prototype other than `Error.prototype`, a declared code, and
|
|
1164
|
+
correctly shaped optional context and result members. It never reads `name`, so subclass instances
|
|
1165
|
+
pass. Older boolean brands, transparent proxies, and branded plain objects fail recognition.
|
|
1157
1166
|
|
|
1158
1167
|
A run failure carries its `ExecuteResult` on `error.result`, and its command line, exit `code`, and
|
|
1159
1168
|
`signal` on `error.context`. A duplicate-id and a protocol failure carry the offending `id` on
|
|
@@ -1305,7 +1314,7 @@ const session = createSession({
|
|
|
1305
1314
|
// …on shutdown: end the input, give the child a window of your own, then terminate if it overruns.
|
|
1306
1315
|
const window = new Promise<boolean>((resolve) => setTimeout(() => resolve(false), 2_000))
|
|
1307
1316
|
const flushed = await Promise.race([session.end().then(() => true), window])
|
|
1308
|
-
const finished = flushed ? await Promise.race([session.
|
|
1317
|
+
const finished = flushed ? await Promise.race([session.ended.then(() => true), window]) : false
|
|
1309
1318
|
if (!finished) await session.stop()
|
|
1310
1319
|
await session.destroy()
|
|
1311
1320
|
```
|
|
@@ -1423,9 +1432,9 @@ isExited(reporter) // whether the native exit arrived
|
|
|
1423
1432
|
- **Reach for `Session` when the child speaks a protocol** — `lines` frames text, and a
|
|
1424
1433
|
length-prefixed header, a binary payload, or a NUL byte survives no line framer. A session hands
|
|
1425
1434
|
you the exact bytes and lets you frame them.
|
|
1426
|
-
- **Close a session with `end`, then race `
|
|
1427
|
-
terminates nothing, `
|
|
1428
|
-
that overruns the window you gave it. Race `
|
|
1435
|
+
- **Close a session with `end`, then race `ended`, then `stop`** — `end` closes the input and
|
|
1436
|
+
terminates nothing, `ended` reports the child's own exit, and `stop` is the escalation for a child
|
|
1437
|
+
that overruns the window you gave it. Race `ended` rather than `exit`: `exit` waits out `drain`
|
|
1429
1438
|
for a descendant holding the pipe, so a window raced against it escalates against a child that
|
|
1430
1439
|
already ended.
|
|
1431
1440
|
- **Give `execute` a `timeout` when the command can start a descendant** — an unbounded run waits on
|
|
@@ -1461,13 +1470,13 @@ Each name on this surface that reads against a house rule is settled here rather
|
|
|
1461
1470
|
| `truncated` | One name on both surfaces, because it reports one fact: the surface omitted output. Each entity names its own bound — a `Process` omits `lines` past a retention bound, and an `ExecuteResult` omits captured text past `limit`. |
|
|
1462
1471
|
| `run` | Kept as the English noun for one invocation — a terminated run, a run that stays pending. It never names a function; `execute` and `executeSync` are named by their identifiers, so the concept carries one term. |
|
|
1463
1472
|
| `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`. |
|
|
1464
|
-
| `
|
|
1473
|
+
| `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. |
|
|
1465
1474
|
| `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. |
|
|
1466
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. |
|
|
1467
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. |
|
|
1468
1477
|
| `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. |
|
|
1469
|
-
| `
|
|
1470
|
-
| `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 `
|
|
1478
|
+
| `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
|
+
| `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. |
|
|
1471
1480
|
| `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. |
|
|
1472
1481
|
| `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. |
|
|
1473
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. |
|
|
@@ -1541,7 +1550,7 @@ The pure decision rows do not prove Windows end to end. They prove the decisions
|
|
|
1541
1550
|
event and the tail stopping together, `lines` ending an in-flight read after its queued lines, the
|
|
1542
1551
|
`exit` promise settling at the cutoff when the streams never close, the `drain` bound driven shorter
|
|
1543
1552
|
and longer than a descendant release, `stop` alone reaching the moment with no `destroy` call, the
|
|
1544
|
-
latched `
|
|
1553
|
+
latched `terminated` refusing a `send`, the released abort listener, the spawn-fault path, and the
|
|
1545
1554
|
`drain` refusals at each end of its range.
|
|
1546
1555
|
- [`tests/src/server/processes/Session.test.ts`](../tests/src/server/processes/Session.test.ts) —
|
|
1547
1556
|
the byte face: a binary payload carrying NUL bytes, an invalid UTF-8 sequence, a lone carriage return, and an embedded line
|
|
@@ -1559,7 +1568,7 @@ The pure decision rows do not prove Windows end to end. They prove the decisions
|
|
|
1559
1568
|
- [`tests/src/server/processes/Supervisor.test.ts`](../tests/src/server/processes/Supervisor.test.ts)
|
|
1560
1569
|
— the engine driven through a literal face: the moment order that ends the face's read pipeline, freezes the
|
|
1561
1570
|
terminal state, and only then releases the face; the backpressure release reaching a face holding
|
|
1562
|
-
a paused stdout before the termination sequence rather than after it; `
|
|
1571
|
+
a paused stdout before the termination sequence rather than after it; `ended` settling at the
|
|
1563
1572
|
native exit while `exit` waits out the drain a descendant holds open; a `deliver` refused once a
|
|
1564
1573
|
termination has begun; and the one barrier every `end` call shares, with the child ending itself
|
|
1565
1574
|
because its input ended.
|
|
@@ -1586,13 +1595,15 @@ The pure decision rows do not prove Windows end to end. They prove the decisions
|
|
|
1586
1595
|
and its percent-sign refusal, the environment merge under each platform input, the UTF-8-safe
|
|
1587
1596
|
byte bounds retreating a cut to a code-point boundary, the per-chunk capture bound and the byte it
|
|
1588
1597
|
keeps past `limit`, the validators, the termination helpers, and `waitForClose` across a close
|
|
1589
|
-
inside its deadline, a deadline that elapsed first, and the listeners it leaves behind. The
|
|
1590
|
-
|
|
1591
|
-
|
|
1592
|
-
|
|
1593
|
-
|
|
1594
|
-
|
|
1595
|
-
|
|
1598
|
+
inside its deadline, a deadline that elapsed first, and the listeners it leaves behind. The
|
|
1599
|
+
fire-and-forget spawn covers owned inputs, detached process-group behavior, invalid-input
|
|
1600
|
+
refusal, and the validated working directory.
|
|
1601
|
+
- [`tests/src/server/execution/execute.test.ts`](../tests/src/server/execution/execute.test.ts)
|
|
1602
|
+
— the asynchronous one-shot run: owned inputs, buffered outcomes, failure delivery,
|
|
1603
|
+
cancellation, timeout, capture bounds, spawn faults, and pre-spawn refusal.
|
|
1604
|
+
- [`tests/src/server/execution/executeSync.test.ts`](../tests/src/server/execution/executeSync.test.ts)
|
|
1605
|
+
— the blocking run: root-only timeout and argument integrity beside owned inputs, buffered
|
|
1606
|
+
outcomes, failure delivery, capture bounds, spawn faults, and pre-spawn refusal.
|
|
1596
1607
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — this guide: the `## Surface` bijection against
|
|
1597
1608
|
each published face's barrel, the interface-to-class method bijections, and the equality gate:
|
|
1598
1609
|
every `Summary` cell against its declaration's description paragraph, the titled
|
|
@@ -1608,7 +1619,8 @@ The pure decision rows do not prove Windows end to end. They prove the decisions
|
|
|
1608
1619
|
vector each mode produces.
|
|
1609
1620
|
- [`tests/setupServer.test.ts`](../tests/setupServer.test.ts) — the same builders spawned for real:
|
|
1610
1621
|
the fixture's own exit code, stdout, and stderr for a supplied detail, its own default when the
|
|
1611
|
-
caller omits one, and the argument vector reaching it unmodified
|
|
1622
|
+
caller omits one, and the argument vector reaching it unmodified; the exit-boundary fixture's
|
|
1623
|
+
listener identity and removal behavior.
|
|
1612
1624
|
|
|
1613
1625
|
## See also
|
|
1614
1626
|
|
|
@@ -178,6 +178,10 @@ checks membership through `STATUSES`.
|
|
|
178
178
|
|
|
179
179
|
### Errors
|
|
180
180
|
|
|
181
|
+
The error guard recognizes the shared brand across package copies and accepts
|
|
182
|
+
subclasses without requiring their name. It refuses transparent proxies and
|
|
183
|
+
unbranded look-alikes.
|
|
184
|
+
|
|
181
185
|
| API | Kind | Summary |
|
|
182
186
|
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
183
187
|
| `ProgramError` | class | Reports a coded programmer error thrown by the program layer, carrying a machine-readable code and an optional context and cause. |
|
|
@@ -120,6 +120,10 @@ and `context.cause` preserves the original throw. A `DEFINITION`/`INVALID` or
|
|
|
120
120
|
`DESTROYED` engine throw maps to the matching code instead, and a `DEFINITION` throw
|
|
121
121
|
raised by `qualify`'s own validation carries `context.definition`.
|
|
122
122
|
|
|
123
|
+
The guard recognizes the error's own identity brand across package copies and module
|
|
124
|
+
formats. It accepts subclasses regardless of their `name` and refuses transparent
|
|
125
|
+
proxies, unbranded look-alikes, and plain branded objects.
|
|
126
|
+
|
|
123
127
|
```ts
|
|
124
128
|
import { isQualifierError, QualifierError } from '@orkestrel/qualifier'
|
|
125
129
|
|
|
@@ -103,6 +103,10 @@ and an optional `context` record of structured detail beside its message.
|
|
|
103
103
|
The `isRaterError` guard narrows a caught value, so a handler reads the `code` member
|
|
104
104
|
off it:
|
|
105
105
|
|
|
106
|
+
The guard recognizes the error's own identity brand across package copies and module
|
|
107
|
+
formats. It accepts subclasses regardless of their `name` and refuses transparent
|
|
108
|
+
proxies, unbranded look-alikes, and plain branded objects.
|
|
109
|
+
|
|
106
110
|
```ts
|
|
107
111
|
import { isRaterError, RaterError } from '@orkestrel/rater'
|
|
108
112
|
|