@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.
Files changed (78) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +57 -9
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +22 -2
  3. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +5 -5
  4. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +67 -5
  5. package/dist/bin/main.js +5 -5
  6. package/dist/bin/main.js.map +1 -1
  7. package/dist/host/agents/orchestration.md +16 -11
  8. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -4
  9. package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +2 -1
  10. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +65 -9
  11. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +28 -2
  12. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -1
  13. package/dist/host/agents/skills/orkestrel-harden/SKILL.md +8 -8
  14. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +3 -3
  15. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +2 -2
  16. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +10 -8
  17. package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
  18. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -8
  19. package/dist/host/agents/skills/orkestrel-publish/references/window.md +5 -1
  20. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +5 -5
  21. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +86 -7
  22. package/dist/host/claude/AGENTS.md +1 -1
  23. package/dist/host/claude/agents/analyst.md +1 -1
  24. package/dist/host/claude/agents/opus.md +7 -6
  25. package/dist/host/claude/agents/orkestrel.md +26 -26
  26. package/dist/host/claude/agents/planner.md +3 -3
  27. package/dist/host/claude/agents/reviewer.md +3 -3
  28. package/dist/host/claude/agents/verifier.md +1 -1
  29. package/dist/host/claude/rules/campaign.md +3 -2
  30. package/dist/host/claude/rules/names.md +13 -7
  31. package/dist/host/claude/rules/tests.md +1 -1
  32. package/dist/host/claude/rules/workspace.md +9 -0
  33. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  34. package/dist/host/codex/agents/analyst.toml +2 -5
  35. package/dist/host/codex/agents/opus.toml +5 -3
  36. package/dist/host/codex/agents/planner.toml +6 -5
  37. package/dist/host/codex/agents/reviewer.toml +4 -7
  38. package/dist/host/codex/agents/verifier.toml +2 -2
  39. package/dist/host/dotfiles/gitignore +1 -2
  40. package/dist/host/guides/agent.md +5 -5
  41. package/dist/host/guides/brief.md +7 -15
  42. package/dist/host/guides/browser.md +1 -1
  43. package/dist/host/guides/capture.md +2 -2
  44. package/dist/host/guides/console.md +4 -30
  45. package/dist/host/guides/guide.md +0 -1
  46. package/dist/host/guides/interpret.md +165 -182
  47. package/dist/host/guides/lsp.md +26 -51
  48. package/dist/host/guides/mcp.md +220 -276
  49. package/dist/host/guides/middleware.md +14 -22
  50. package/dist/host/guides/ollama.md +1 -3
  51. package/dist/host/guides/probe.md +71 -80
  52. package/dist/host/guides/program.md +26 -35
  53. package/dist/host/guides/qualifier.md +0 -6
  54. package/dist/host/guides/queue.md +0 -4
  55. package/dist/host/guides/rater.md +6 -12
  56. package/dist/host/guides/relation.md +0 -2
  57. package/dist/host/guides/scaffold.md +18 -9
  58. package/dist/host/guides/sea.md +47 -51
  59. package/dist/host/guides/server.md +15 -19
  60. package/dist/host/guides/terminal.md +0 -26
  61. package/dist/host/guides/toolbox.md +0 -10
  62. package/dist/host/guides/worker.md +57 -57
  63. package/dist/host/guides/workflow.md +13 -26
  64. package/dist/host/guides/workspace.md +15 -21
  65. package/dist/host/manifest.json +63 -483
  66. package/dist/host/tests/config.test.ts +7 -0
  67. package/dist/src/core/index.cjs +13 -46
  68. package/dist/src/core/index.cjs.map +1 -1
  69. package/dist/src/core/index.js +13 -46
  70. package/dist/src/core/index.js.map +1 -1
  71. package/dist/src/server/index.cjs +10 -9
  72. package/dist/src/server/index.cjs.map +1 -1
  73. package/dist/src/server/index.d.cts +12 -8
  74. package/dist/src/server/index.d.ts +12 -8
  75. package/dist/src/server/index.js +10 -9
  76. package/dist/src/server/index.js.map +1 -1
  77. package/package.json +5 -5
  78. /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 | Summary |
