@orkestrel/scaffold 0.0.120 → 0.0.122
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-dispatch/scripts/brief.js +57 -9
- package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +22 -2
- package/dist/agents/skills/orkestrel-publish/scripts/pins.js +5 -5
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +67 -5
- package/dist/bin/main.js +5 -5
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +16 -11
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +2 -1
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +65 -9
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +28 -2
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -1
- package/dist/host/agents/skills/orkestrel-harden/SKILL.md +8 -8
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +3 -3
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +10 -8
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -8
- package/dist/host/agents/skills/orkestrel-publish/references/window.md +5 -1
- package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +5 -5
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +86 -7
- package/dist/host/claude/AGENTS.md +1 -1
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/opus.md +7 -6
- package/dist/host/claude/agents/orkestrel.md +26 -26
- package/dist/host/claude/agents/planner.md +3 -3
- package/dist/host/claude/agents/reviewer.md +3 -3
- package/dist/host/claude/agents/verifier.md +1 -1
- package/dist/host/claude/rules/campaign.md +3 -2
- package/dist/host/claude/rules/names.md +13 -7
- package/dist/host/claude/rules/tests.md +1 -1
- package/dist/host/claude/rules/workspace.md +9 -0
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +2 -5
- package/dist/host/codex/agents/opus.toml +5 -3
- package/dist/host/codex/agents/planner.toml +6 -5
- package/dist/host/codex/agents/reviewer.toml +4 -7
- package/dist/host/codex/agents/verifier.toml +2 -2
- package/dist/host/dotfiles/gitignore +1 -2
- 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/capture.md +2 -2
- package/dist/host/guides/console.md +4 -30
- package/dist/host/guides/guide.md +0 -1
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/probe.md +71 -80
- 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/relation.md +0 -2
- package/dist/host/guides/scaffold.md +18 -9
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- package/dist/host/guides/terminal.md +0 -26
- package/dist/host/guides/toolbox.md +0 -10
- 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 +63 -483
- package/dist/host/tests/config.test.ts +7 -0
- package/dist/src/core/index.cjs +13 -46
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +13 -46
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +10 -9
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +12 -8
- package/dist/src/server/index.d.ts +12 -8
- package/dist/src/server/index.js +10 -9
- package/dist/src/server/index.js.map +1 -1
- package/package.json +5 -5
- /package/dist/host/agents/skills/orkestrel-parallel/references/{claude.md → claude-code.md} +0 -0
|
@@ -46,12 +46,12 @@ The package publishes these factories. `createWorker` is the `@orkestrel/worker`
|
|
|
46
46
|
`createJSONQueueStore`, `createNodeWorker`, and `serveWorker` are the
|
|
47
47
|
`@orkestrel/worker/server` exports.
|
|
48
48
|
|
|
49
|
-
| Name | Kind | Signature
|
|
50
|
-
| ---------------------- | -------- |
|
|
51
|
-
| `createWorker` | function | `<TInput, TResource, TResult>(options: WorkerOptions<TInput, TResource, TResult>) =>
|
|
52
|
-
| `createJSONQueueStore` | function | `<TInput extends ContractShape>(path: string, input: TInput) => QueueStoreInterface<Infer<TInput>>`
|
|
53
|
-
| `createNodeWorker` | function | `<TInput, TResult>(options: NodeWorkerOptions<TInput, TResult>) =>
|
|
54
|
-
| `serveWorker` | function | `<TInput, TResult>(options: ServeWorkerOptions<TInput, TResult>) => void`
|
|
49
|
+
| Name | Kind | Signature | Summary |
|
|
50
|
+
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
51
|
+
| `createWorker` | function | `<TInput, TResource, TResult>(options: WorkerOptions<TInput, TResource, TResult>) => QueueInterface<TInput, TResult>` | Creates a resource-backed job worker — a `Queue` (`@orkestrel/queue`) composed with a `Pool` (`@orkestrel/pool`), where each enqueued input runs through the handler against an automatically acquired pooled resource released when the job settles. |
|
|
52
|
+
| `createJSONQueueStore` | function | `<TInput extends ContractShape>(path: string, input: TInput) => QueueStoreInterface<Infer<TInput>>` | Creates a persistent JSON-file `QueueStoreInterface` — the core `createDatabaseQueueStore` over a server `createJSONDriver`. |
|
|
53
|
+
| `createNodeWorker` | function | `<TInput, TResult>(options: NodeWorkerOptions<TInput, TResult>) => QueueInterface<TInput, TResult>` | Creates a CPU-parallel worker over `node:worker_threads` — a thin specialization of the core `createWorker` whose pooled resource is a worker thread. |
|
|
54
|
+
| `serveWorker` | function | `<TInput, TResult>(options: ServeWorkerOptions<TInput, TResult>) => void` | Registers a worker-thread handler — the worker-side half of `createNodeWorker`. |
|
|
55
55
|
|
|
56
56
|
### Threads
|
|
57
57
|
|
|
@@ -61,14 +61,14 @@ these to drive one thread yourself; `createNodeWorker` is the entry point for po
|
|
|
61
61
|
work. Driving a thread by hand:
|
|
62
62
|
|
|
63
63
|
```ts
|
|
64
|
-
import { createThread,
|
|
64
|
+
import { createThread, isReply, Job } from '@orkestrel/worker/server'
|
|
65
65
|
|
|
66
66
|
const isNumber = (value: unknown): value is number => typeof value === 'number'
|
|
67
67
|
|
|
68
68
|
const thread = await createThread(new URL('./double.ts', import.meta.url))
|
|
69
69
|
const controller = new AbortController()
|
|
70
70
|
try {
|
|
71
|
-
const job = new
|
|
71
|
+
const job = new Job(thread, 21, { id: 'job-1', signal: controller.signal }, isNumber)
|
|
72
72
|
console.log(await job.promise) // 42
|
|
73
73
|
console.log(isReply({ id: 'reply-1', ok: true, value: 42 }, 'reply-1')) // true
|
|
74
74
|
console.log(isReply({ id: 'reply-1', ok: true, value: 42 }, 'other')) // false
|
|
@@ -88,41 +88,38 @@ The thread-level functions behind `createNodeWorker`:
|
|
|
88
88
|
|
|
89
89
|
The classes the core and server faces export:
|
|
90
90
|
|
|
91
|
-
| Name
|
|
92
|
-
|
|
|
93
|
-
| `
|
|
94
|
-
| `Worker`
|
|
91
|
+
| Name | Kind | Signature | Summary |
|
|
92
|
+
| -------- | ----- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
93
|
+
| `Job` | class | `new <TResult>(thread: NodeThread, input: unknown, context: QueueContext, result: Guard<TResult>) => Job<TResult>` | Represents one dispatched worker-thread job — the lifecycle entity behind a job posted to a leased `NodeThread`, whose `promise` settles with the narrowed reply. |
|
|
94
|
+
| `Worker` | class | `new <TInput, TResource, TResult>(options: WorkerOptions<TInput, TResource, TResult>) => QueueInterface<TInput, TResult>` | Represents a resource-backed job worker — a thin facade composing a `Queue` (`@orkestrel/queue`) with a `Pool` (`@orkestrel/pool`). |
|
|
95
95
|
|
|
96
96
|
### Types
|
|
97
97
|
|
|
98
|
-
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 `\|`.
|
|
99
|
-
|
|
100
98
|
Each type and interface the core and server faces publish:
|
|
101
99
|
|
|
102
|
-
| Name | Kind | Signature
|
|
103
|
-
| -------------------- | --------- |
|
|
104
|
-
| `WorkerHandler` | type | `(input: TInput, resource: TResource, context: QueueContext) => Promise<TResult> \| TResult`
|
|
105
|
-
| `WorkerOptions` | interface | `{ on?, error?, handler, pool, concurrency?, retries?, timeout?, store? }`
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
`
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
100
|
+
| Name | Kind | Signature | Summary |
|
|
101
|
+
| -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
102
|
+
| `WorkerHandler` | type | `(input: TInput, resource: TResource, context: QueueContext) => Promise<TResult> \| TResult` | Runs one worker job with a leased pool resource. |
|
|
103
|
+
| `WorkerOptions` | interface | `{ on?, error?, handler, pool, concurrency?, retries?, timeout?, store? }` | Configures `createWorker`. |
|
|
104
|
+
| `NodeWorkerOptions` | interface | `{ on?, error?, script, input, result, workerData?, concurrency?, retries?, timeout?, store? }` | Configures `createNodeWorker` — a CPU-parallel worker over `node:worker_threads`. |
|
|
105
|
+
| `ServeWorkerOptions` | interface | `{ input, handler }` | Configures `serveWorker` — the worker-side entry a thread script registers. |
|
|
106
|
+
| `NodeThread` | interface | `{ worker, alive, death }` | Represents a live worker thread plus its latched liveness state — the pooled resource a `createNodeWorker` leases per job. |
|
|
107
|
+
| `Reply` | type | `{ readonly id: string; readonly ok: true; readonly value: unknown; } \| { readonly id: string; readonly ok: false; readonly error: string; }` | Represents a thread→main reply envelope — a success carrying an opaque `value`, or a failure with a message — the reply half of the wire protocol `createNodeWorker` posts and `serveWorker` answers. |
|
|
108
|
+
|
|
109
|
+
`Worker` implements `@orkestrel/queue`'s `QueueInterface`, and `createWorker` and
|
|
110
|
+
`createNodeWorker` return that interface. Its `emitter` / `count` / `active` / `paused` / `stopped`
|
|
111
|
+
members are `readonly` data members: `emitter` is the typed push observation surface
|
|
112
|
+
carrying the queue's `QueueEventMap` (see [Observing](#observing)), and the call-signature
|
|
113
|
+
methods are documented under [Methods](#methods). `Queue` / `Pool` themselves — and their
|
|
114
|
+
own options, event maps, and stores — are documented in their own packages:
|
|
115
|
+
[queue.md](queue.md) / [pool.md](pool.md).
|
|
118
116
|
|
|
119
117
|
## Methods
|
|
120
118
|
|
|
121
|
-
The public methods of `
|
|
122
|
-
|
|
123
|
-
exactly, so this doubles as the class's instance-method surface.
|
|
119
|
+
The public methods of `Worker` — every call-signature member of `QueueInterface` it
|
|
120
|
+
implements, with no method beyond them.
|
|
124
121
|
|
|
125
|
-
#### `
|
|
122
|
+
#### `Worker`
|
|
126
123
|
|
|
127
124
|
| Method | Returns | Summary |
|
|
128
125
|
| --------- | ------------------ | ------------------------------------------------------------------------------------------------------------------ |
|
|
@@ -177,7 +174,7 @@ These invariants hold across `src/core` ↔ `worker.md`:
|
|
|
177
174
|
settlement serially, aggregates the queue's failure and the pool's in that order, and
|
|
178
175
|
destroys the worker emitter last.
|
|
179
176
|
3. **Observable — the queue lifecycle re-exposed.** The `Worker` owns a typed `Emitter`
|
|
180
|
-
exposed as `readonly emitter` carrying `
|
|
177
|
+
exposed as `readonly emitter` carrying `QueueEventMap<TResult>`
|
|
181
178
|
(`enqueue` / `start` / `retry` / `success` / `failure` / `abort` / `drain`), bridged
|
|
182
179
|
from the underlying queue's own emitter at construction — each bridge listener
|
|
183
180
|
re-emits directly on the worker's emitter and never throws, so the inner queue's own
|
|
@@ -188,16 +185,16 @@ These invariants hold across `src/core` ↔ `worker.md`:
|
|
|
188
185
|
own `create` / `acquire` / `release` / `destroy` events stay the pool's internal
|
|
189
186
|
concern — observe a `Pool` directly for those.
|
|
190
187
|
4. **Doc ↔ source method bijection.** The `## Methods` table lists exactly the public
|
|
191
|
-
methods of `
|
|
192
|
-
|
|
188
|
+
methods of `Worker` — exhaustive, both directions — and they are the methods of the
|
|
189
|
+
`QueueInterface` it implements, no more.
|
|
193
190
|
5. **`createNodeWorker` is a thread specialization of `createWorker` (`@orkestrel/worker/server`).**
|
|
194
191
|
It does not reimplement concurrency / retry / timeout / lifecycle — it calls
|
|
195
192
|
`createWorker` with a `Pool` whose resource is a `node:worker_threads` thread
|
|
196
193
|
(`create` = the spawn `createThread` publishes, `destroy` = `terminate()`,
|
|
197
194
|
`validate` = `alive && threadId > 0`) and an internal handler that narrows the input
|
|
198
|
-
through `options.input` then runs a `
|
|
195
|
+
through `options.input` then runs a `Job` against the leased thread. `TInput` and
|
|
199
196
|
`TResult` infer from the `input` and `result` guards, so a call site needs no type
|
|
200
|
-
argument. The structured-clone boundary is crossed with no `as`: a `
|
|
197
|
+
argument. The structured-clone boundary is crossed with no `as`: a `Job` narrows each reply
|
|
201
198
|
value through `options.result` (a value that fails it rejects with `'reply did not
|
|
202
199
|
satisfy result guard'`), and the worker side narrows each payload through
|
|
203
200
|
`options.input` (a bad input replies `'input did not satisfy input guard'`) —
|
|
@@ -223,15 +220,15 @@ These invariants hold across `src/core` ↔ `worker.md`:
|
|
|
223
220
|
7. **A thread death settles its job under every event ordering — the `death` latch.**
|
|
224
221
|
Every spawned thread carries persistent `error` / `messageerror` / `exit` listeners that
|
|
225
222
|
flip `alive = false`
|
|
226
|
-
and latch the first terminal event on `NodeThread.death`; a `
|
|
223
|
+
and latch the first terminal event on `NodeThread.death`; a `Job` checks that latch
|
|
227
224
|
synchronously at construction, so a job dispatched onto a thread that already died rejects
|
|
228
225
|
immediately. A thread can become terminal before the readiness promise continuation
|
|
229
|
-
attaches
|
|
230
|
-
the job would wait forever. A death mid-flight still rejects through the
|
|
226
|
+
attaches `Job` listeners, and those events will never fire again; without the latch
|
|
227
|
+
the job would wait forever. A death mid-flight still rejects through the `Job`'s own
|
|
231
228
|
`error` / `exit` listeners; exit rejects with that exact already-latched `death` object,
|
|
232
229
|
whose message retains the exit code (for example, `worker thread exited (code 1)`). An
|
|
233
230
|
inbound `messageerror` also evicts and terminates the thread, rejects the
|
|
234
|
-
|
|
231
|
+
job, and is detached with the other per-job listeners. A death before `online`
|
|
235
232
|
rejects the spawn itself.
|
|
236
233
|
8. **`serveWorker` captures registration options once.** After the main-thread
|
|
237
234
|
`parentPort === null` no-op, registration reads `options.input` and then
|
|
@@ -240,9 +237,9 @@ These invariants hold across `src/core` ↔ `worker.md`:
|
|
|
240
237
|
the initially captured guard and handler identities. The main-thread no-op reads neither.
|
|
241
238
|
9. **Structured-clone constraints.** `TInput` / `TResult` / `workerData` must be
|
|
242
239
|
structured-cloneable (no functions / Promises / `AbortSignal`). A non-cloneable result
|
|
243
|
-
cannot strand a
|
|
240
|
+
cannot strand a job: `serveWorker` replaces the failed success post with a clone-safe
|
|
244
241
|
failure envelope, and closes the parent port if even that fallback cannot be posted so the
|
|
245
|
-
main side observes exit. A matching-id malformed reply similarly rejects the
|
|
242
|
+
main side observes exit. A matching-id malformed reply similarly rejects the job,
|
|
246
243
|
terminates and evicts the tainted thread, and leaves id-less / foreign-id chatter ignored.
|
|
247
244
|
Raw TypeScript is unflagged on Node 22.18+ and Node 23.6+; Node 22.12–22.17 and Node
|
|
248
245
|
23.0–23.5 require `--experimental-strip-types`. A built `.js` / `.mjs` script is an
|
|
@@ -251,7 +248,7 @@ These invariants hold across `src/core` ↔ `worker.md`:
|
|
|
251
248
|
that runs the handler and answers the protocol; it is self-contained and imports only
|
|
252
249
|
`node:worker_threads` at runtime,
|
|
253
250
|
so it loads as a raw module in a spawned thread. `createNodeWorker` returns the plain
|
|
254
|
-
`
|
|
251
|
+
`QueueInterface`, so it inherits the Worker's `emitter` unchanged (clause 3).
|
|
255
252
|
10. **`createJSONQueueStore` is `@orkestrel/queue`'s `createDatabaseQueueStore` over a
|
|
256
253
|
server JSON driver.** A queue's durable state is a `@orkestrel/database` table,
|
|
257
254
|
so JSON persistence reuses the existing driver rather than a bespoke store — see
|
|
@@ -262,7 +259,7 @@ These invariants hold across `src/core` ↔ `worker.md`:
|
|
|
262
259
|
`createNodeWorker` (`@orkestrel/worker/server`) runs jobs on a pool of `node:worker_threads` threads —
|
|
263
260
|
true CPU parallelism for work that would otherwise block the event loop. It is a thin
|
|
264
261
|
specialization of [`createWorker`](#surface): the pooled resource is a worker thread, and
|
|
265
|
-
it returns the plain `
|
|
262
|
+
it returns the plain `QueueInterface`, so its methods, lifecycle, concurrency, retries,
|
|
266
263
|
timeout, and durability are exactly the Worker's (see [Methods](#methods)). The only
|
|
267
264
|
additions are the thread pairing and the zero-`as` wire bridge.
|
|
268
265
|
|
|
@@ -326,7 +323,7 @@ structured-cloneable (no functions, Promises, or `AbortSignal`s cross the bounda
|
|
|
326
323
|
name, and the thread reads it back from `node:worker_threads`.
|
|
327
324
|
|
|
328
325
|
A thread worker takes the same `on` and `error` hooks as the core worker: pass `on` to wire
|
|
329
|
-
initial `
|
|
326
|
+
initial `QueueEventMap` listeners at construction, and `error` to receive a listener's throw
|
|
330
327
|
(see [Observing](#observing)).
|
|
331
328
|
|
|
332
329
|
## Persistence
|
|
@@ -374,9 +371,9 @@ worker.emitter.on('failure', (id, error) => log.warn(`job ${id} failed`, error))
|
|
|
374
371
|
|
|
375
372
|
The events the worker's emitter carries:
|
|
376
373
|
|
|
377
|
-
| Event map
|
|
378
|
-
|
|
|
379
|
-
| `
|
|
374
|
+
| Event map | Events |
|
|
375
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
376
|
+
| `QueueEventMap<TResult>` | `enqueue(id)` · `start(id)` · `retry(id, attempt)` · `success(id, result)` · `failure(id, error)` · `abort(reason)` · `drain()` |
|
|
380
377
|
|
|
381
378
|
The worker forwards queue event payloads unchanged. In particular, `abort(reason)` carries
|
|
382
379
|
the queue's coded `QueueError` with code `aborted`; its `cause` retains the caller-supplied
|
|
@@ -533,7 +530,7 @@ These tests pin the behaviour this guide documents:
|
|
|
533
530
|
|
|
534
531
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the
|
|
535
532
|
`## Surface` ↔ `src/core` / `src/server` bijection (value + type exports), the
|
|
536
|
-
`
|
|
533
|
+
`## Methods` ↔ `Worker` method bijection, and the equality gate: every `Summary`
|
|
537
534
|
cell against its declaration's description paragraph, the titled
|
|
538
535
|
`A resource-backed worker` fence against the `@example` block of that title (pinned so
|
|
539
536
|
the titled pair cannot be retired silently), and the README pitch against this guide's
|
|
@@ -566,9 +563,11 @@ These tests pin the behaviour this guide documents:
|
|
|
566
563
|
promise identity across repeated and abort-event-reentrant calls, waits for serial queue
|
|
567
564
|
then pool cleanup, destroys the worker emitter last, and preserves a sole pool failure;
|
|
568
565
|
and durability passthrough — a `store` persists a job and `restore()` re-runs it against
|
|
569
|
-
a fresh resource (delegated to the queue), a no-op without a store
|
|
566
|
+
a fresh resource (delegated to the queue), a no-op without a store; and the `Worker`
|
|
567
|
+
typed by `@orkestrel/queue`'s `QueueInterface`, its `emitter` and `on` hooks carrying
|
|
568
|
+
`QueueEventMap`.
|
|
570
569
|
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) —
|
|
571
|
-
`createWorker` returns a working
|
|
570
|
+
`createWorker` returns a working `QueueInterface` end to end and honours its options +
|
|
572
571
|
status surface.
|
|
573
572
|
- [`tests/src/server/factories.test.ts`](../tests/src/server/factories.test.ts) —
|
|
574
573
|
`createJSONQueueStore` over a real temp file: entries persist across store instances on
|
|
@@ -576,10 +575,11 @@ These tests pin the behaviour this guide documents:
|
|
|
576
575
|
the JSON round-trip, and a `remove` is reflected across a reopen; `createThread` resolving
|
|
577
576
|
a live thread that clones its `workerData` across, spawning with that argument omitted, and
|
|
578
577
|
rejecting a script that dies before `online`; plus a `createNodeWorker` round-trip smoke (a
|
|
579
|
-
job over a real thread
|
|
580
|
-
listener throw routed to `error`, and the option
|
|
578
|
+
job over a real thread through the returned `QueueInterface`, then teardown), the `on`
|
|
579
|
+
hooks wired at construction with a listener throw routed to `error`, and the option
|
|
580
|
+
snapshot retained across jobs.
|
|
581
581
|
- [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) — the
|
|
582
|
-
main-side worker-thread machinery (`createThread` / `
|
|
582
|
+
main-side worker-thread machinery (`createThread` / `Job`), driven
|
|
583
583
|
through `createNodeWorker` over real worker threads (no mocking): a round-trip and a
|
|
584
584
|
batch over a small pool; the concurrency cap and the live-thread cap + idle reuse; a
|
|
585
585
|
throwing handler rejecting with its error, and re-running under `retries`; explicit enqueue
|
|
@@ -191,14 +191,10 @@ The **browser** backends ship in [`src/browser`](../src/browser), published thro
|
|
|
191
191
|
|
|
192
192
|
The browser backends also publish supporting members through `@orkestrel/workflow/browser`: the `POST_TASK_PRIORITY` map `BrowserScheduler` reads to translate a portable `SchedulerPriority` into a `scheduler.postTask` priority level, and the `IdleInterface` shape of the feature-detected `requestIdleCallback` / `cancelIdleCallback` pair `IdleScheduler` narrows to (or resolves to `undefined`, falling back to a macrotask).
|
|
193
193
|
|
|
194
|
-
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 `\|`.
|
|
195
|
-
|
|
196
194
|
| Name | Kind | Signature | Summary |
|
|
197
195
|
| --------------- | --------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
198
196
|
| `IdleInterface` | interface | `{ request, cancel }` | Declares the narrowed `requestIdleCallback` / `cancelIdleCallback` pair feature-detected off `globalThis`. |
|
|
199
197
|
|
|
200
|
-
A `Shape` cell holds the constant's declared type.
|
|
201
|
-
|
|
202
198
|
| Name | Kind | Signature | Summary |
|
|
203
199
|
| -------------------- | ----- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
204
200
|
| `POST_TASK_PRIORITY` | const | `Readonly<Record<SchedulerPriority, string>>` | Maps each portable `SchedulerPriority` to the browser-native `postTask` priority — `user` to `'user-blocking'`, `normal` to `'user-visible'`, and `background` to `'background'`. |
|
|
@@ -242,7 +238,9 @@ Centralized, exhaustively unit-tested helpers and guards. The status derivations
|
|
|
242
238
|
Generic exact-JSON ownership comes directly from [`@orkestrel/contract`](contract.md):
|
|
243
239
|
consumers import its `JSONRecord`, `cloneJSONValue`, and `cloneJSONRecord` from their
|
|
244
240
|
originating package. Workflow does not re-export them. Its domain cloners below add
|
|
245
|
-
workflow-specific validation and translate ownership failures into `WorkflowError`.
|
|
241
|
+
workflow-specific validation and translate ownership failures into `WorkflowError`. The
|
|
242
|
+
`success` and `failure` constructors that box a `Result`, and the `errorToMessage` function
|
|
243
|
+
that renders a thrown value as a failure message, also come from `@orkestrel/contract`.
|
|
246
244
|
|
|
247
245
|
| Name | Kind | Signature | Summary |
|
|
248
246
|
| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
@@ -267,9 +265,6 @@ workflow-specific validation and translate ownership failures into `WorkflowErro
|
|
|
267
265
|
| `isTaskActivity` | function | `(value: unknown) => value is TaskActivity` | Tests whether an unknown value is valid persisted task activity. |
|
|
268
266
|
| `captureWorkflowOptions` | function | `(options?: WorkflowOptions) => WorkflowOptions` | Captures every top-level `WorkflowOptions` value exactly once into an owned plain bag. |
|
|
269
267
|
| `createHostSchedule` | function | `(start: HostScheduleFunction, signal?: AbortSignal) => Promise<void>` | Schedules one cancellable host operation behind an owned settlement signal. |
|
|
270
|
-
| `success` | function | `<T>(value: T) => Success<T>` | Boxes a value as a `Success` — the graceful outcome half of a `Result`. |
|
|
271
|
-
| `failure` | function | `<E>(error: E) => Failure<E>` | Boxes an error as a `Failure` — the graceful outcome half of a `Result`. |
|
|
272
|
-
| `errorToMessage` | function | `(error: unknown) => string` | Normalizes an unknown thrown value to a non-empty persistence-safe message. |
|
|
273
268
|
| `findFailure` | function | `(results: readonly TaskResult[]) => TaskResult \| undefined` | Finds the first `TaskResult` in a positional list whose boxed outcome is a `Failure` — the pure scan shared by a phase's and a workflow's derived-`failed` `fail`-event lookup. |
|
|
274
269
|
| `buildWorkflowContext` | function | `(node: WorkflowContext) => WorkflowContext` | Builds a `WorkflowContext` — the identity every level inherits — from a node's `id` / `name` / optional `description`. |
|
|
275
270
|
| `buildPhaseContext` | function | `(workflow: WorkflowContext, node: WorkflowContext) => PhaseContext` | Builds a `PhaseContext` — a phase's own identity plus a back-reference to its workflow — from the parent `WorkflowContext` and the phase node's identity. |
|
|
@@ -302,7 +297,6 @@ The exact snapshot boundary is also available as composable public leaves:
|
|
|
302
297
|
import {
|
|
303
298
|
cloneWorkflowSnapshot,
|
|
304
299
|
createWorkflow,
|
|
305
|
-
errorToMessage,
|
|
306
300
|
hasWorkflowHandlers,
|
|
307
301
|
isLifecycleStatus,
|
|
308
302
|
isOwnedWorkflowSnapshot,
|
|
@@ -341,7 +335,6 @@ if (phase !== undefined && task !== undefined) {
|
|
|
341
335
|
matchesDescription(snapshot.description, workflow.description)
|
|
342
336
|
hasWorkflowHandlers(snapshot, functions)
|
|
343
337
|
scanSnapshotContext({ ...snapshot, bail: 'invalid' })
|
|
344
|
-
errorToMessage(new Error('provider failed'))
|
|
345
338
|
recoverWorkflowSnapshot(snapshot)
|
|
346
339
|
```
|
|
347
340
|
|
|
@@ -365,20 +358,16 @@ resolveTaskSilence(0, 30_000) // undefined: the task explicitly disables inherit
|
|
|
365
358
|
|
|
366
359
|
`createWorkflowContract` derives its lockstep JSON Schema, guard, parser, and generator from these shape values. They agree with the hand-written definition interfaces (the source of truth); a round-trip parity test (`generate → is → parse`) guards against drift.
|
|
367
360
|
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
|
371
|
-
|
|
|
372
|
-
| `
|
|
373
|
-
| `
|
|
374
|
-
| `
|
|
375
|
-
| `taskUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of a `TaskUpdate` — a partial edit to a `pending` task's `name` / `description`, both optional. |
|
|
376
|
-
| `phaseUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `PhaseUpdate` — a partial edit to a `pending` phase's `name` / `description` / `concurrency` / `bail`, all optional. |
|
|
361
|
+
| Name | Kind | Signature | Summary |
|
|
362
|
+
| --------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
363
|
+
| `taskDefinitionShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>` | Describes the shape of a `TaskDefinition` — identity plus an optional `behavior` behavior reference (a plain registry-key string, min length 1). `description` is optional prose. |
|
|
364
|
+
| `phaseShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tasks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `PhaseDefinition` — identity, its ordered `taskDefinitionShape` tasks, and an optional positive-integer `concurrency` throttle (max tasks in flight; omitted ⇒ unbounded). |
|
|
365
|
+
| `workflowShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; phases: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tasks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `WorkflowDefinition` — the contract root: identity, its ordered `phaseShape` phases, and the optional `bail` boolean failure policy (the literal pair `true`/`false`, the runtime mirror of the boolean toggle; omitted ⇒ the graceful default). |
|
|
366
|
+
| `taskUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of a `TaskUpdate` — a partial edit to a `pending` task's `name` / `description`, both optional. |
|
|
367
|
+
| `phaseUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `PhaseUpdate` — a partial edit to a `pending` phase's `name` / `description` / `concurrency` / `bail`, all optional. |
|
|
377
368
|
|
|
378
369
|
### Constants
|
|
379
370
|
|
|
380
|
-
A `Shape` cell holds the constant's declared type.
|
|
381
|
-
|
|
382
371
|
| Name | Kind | Signature | Summary |
|
|
383
372
|
| --------------------------- | ----- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
384
373
|
| `DEFAULT_BAIL` | const | `false` | Names the default `WorkflowDefinition.bail`, `false` — the graceful policy that records a leaf failure and finishes every phase. |
|
|
@@ -392,8 +381,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
392
381
|
|
|
393
382
|
### Types
|
|
394
383
|
|
|
395
|
-
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 `\|`.
|
|
396
|
-
|
|
397
384
|
| Name | Kind | Signature | Summary |
|
|
398
385
|
| ------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
399
386
|
| `TaskDefinition` | interface | `{ id, name, description?, behavior?, retries?, timeout? }` | Represents the serializable definition of one task — its identity, an optional reference to the behavior it runs, and its optional per-task `retries` and `timeout` overrides. |
|
|
@@ -406,8 +393,8 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
406
393
|
| `PhaseInput` | type | `Partial<PhaseContext>` | Represents the minimal data to create a phase context — a partial `PhaseContext`. |
|
|
407
394
|
| `TaskInput` | interface | `{ metadata? }` | Represents the minimal data to create a task context — a partial `TaskContext` plus the open `metadata` bag the task stores and snapshots without interpreting it. |
|
|
408
395
|
| `TaskProgress` | interface | `{ progress, total?, message? }` | Represents the aggregate progress most recently reported by a running task. |
|
|
409
|
-
| `TaskClaim` | interface | `{ id, name, started }` | Represents one identified thing a running task claims active, with the moment the claim began — the shape `
|
|
410
|
-
| `
|
|
396
|
+
| `TaskClaim` | interface | `{ id, name, started }` | Represents one identified thing a running task claims active, with the moment the claim began — the shape `TaskActivityOperation` and `TaskConstraint` share. |
|
|
397
|
+
| `TaskActivityOperation` | interface | `{}` | Represents one operation claimed active when a running task's complete frame was accepted. |
|
|
411
398
|
| `TaskConstraint` | interface | `{}` | Represents one constraint claimed active when a running task's complete frame was accepted. |
|
|
412
399
|
| `TaskActivityInput` | interface | `{ note?, progress?, operations?, constraints? }` | Represents one complete replacement of a running task's observable activity, an omitted collection meaning an empty one. |
|
|
413
400
|
| `TaskActivity` | interface | `{ note?, progress?, operations, constraints, updated }` | Represents the bounded, JSON-serializable activity most recently accepted from a task reporter. |
|
|
@@ -1565,7 +1552,7 @@ A successful run fires `start` → `unit`/`settle` per unit → `finish`. A fail
|
|
|
1565
1552
|
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — status/lineage/snapshot helpers, bounded silence inheritance, `createHostSchedule` setup/cancellation race arbitration with exact falsy failures, hostile caller signal methods, and throwing cancellation closures after caller abort or host failure, plus the snapshot-decode leaves: remaining-budget recovery, established strict halt boundaries, exhausted recovery failures, monotonic stamps, exact-restore separation, and hostile inputs.
|
|
1566
1553
|
- [`tests/src/core/cloners.test.ts`](../tests/src/core/cloners.test.ts) — immutable activity cloning, hostile/revoked proxy containment, one-read getters, no alias retention, stamp-vs-restore `updated` handling, and exact wrong-storage-key `RESTORE` evidence.
|
|
1567
1554
|
- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — total activity, task-failure, task-result, and owned-snapshot guards over valid, malformed, cyclic, throwing-proxy/getter/ownKeys, and revoked inputs.
|
|
1568
|
-
- [`tests/src/core/shapers.test.ts`](../tests/src/core/shapers.test.ts) — the shape descriptors: the `
|
|
1555
|
+
- [`tests/src/core/shapers.test.ts`](../tests/src/core/shapers.test.ts) — the shape descriptors: the `taskDefinitionShape` / `phaseShape` / `workflowShape` mirroring the hand-written definition interfaces, the per-field `description`s riding the `behavior` string + key fields (Rank 1), `describedLiteral`.
|
|
1569
1556
|
- [`tests/src/core/tasks/Task.test.ts`](../tests/src/core/tasks/Task.test.ts) — lifecycle plus whole-frame activity, validation/immutability, pulse, repeatable silence rearming, task signal, terminal cleanup, and cooperative pause.
|
|
1570
1557
|
- [`tests/src/core/phases/Phase.test.ts`](../tests/src/core/phases/Phase.test.ts) — the derived middle tier: child-transition cascade, `skip` / `stop` override, results, snapshot/restore, and isolated lifecycle emission including idempotent pause/resume.
|
|
1571
1558
|
- [`tests/src/core/Workflow.test.ts`](../tests/src/core/Workflow.test.ts) — the derived root: bail-aware cascade, result tree, override, snapshot/restore, teardown, and isolated lifecycle emission including idempotent pause/resume.
|