@orkestrel/scaffold 0.0.119 → 0.0.121
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/main.js +19 -19
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
- package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +52 -51
- package/dist/host/claude/rules/tests.md +2 -2
- package/dist/host/claude/rules/typescript.md +2 -3
- package/dist/host/guides/abort.md +0 -4
- package/dist/host/guides/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/console.md +4 -30
- package/dist/host/guides/contract.md +23 -44
- package/dist/host/guides/csv.md +86 -93
- package/dist/host/guides/database.md +0 -4
- package/dist/host/guides/emitter.md +0 -2
- package/dist/host/guides/form.md +26 -47
- package/dist/host/guides/guide.md +0 -1
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +148 -144
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- package/dist/host/guides/sqlite.md +0 -4
- package/dist/host/guides/sse.md +6 -10
- package/dist/host/guides/table.md +481 -493
- package/dist/host/guides/template.md +0 -4
- package/dist/host/guides/terminal.md +0 -26
- package/dist/host/guides/test.md +46 -66
- package/dist/host/guides/timeout.md +0 -6
- package/dist/host/guides/tool.md +2 -6
- package/dist/host/guides/toolbox.md +0 -10
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +64 -909
- package/dist/src/core/index.cjs +128 -181
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +213 -213
- package/dist/src/core/index.d.ts +213 -213
- package/dist/src/core/index.js +117 -170
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +35 -34
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +62 -58
- package/dist/src/server/index.d.ts +62 -58
- package/dist/src/server/index.js +36 -35
- package/dist/src/server/index.js.map +1 -1
- package/package.json +13 -13
|
@@ -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
|
|
50
|
-
| ---------------------- | -------- |
|
|
51
|
-
| `createWorker` | function | `<TInput, TResource, TResult>(options: WorkerOptions<TInput, TResource, TResult>) =>
|
|
52
|
-
| `createJSONQueueStore` | function | `<TInput extends ContractShape>(path: string, input: TInput) => QueueStoreInterface<Infer<TInput>>`
|
|
53
|
-
| `createNodeWorker` | function | `<TInput, TResult>(options: NodeWorkerOptions<TInput, TResult>) =>
|
|
54
|
-
| `serveWorker` | function | `<TInput, TResult>(options: ServeWorkerOptions<TInput, TResult>) => void`
|
|
49
|
+
| Name | Kind | Signature | Summary |
|
|
50
|
+
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
51
|
+
| `createWorker` | function | `<TInput, TResource, TResult>(options: WorkerOptions<TInput, TResource, TResult>) => QueueInterface<TInput, TResult>` | Creates a resource-backed job worker — a `Queue` (`@orkestrel/queue`) composed with a `Pool` (`@orkestrel/pool`), where each enqueued input runs through the handler against an automatically acquired pooled resource released when the job settles. |
|
|
52
|
+
| `createJSONQueueStore` | function | `<TInput extends ContractShape>(path: string, input: TInput) => QueueStoreInterface<Infer<TInput>>` | Creates a persistent JSON-file `QueueStoreInterface` — the core `createDatabaseQueueStore` over a server `createJSONDriver`. |
|
|
53
|
+
| `createNodeWorker` | function | `<TInput, TResult>(options: NodeWorkerOptions<TInput, TResult>) => QueueInterface<TInput, TResult>` | Creates a CPU-parallel worker over `node:worker_threads` — a thin specialization of the core `createWorker` whose pooled resource is a worker thread. |
|
|
54
|
+
| `serveWorker` | function | `<TInput, TResult>(options: ServeWorkerOptions<TInput, TResult>) => void` | Registers a worker-thread handler — the worker-side half of `createNodeWorker`. |
|
|
55
55
|
|
|
56
56
|
### Threads
|
|
57
57
|
|
|
@@ -61,14 +61,14 @@ these to drive one thread yourself; `createNodeWorker` is the entry point for po
|
|
|
61
61
|
work. Driving a thread by hand:
|
|
62
62
|
|
|
63
63
|
```ts
|
|
64
|
-
import { createThread,
|
|
64
|
+
import { createThread, isReply, Job } from '@orkestrel/worker/server'
|
|
65
65
|
|
|
66
66
|
const isNumber = (value: unknown): value is number => typeof value === 'number'
|
|
67
67
|
|
|
68
68
|
const thread = await createThread(new URL('./double.ts', import.meta.url))
|
|
69
69
|
const controller = new AbortController()
|
|
70
70
|
try {
|
|
71
|
-
const job = new
|
|
71
|
+
const job = new Job(thread, 21, { id: 'job-1', signal: controller.signal }, isNumber)
|
|
72
72
|
console.log(await job.promise) // 42
|
|
73
73
|
console.log(isReply({ id: 'reply-1', ok: true, value: 42 }, 'reply-1')) // true
|
|
74
74
|
console.log(isReply({ id: 'reply-1', ok: true, value: 42 }, 'other')) // false
|
|
@@ -88,41 +88,38 @@ The thread-level functions behind `createNodeWorker`:
|
|
|
88
88
|
|
|
89
89
|
The classes the core and server faces export:
|
|
90
90
|
|
|
91
|
-
| Name
|
|
92
|
-
|
|
|
93
|
-
| `
|
|
94
|
-
| `Worker`
|
|
91
|
+
| Name | Kind | Signature | Summary |
|
|
92
|
+
| -------- | ----- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
93
|
+
| `Job` | class | `new <TResult>(thread: NodeThread, input: unknown, context: QueueContext, result: Guard<TResult>) => Job<TResult>` | Represents one dispatched worker-thread job — the lifecycle entity behind a job posted to a leased `NodeThread`, whose `promise` settles with the narrowed reply. |
|
|
94
|
+
| `Worker` | class | `new <TInput, TResource, TResult>(options: WorkerOptions<TInput, TResource, TResult>) => QueueInterface<TInput, TResult>` | Represents a resource-backed job worker — a thin facade composing a `Queue` (`@orkestrel/queue`) with a `Pool` (`@orkestrel/pool`). |
|
|
95
95
|
|
|
96
96
|
### Types
|
|
97
97
|
|
|
98
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
|
|
99
|
-
|
|
100
98
|
Each type and interface the core and server faces publish:
|
|
101
99
|
|
|
102
|
-
| Name | Kind | Signature
|
|
103
|
-
| -------------------- | --------- |
|
|
104
|
-
| `WorkerHandler` | type | `(input: TInput, resource: TResource, context: QueueContext) => Promise<TResult> \| TResult`
|
|
105
|
-
| `WorkerOptions` | interface | `{ on?, error?, handler, pool, concurrency?, retries?, timeout?, store? }`
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
`
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
100
|
+
| Name | Kind | Signature | Summary |
|
|
101
|
+
| -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
102
|
+
| `WorkerHandler` | type | `(input: TInput, resource: TResource, context: QueueContext) => Promise<TResult> \| TResult` | Runs one worker job with a leased pool resource. |
|
|
103
|
+
| `WorkerOptions` | interface | `{ on?, error?, handler, pool, concurrency?, retries?, timeout?, store? }` | Configures `createWorker`. |
|
|
104
|
+
| `NodeWorkerOptions` | interface | `{ on?, error?, script, input, result, workerData?, concurrency?, retries?, timeout?, store? }` | Configures `createNodeWorker` — a CPU-parallel worker over `node:worker_threads`. |
|
|
105
|
+
| `ServeWorkerOptions` | interface | `{ input, handler }` | Configures `serveWorker` — the worker-side entry a thread script registers. |
|
|
106
|
+
| `NodeThread` | interface | `{ worker, alive, death }` | Represents a live worker thread plus its latched liveness state — the pooled resource a `createNodeWorker` leases per job. |
|
|
107
|
+
| `Reply` | type | `{ readonly id: string; readonly ok: true; readonly value: unknown; } \| { readonly id: string; readonly ok: false; readonly error: string; }` | Represents a thread→main reply envelope — a success carrying an opaque `value`, or a failure with a message — the reply half of the wire protocol `createNodeWorker` posts and `serveWorker` answers. |
|
|
108
|
+
|
|
109
|
+
`Worker` implements `@orkestrel/queue`'s `QueueInterface`, and `createWorker` and
|
|
110
|
+
`createNodeWorker` return that interface. Its `emitter` / `count` / `active` / `paused` / `stopped`
|
|
111
|
+
members are `readonly` data members: `emitter` is the typed push observation surface
|
|
112
|
+
carrying the queue's `QueueEventMap` (see [Observing](#observing)), and the call-signature
|
|
113
|
+
methods are documented under [Methods](#methods). `Queue` / `Pool` themselves — and their
|
|
114
|
+
own options, event maps, and stores — are documented in their own packages:
|
|
115
|
+
[queue.md](queue.md) / [pool.md](pool.md).
|
|
118
116
|
|
|
119
117
|
## Methods
|
|
120
118
|
|
|
121
|
-
The public methods of `
|
|
122
|
-
|
|
123
|
-
exactly, so this doubles as the class's instance-method surface.
|
|
119
|
+
The public methods of `Worker` — every call-signature member of `QueueInterface` it
|
|
120
|
+
implements, with no method beyond them.
|
|
124
121
|
|
|
125
|
-
#### `
|
|
122
|
+
#### `Worker`
|
|
126
123
|
|
|
127
124
|
| Method | Returns | Summary |
|
|
128
125
|
| --------- | ------------------ | ------------------------------------------------------------------------------------------------------------------ |
|
|
@@ -177,7 +174,7 @@ These invariants hold across `src/core` ↔ `worker.md`:
|
|
|
177
174
|
settlement serially, aggregates the queue's failure and the pool's in that order, and
|
|
178
175
|
destroys the worker emitter last.
|
|
179
176
|
3. **Observable — the queue lifecycle re-exposed.** The `Worker` owns a typed `Emitter`
|
|
180
|
-
exposed as `readonly emitter` carrying `
|
|
177
|
+
exposed as `readonly emitter` carrying `QueueEventMap<TResult>`
|
|
181
178
|
(`enqueue` / `start` / `retry` / `success` / `failure` / `abort` / `drain`), bridged
|
|
182
179
|
from the underlying queue's own emitter at construction — each bridge listener
|
|
183
180
|
re-emits directly on the worker's emitter and never throws, so the inner queue's own
|
|
@@ -188,16 +185,16 @@ These invariants hold across `src/core` ↔ `worker.md`:
|
|
|
188
185
|
own `create` / `acquire` / `release` / `destroy` events stay the pool's internal
|
|
189
186
|
concern — observe a `Pool` directly for those.
|
|
190
187
|
4. **Doc ↔ source method bijection.** The `## Methods` table lists exactly the public
|
|
191
|
-
methods of `
|
|
192
|
-
|
|
188
|
+
methods of `Worker` — exhaustive, both directions — and they are the methods of the
|
|
189
|
+
`QueueInterface` it implements, no more.
|
|
193
190
|
5. **`createNodeWorker` is a thread specialization of `createWorker` (`@orkestrel/worker/server`).**
|
|
194
191
|
It does not reimplement concurrency / retry / timeout / lifecycle — it calls
|
|
195
192
|
`createWorker` with a `Pool` whose resource is a `node:worker_threads` thread
|
|
196
193
|
(`create` = the spawn `createThread` publishes, `destroy` = `terminate()`,
|
|
197
194
|
`validate` = `alive && threadId > 0`) and an internal handler that narrows the input
|
|
198
|
-
through `options.input` then runs a `
|
|
195
|
+
through `options.input` then runs a `Job` against the leased thread. `TInput` and
|
|
199
196
|
`TResult` infer from the `input` and `result` guards, so a call site needs no type
|
|
200
|
-
argument. The structured-clone boundary is crossed with no `as`: a `
|
|
197
|
+
argument. The structured-clone boundary is crossed with no `as`: a `Job` narrows each reply
|
|
201
198
|
value through `options.result` (a value that fails it rejects with `'reply did not
|
|
202
199
|
satisfy result guard'`), and the worker side narrows each payload through
|
|
203
200
|
`options.input` (a bad input replies `'input did not satisfy input guard'`) —
|
|
@@ -223,15 +220,15 @@ These invariants hold across `src/core` ↔ `worker.md`:
|
|
|
223
220
|
7. **A thread death settles its job under every event ordering — the `death` latch.**
|
|
224
221
|
Every spawned thread carries persistent `error` / `messageerror` / `exit` listeners that
|
|
225
222
|
flip `alive = false`
|
|
226
|
-
and latch the first terminal event on `NodeThread.death`; a `
|
|
223
|
+
and latch the first terminal event on `NodeThread.death`; a `Job` checks that latch
|
|
227
224
|
synchronously at construction, so a job dispatched onto a thread that already died rejects
|
|
228
225
|
immediately. A thread can become terminal before the readiness promise continuation
|
|
229
|
-
attaches
|
|
230
|
-
the job would wait forever. A death mid-flight still rejects through the
|
|
226
|
+
attaches `Job` listeners, and those events will never fire again; without the latch
|
|
227
|
+
the job would wait forever. A death mid-flight still rejects through the `Job`'s own
|
|
231
228
|
`error` / `exit` listeners; exit rejects with that exact already-latched `death` object,
|
|
232
229
|
whose message retains the exit code (for example, `worker thread exited (code 1)`). An
|
|
233
230
|
inbound `messageerror` also evicts and terminates the thread, rejects the
|
|
234
|
-
|
|
231
|
+
job, and is detached with the other per-job listeners. A death before `online`
|
|
235
232
|
rejects the spawn itself.
|
|
236
233
|
8. **`serveWorker` captures registration options once.** After the main-thread
|
|
237
234
|
`parentPort === null` no-op, registration reads `options.input` and then
|
|
@@ -240,9 +237,9 @@ These invariants hold across `src/core` ↔ `worker.md`:
|
|
|
240
237
|
the initially captured guard and handler identities. The main-thread no-op reads neither.
|
|
241
238
|
9. **Structured-clone constraints.** `TInput` / `TResult` / `workerData` must be
|
|
242
239
|
structured-cloneable (no functions / Promises / `AbortSignal`). A non-cloneable result
|
|
243
|
-
cannot strand a
|
|
240
|
+
cannot strand a job: `serveWorker` replaces the failed success post with a clone-safe
|
|
244
241
|
failure envelope, and closes the parent port if even that fallback cannot be posted so the
|
|
245
|
-
main side observes exit. A matching-id malformed reply similarly rejects the
|
|
242
|
+
main side observes exit. A matching-id malformed reply similarly rejects the job,
|
|
246
243
|
terminates and evicts the tainted thread, and leaves id-less / foreign-id chatter ignored.
|
|
247
244
|
Raw TypeScript is unflagged on Node 22.18+ and Node 23.6+; Node 22.12–22.17 and Node
|
|
248
245
|
23.0–23.5 require `--experimental-strip-types`. A built `.js` / `.mjs` script is an
|
|
@@ -251,7 +248,7 @@ These invariants hold across `src/core` ↔ `worker.md`:
|
|
|
251
248
|
that runs the handler and answers the protocol; it is self-contained and imports only
|
|
252
249
|
`node:worker_threads` at runtime,
|
|
253
250
|
so it loads as a raw module in a spawned thread. `createNodeWorker` returns the plain
|
|
254
|
-
`
|
|
251
|
+
`QueueInterface`, so it inherits the Worker's `emitter` unchanged (clause 3).
|
|
255
252
|
10. **`createJSONQueueStore` is `@orkestrel/queue`'s `createDatabaseQueueStore` over a
|
|
256
253
|
server JSON driver.** A queue's durable state is a `@orkestrel/database` table,
|
|
257
254
|
so JSON persistence reuses the existing driver rather than a bespoke store — see
|
|
@@ -262,7 +259,7 @@ These invariants hold across `src/core` ↔ `worker.md`:
|
|
|
262
259
|
`createNodeWorker` (`@orkestrel/worker/server`) runs jobs on a pool of `node:worker_threads` threads —
|
|
263
260
|
true CPU parallelism for work that would otherwise block the event loop. It is a thin
|
|
264
261
|
specialization of [`createWorker`](#surface): the pooled resource is a worker thread, and
|
|
265
|
-
it returns the plain `
|
|
262
|
+
it returns the plain `QueueInterface`, so its methods, lifecycle, concurrency, retries,
|
|
266
263
|
timeout, and durability are exactly the Worker's (see [Methods](#methods)). The only
|
|
267
264
|
additions are the thread pairing and the zero-`as` wire bridge.
|
|
268
265
|
|
|
@@ -326,7 +323,7 @@ structured-cloneable (no functions, Promises, or `AbortSignal`s cross the bounda
|
|
|
326
323
|
name, and the thread reads it back from `node:worker_threads`.
|
|
327
324
|
|
|
328
325
|
A thread worker takes the same `on` and `error` hooks as the core worker: pass `on` to wire
|
|
329
|
-
initial `
|
|
326
|
+
initial `QueueEventMap` listeners at construction, and `error` to receive a listener's throw
|
|
330
327
|
(see [Observing](#observing)).
|
|
331
328
|
|
|
332
329
|
## Persistence
|
|
@@ -374,9 +371,9 @@ worker.emitter.on('failure', (id, error) => log.warn(`job ${id} failed`, error))
|
|
|
374
371
|
|
|
375
372
|
The events the worker's emitter carries:
|
|
376
373
|
|
|
377
|
-
| Event map
|
|
378
|
-
|
|
|
379
|
-
| `
|
|
374
|
+
| Event map | Events |
|
|
375
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
376
|
+
| `QueueEventMap<TResult>` | `enqueue(id)` · `start(id)` · `retry(id, attempt)` · `success(id, result)` · `failure(id, error)` · `abort(reason)` · `drain()` |
|
|
380
377
|
|
|
381
378
|
The worker forwards queue event payloads unchanged. In particular, `abort(reason)` carries
|
|
382
379
|
the queue's coded `QueueError` with code `aborted`; its `cause` retains the caller-supplied
|
|
@@ -533,7 +530,7 @@ These tests pin the behaviour this guide documents:
|
|
|
533
530
|
|
|
534
531
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the
|
|
535
532
|
`## Surface` ↔ `src/core` / `src/server` bijection (value + type exports), the
|
|
536
|
-
`
|
|
533
|
+
`## Methods` ↔ `Worker` method bijection, and the equality gate: every `Summary`
|
|
537
534
|
cell against its declaration's description paragraph, the titled
|
|
538
535
|
`A resource-backed worker` fence against the `@example` block of that title (pinned so
|
|
539
536
|
the titled pair cannot be retired silently), and the README pitch against this guide's
|
|
@@ -566,9 +563,11 @@ These tests pin the behaviour this guide documents:
|
|
|
566
563
|
promise identity across repeated and abort-event-reentrant calls, waits for serial queue
|
|
567
564
|
then pool cleanup, destroys the worker emitter last, and preserves a sole pool failure;
|
|
568
565
|
and durability passthrough — a `store` persists a job and `restore()` re-runs it against
|
|
569
|
-
a fresh resource (delegated to the queue), a no-op without a store
|
|
566
|
+
a fresh resource (delegated to the queue), a no-op without a store; and the `Worker`
|
|
567
|
+
typed by `@orkestrel/queue`'s `QueueInterface`, its `emitter` and `on` hooks carrying
|
|
568
|
+
`QueueEventMap`.
|
|
570
569
|
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) —
|
|
571
|
-
`createWorker` returns a working
|
|
570
|
+
`createWorker` returns a working `QueueInterface` end to end and honours its options +
|
|
572
571
|
status surface.
|
|
573
572
|
- [`tests/src/server/factories.test.ts`](../tests/src/server/factories.test.ts) —
|
|
574
573
|
`createJSONQueueStore` over a real temp file: entries persist across store instances on
|
|
@@ -576,10 +575,11 @@ These tests pin the behaviour this guide documents:
|
|
|
576
575
|
the JSON round-trip, and a `remove` is reflected across a reopen; `createThread` resolving
|
|
577
576
|
a live thread that clones its `workerData` across, spawning with that argument omitted, and
|
|
578
577
|
rejecting a script that dies before `online`; plus a `createNodeWorker` round-trip smoke (a
|
|
579
|
-
job over a real thread
|
|
580
|
-
listener throw routed to `error`, and the option
|
|
578
|
+
job over a real thread through the returned `QueueInterface`, then teardown), the `on`
|
|
579
|
+
hooks wired at construction with a listener throw routed to `error`, and the option
|
|
580
|
+
snapshot retained across jobs.
|
|
581
581
|
- [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) — the
|
|
582
|
-
main-side worker-thread machinery (`createThread` / `
|
|
582
|
+
main-side worker-thread machinery (`createThread` / `Job`), driven
|
|
583
583
|
through `createNodeWorker` over real worker threads (no mocking): a round-trip and a
|
|
584
584
|
batch over a small pool; the concurrency cap and the live-thread cap + idle reuse; a
|
|
585
585
|
throwing handler rejecting with its error, and re-running under `retries`; explicit enqueue
|