@orkestrel/scaffold 0.0.119 → 0.0.121

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/dist/bin/main.js +19 -19
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  4. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  6. package/dist/host/claude/agents/orkestrel.md +52 -51
  7. package/dist/host/claude/rules/tests.md +2 -2
  8. package/dist/host/claude/rules/typescript.md +2 -3
  9. package/dist/host/guides/abort.md +0 -4
  10. package/dist/host/guides/agent.md +5 -5
  11. package/dist/host/guides/brief.md +7 -15
  12. package/dist/host/guides/browser.md +1 -1
  13. package/dist/host/guides/budget.md +1 -5
  14. package/dist/host/guides/capture.md +2 -2
  15. package/dist/host/guides/codec.md +18 -3
  16. package/dist/host/guides/console.md +4 -30
  17. package/dist/host/guides/contract.md +23 -44
  18. package/dist/host/guides/csv.md +86 -93
  19. package/dist/host/guides/database.md +0 -4
  20. package/dist/host/guides/emitter.md +0 -2
  21. package/dist/host/guides/form.md +26 -47
  22. package/dist/host/guides/guide.md +0 -1
  23. package/dist/host/guides/html.md +3 -7
  24. package/dist/host/guides/indexeddb.md +28 -32
  25. package/dist/host/guides/interpret.md +165 -182
  26. package/dist/host/guides/jsonrpc.md +187 -0
  27. package/dist/host/guides/lsp.md +26 -51
  28. package/dist/host/guides/markdown.md +132 -141
  29. package/dist/host/guides/mcp.md +220 -276
  30. package/dist/host/guides/middleware.md +14 -22
  31. package/dist/host/guides/msg.md +47 -63
  32. package/dist/host/guides/ndjson.md +0 -4
  33. package/dist/host/guides/ollama.md +1 -3
  34. package/dist/host/guides/pool.md +0 -4
  35. package/dist/host/guides/probe.md +71 -80
  36. package/dist/host/guides/process.md +71 -79
  37. package/dist/host/guides/program.md +26 -35
  38. package/dist/host/guides/qualifier.md +0 -6
  39. package/dist/host/guides/queue.md +0 -4
  40. package/dist/host/guides/rater.md +6 -12
  41. package/dist/host/guides/reason.md +30 -36
  42. package/dist/host/guides/relation.md +0 -2
  43. package/dist/host/guides/router.md +11 -18
  44. package/dist/host/guides/scaffold.md +148 -144
  45. package/dist/host/guides/sea.md +47 -51
  46. package/dist/host/guides/server.md +15 -19
  47. package/dist/host/guides/sqlite.md +0 -4
  48. package/dist/host/guides/sse.md +6 -10
  49. package/dist/host/guides/table.md +481 -493
  50. package/dist/host/guides/template.md +0 -4
  51. package/dist/host/guides/terminal.md +0 -26
  52. package/dist/host/guides/test.md +46 -66
  53. package/dist/host/guides/timeout.md +0 -6
  54. package/dist/host/guides/tool.md +2 -6
  55. package/dist/host/guides/toolbox.md +0 -10
  56. package/dist/host/guides/websocket.md +0 -4
  57. package/dist/host/guides/worker.md +57 -57
  58. package/dist/host/guides/workflow.md +13 -26
  59. package/dist/host/guides/workspace.md +15 -21
  60. package/dist/host/manifest.json +64 -909
  61. package/dist/src/core/index.cjs +128 -181
  62. package/dist/src/core/index.cjs.map +1 -1
  63. package/dist/src/core/index.d.cts +213 -213
  64. package/dist/src/core/index.d.ts +213 -213
  65. package/dist/src/core/index.js +117 -170
  66. package/dist/src/core/index.js.map +1 -1
  67. package/dist/src/server/index.cjs +35 -34
  68. package/dist/src/server/index.cjs.map +1 -1
  69. package/dist/src/server/index.d.cts +62 -58
  70. package/dist/src/server/index.d.ts +62 -58
  71. package/dist/src/server/index.js +36 -35
  72. package/dist/src/server/index.js.map +1 -1
  73. package/package.json +13 -13