50
- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
51
- | `createWorker` | function | `<TInput, TResource, TResult>(options: WorkerOptions<TInput, TResource, TResult>) => WorkerInterface<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>) => WorkerInterface<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`. |
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, Dispatch, isReply } from '@orkestrel/worker/server'
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 Dispatch(thread, 21, { id: 'job-1', signal: controller.signal }, isNumber)
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 | Kind | Signature | Summary |
92
- | ---------- | ----- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
93
- | `Dispatch` | class | `new <TResult>(thread: NodeThread, input: unknown, context: QueueContext, result: Guard<TResult>) => Dispatch<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>) => WorkerInterface<TInput, TResult>` | Represents a resource-backed job worker — a thin facade composing a `Queue` (`@orkestrel/queue`) with a `Pool` (`@orkestrel/pool`). |
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 | Summary |
103
- | -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
104
- | `WorkerHandler` | type | `(input: TInput, resource: TResource, context: QueueContext) => Promise<TResult> \| TResult` | Runs one worker job with a leased pool resource. |
105
- | `WorkerOptions` | interface | `{ on?, error?, handler, pool, concurrency?, retries?, timeout?, store? }` | Configures `createWorker`. |
106
- | `WorkerInterface` | interface | `{ emitter, count, active, paused, stopped, enqueue(), restore(), start(), stop(), pause(), resume(), abort(), clear(), destroy() }` | Represents the job-worker contract a consumer holds — a `Queue` whose handler runs each job against a pooled resource. |
107
- | `WorkerEventMap` | type | `{ readonly enqueue: readonly [id: string]; readonly start: readonly [id: string]; readonly retry: readonly [id: string, attempt: number]; readonly success: readonly [id: string, result: TResult]; readonly failure: readonly [id: string, error: unknown]; readonly abort: readonly [reason: unknown]; readonly drain: readonly []; }` | Represents the push observation surface of a `WorkerInterface` — the job lifecycle a fire-and-forget observer subscribes to. |
108
- | `NodeWorkerOptions` | interface | `{ on?, error?, script, input, result, workerData?, concurrency?, retries?, timeout?, store? }` | Configures `createNodeWorker` — a CPU-parallel worker over `node:worker_threads`. |
109
- | `ServeWorkerOptions` | interface | `{ input, handler }` | Configures `serveWorker` — the worker-side entry a thread script registers. |
110
- | `NodeThread` | interface | `{ worker, alive, death }` | Represents a live worker thread plus its latched liveness state — the pooled resource a `createNodeWorker` leases per job. |
111
- | `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. |
112
-
113
- The `emitter` / `count` / `active` / `paused` / `stopped` members of `WorkerInterface` are
114
- `readonly` data members (Surface rows, earlier) — `emitter` is the typed push observation
115
- surface (see [Observing](#observing)); the call-signature methods are documented under
116
- [Methods](#methods). `Queue` / `Pool` themselves — and their own options, event maps, and
117
- stores — are documented in their own packages: [queue.md](queue.md) / [pool.md](pool.md).
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 `WorkerInterface` — every call-signature member listed (its
122
- `readonly` data members stay Surface rows). `Worker` implements `WorkerInterface`
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
- #### `WorkerInterface`
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 `WorkerEventMap<TResult>`
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 `WorkerInterface` — exhaustive, both directions — and `Worker` exposes
192
- the same public methods as its interface, no more.
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 `Dispatch` against the leased thread. `TInput` and
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 `Dispatch` narrows each reply
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 `Dispatch` checks that latch
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 dispatch listeners, and those events will never fire again; without the latch
230
- the job would wait forever. A death mid-flight still rejects through the dispatch's own
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
- dispatch, and is detached with the other per-job listeners. A death before `online`
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 dispatch: `serveWorker` replaces the failed success post with a clone-safe
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 dispatch,
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
- `WorkerInterface`, so it inherits the Worker's `emitter` unchanged (clause 3).
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 `WorkerInterface`, so its methods, lifecycle, concurrency, retries,
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 `WorkerEventMap` listeners at construction, and `error` to receive a listener's throw
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 | Events |
378
- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
379
- | `WorkerEventMap<TResult>` | `enqueue(id)` · `start(id)` · `retry(id, attempt)` · `success(id, result)` · `failure(id, error)` · `abort(reason)` · `drain()` |
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
- `WorkerInterface` ↔ `Worker` method bijection, and the equality gate: every `Summary`
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, typed instance end to end and honours its options +
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, then teardown), the `on` hooks wired at construction with a
580
- listener throw routed to `error`, and the option snapshot retained across jobs.
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` / `Dispatch`), driven
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
- A `Shape` cell holds the constant's declared type.
369
-
370
- | Name | Kind | Signature | Summary |
371
- | ------------------ | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
372
- | `taskShape` | 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. |
373
- | `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 `taskShape` tasks, and an optional positive-integer `concurrency` throttle (max tasks in flight; omitted ⇒ unbounded). |
374
- | `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). |
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 `TaskOperation` and `TaskConstraint` share. |
410
- | `TaskOperation` | interface | `{}` | Represents one operation claimed active when a running task's complete frame was accepted. |
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 `taskShape` / `phaseShape` / `workflowShape` mirroring the hand-written definition interfaces, the per-field `description`s riding the `behavior` string + key fields (Rank 1), `describedLiteral`.
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.