@@ -64,8 +64,6 @@ Concrete `DefinitionStoreInterface` implementations (AGENTS' Stores rule, point-
64
64
 
65
65
  The total `(value: unknown) => value is T` guards this package applies at its untrusted boundaries — an authored lineage, a frozen agent adapter, the small-model column DSL, and a persisted database definition read back from a store.
66
66
 
67
- In a guard table a `Shape` cell holds the type the guard narrows to.
68
-
69
67
  | Name | Kind | Signature | Summary |
70
68
  | ---------------------- | -------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
71
69
  | `isWorkflowLineage` | function | `(value: unknown) => value is WorkflowLineage` | Narrows an unknown value to a valid alternating workflow lineage. |
@@ -115,8 +113,6 @@ The `TableSpec` column DSL compiled into the live `@orkestrel/database` `TableMa
115
113
 
116
114
  The shape values each `create*Tool` factory (and `createWorkflowDraftContract`) compiles into the lockstep guard / parser / JSON Schema outputs under AGENTS' narrow-untrusted-input-with-guards rule; `agentToolShape` agrees with the hand-written `AgentToolArguments`, the source of truth.
117
115
 
118
- A `Shape` cell holds the constant's declared type.
119
-
120
116
  | Name | Kind | Signature | Summary |
121
117
  | ---------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
122
118
  | `agentToolShape` | const | `import("@orkestrel/contract").ObjectShape<{ task: import("@orkestrel/contract").StringShape; provider: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tools: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>>; system: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of `AgentToolArguments` — `createAgentTool`'s advertised `parameters`. |
@@ -147,8 +143,6 @@ A `Shape` cell holds the constant's declared type.
147
143
 
148
144
  ### Constants
149
145
 
150
- A `Shape` cell holds the constant's declared type.
151
-
152
146
  | Name | Kind | Signature | Summary |
153
147
  | ------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
154
148
  | `AGENT_TOOL_NAME` | const | `"agent"` | Holds the name `createAgentTool` advertises by default, `'agent'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
@@ -190,8 +184,6 @@ A `Shape` cell holds the constant's declared type.
190
184
 
191
185
  ### Types
192
186
 
193
- 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 `\|`.
194
-
195
187
  | Name | Kind | Signature | Summary |
196
188
  | -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
197
189
  | `TaskDraft` | interface | `{ id?, name?, description?, behavior?, retries?, timeout? }` | Represents a draft task — a `TaskDefinition` (`@orkestrel/workflow`) with optional `id` and `name`. |
@@ -234,8 +226,6 @@ The wire bridge for a `TerminalManagerInterface` — a GET SSE stream and a POST
234
226
 
235
227
  The POST endpoint takes `{ id, values }`, admits the body only when `id` is a nonempty string and `values` passes `@orkestrel/form`'s `isFormValues`, and returns the manager's own answer `Result` as a JSON body — `200` accepted, `422` an `'unknown'` / `'rejected'` outcome, `404` a `'target'` outcome. The body is what carries a rejection's per-field `errors` back to the answering client, so `PromptClient` can re-render the failed fields instead of guessing from a status code.
236
228
 
237
- 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 `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A `Shape` cell holds the constant's declared type.
238
-
239
229
  | Name | Kind | Signature | Summary |
240
230
  | ----------------------- | --------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
241
231
  | `createTerminalRoutes` | function | `(manager: TerminalManagerInterface, options?: TerminalRoutesOptions) => readonly TerminalRoute[]` | Builds the GET SSE stream and POST answer routes that bridge a terminal manager onto the wire. |
@@ -74,8 +74,6 @@ Narrow the header before the call. `sec-websocket-key` is typed `string | undefi
74
74
 
75
75
  ### Constants
76
76
 
77
- A `Shape` cell holds the constant's declared type.
78
-
79
77
  | Name | Kind | Signature | Summary |
80
78
  | ----------------------------------- | ----- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
81
79
  | `WEBSOCKET_GUID` | const | `"258EAFA5-E914-47DA-95CA-C5AB0DC85B11"` | Names the accept GUID concatenated to a client's `Sec-WebSocket-Key` before the accept hash, '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'. |
@@ -103,8 +101,6 @@ A `Shape` cell holds the constant's declared type.
103
101
 
104
102
  ### Types
105
103
 
106
- 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 `\|`.
107
-
108
104
  | Name | Kind | Signature | Summary |
109
105
  | ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
110
106
  | `WebSocketReadyState` | type | `0 \| 1 \| 2 \| 3` | Represents a WebSocket ready state — the stage a connection has reached between the handshake and the socket's end. |
@@ -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