@orkestrel/worker 0.0.10 → 0.0.11

package/dist/src/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["#queue","#pool","#emitter","#handler","#handle","#bridge","#ending","#teardown"],"sources":["../../../src/core/Worker.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { EmitterInterface } from '@orkestrel/emitter'\nimport type { QueueEntryOptions, QueueExecution } from '@orkestrel/queue'\nimport type { WorkerEventMap, WorkerHandler, WorkerInterface, WorkerOptions } from './types.js'\nimport { Emitter } from '@orkestrel/emitter'\nimport { Pool } from '@orkestrel/pool'\nimport { Queue } from '@orkestrel/queue'\n\n/**\n * A resource-backed job worker — a thin facade composing a `Queue` (`@orkestrel/queue`)\n * with a `Pool` (`@orkestrel/pool`).\n *\n * @remarks\n * - **Composition, not reimplementation.** The Worker owns a `Pool` (built from\n *   `options.pool`) and a `Queue` whose handler ACQUIRES a pooled resource, runs the\n *   user handler against it, and RELEASES it in a `finally`. All concurrency, retries,\n *   timeout, and lifecycle are the Queue's — the Worker adds only the resource pairing.\n * - **Resource ↔ concurrency.** The queue strictly validates `concurrency` as a positive\n *   safe integer after caller options are captured once. Only `undefined` defaults\n *   `concurrency` to `1` or pool `max` to that value; runtime `null` reaches the owning\n *   validator. The queue validates before the pool option is read; every declared pool member\n *   is then captured once by direct access, preserving inherited and non-enumerable structural\n *   options. At most one resource exists per in-flight job by default, and idle resources are\n *   reused across jobs.\n * - **Acquire over the attempt signal.** Each job acquires using the attempt's\n *   `execution.signal`, so an `abort` / `timeout` while waiting for a resource rejects\n *   the acquire — the Queue then handles retry / rejection, and there is no token to\n *   release (the resource was never leased).\n * - **Lifecycle (§10).** `enqueue` / `restore` / `start` / `stop` / `pause` / `resume` /\n *   `abort` / `clear` delegate to the queue; `count` / `active` / `paused` / `stopped`\n *   read it. `stop` / `abort` / `clear` return the queue's own cleanup barriers.\n *   `destroy` returns one stable barrier while it tears down the queue, then the pool,\n *   and destroys the worker emitter last. A sole cleanup failure is preserved by\n *   identity; failures from both layers become an ordered `AggregateError`.\n * - **Durability.** An optional `store` is passed straight through to the queue, so the\n *   worker's outstanding jobs persist; `restore` re-runs them (delegated to the queue).\n * - **Observable (§13).** The owned {@link emitter} ({@link WorkerEventMap}) RE-EXPOSES the\n *   underlying queue's job lifecycle (`enqueue` / `start` / `retry` / `success` / `failure` /\n *   `abort` / `drain`) as the worker's OWN events — bridged from the inner queue's emitter at\n *   construction — so a consumer observes the worker without reaching through to internals.\n *   The bridge re-emits directly on the worker's own emitter; the worker emitter isolates a\n *   listener throw and routes it to its `error` handler (the `error` option), so a buggy\n *   worker observer can never corrupt the inner queue or pool — the bridge listener never\n *   throws, so the inner queue's own emit stays balanced. The pool's create / acquire /\n *   release events stay the pool's internal concern (a Worker manages its own resources);\n *   observe a `Pool` directly for those.\n */\nexport class Worker<TInput, TResource, TResult> implements WorkerInterface<TInput, TResult> {\n\treadonly #queue: Queue<TInput, TResult>\n\treadonly #pool: Pool<TResource>\n\t// The PUSH observation surface (§13) — the worker's OWN emitter, fed by the queue→worker\n\t// bridge. The emitter isolates a worker observer's throw (routing it to the `error`\n\t// handler), so it never escapes into queue or pool.\n\treadonly #emitter: Emitter<WorkerEventMap<TResult>>\n\treadonly #handler: WorkerHandler<TInput, TResource, TResult>\n\t#ending: PromiseWithResolvers<void> | undefined\n\n\tconstructor(options: WorkerOptions<TInput, TResource, TResult>) {\n\t\tconst {\n\t\t\tconcurrency: capturedConcurrency,\n\t\t\thandler,\n\t\t\ton,\n\t\t\terror,\n\t\t\tretries,\n\t\t\ttimeout,\n\t\t\tstore,\n\t\t} = options\n\t\tconst concurrency = capturedConcurrency === undefined ? 1 : capturedConcurrency\n\t\tthis.#handler = handler\n\t\tthis.#emitter = new Emitter<WorkerEventMap<TResult>>({\n\t\t\t...(on !== undefined ? { on } : {}),\n\t\t\t...(error !== undefined ? { error } : {}),\n\t\t})\n\t\tthis.#queue = new Queue<TInput, TResult>({\n\t\t\thandler: this.#handle.bind(this),\n\t\t\tconcurrency,\n\t\t\t...(retries !== undefined ? { retries } : {}),\n\t\t\t...(timeout !== undefined ? { timeout } : {}),\n\t\t\t...(store !== undefined ? { store } : {}),\n\t\t})\n\t\tconst pool = options.pool\n\t\tconst { max, on: poolOn, error: poolError, create, destroy, validate } = pool\n\t\tthis.#pool = new Pool<TResource>({\n\t\t\tcreate,\n\t\t\tmax: max === undefined ? concurrency : max,\n\t\t\t...(poolOn !== undefined ? { on: poolOn } : {}),\n\t\t\t...(poolError !== undefined ? { error: poolError } : {}),\n\t\t\t...(destroy !== undefined ? { destroy } : {}),\n\t\t\t...(validate !== undefined ? { validate } : {}),\n\t\t})\n\t\tthis.#bridge()\n\t}\n\n\tget emitter(): EmitterInterface<WorkerEventMap<TResult>> {\n\t\treturn this.#emitter\n\t}\n\n\tget count(): number {\n\t\treturn this.#queue.count\n\t}\n\n\tget active(): number {\n\t\treturn this.#queue.active\n\t}\n\n\tget paused(): boolean {\n\t\treturn this.#queue.paused\n\t}\n\n\tget stopped(): boolean {\n\t\treturn this.#queue.stopped\n\t}\n\n\tenqueue(input: TInput, options?: QueueEntryOptions): Promise<TResult> {\n\t\treturn this.#queue.enqueue(input, options)\n\t}\n\n\trestore(): Promise<void> {\n\t\treturn this.#queue.restore()\n\t}\n\n\tstart(): void {\n\t\tthis.#queue.start()\n\t}\n\n\tstop(): Promise<void> {\n\t\treturn this.#queue.stop()\n\t}\n\n\tpause(): void {\n\t\tthis.#queue.pause()\n\t}\n\n\tresume(): void {\n\t\tthis.#queue.resume()\n\t}\n\n\tabort(reason?: unknown): Promise<void> {\n\t\treturn this.#queue.abort(reason)\n\t}\n\n\tclear(): Promise<void> {\n\t\treturn this.#queue.clear()\n\t}\n\n\tdestroy(): Promise<void> {\n\t\tif (this.#ending !== undefined) return this.#ending.promise\n\t\tconst ending = Promise.withResolvers<void>()\n\t\tthis.#ending = ending\n\t\tvoid this.#teardown(ending)\n\t\treturn ending.promise\n\t}\n\n\tasync #handle(input: TInput, execution: QueueExecution): Promise<TResult> {\n\t\tconst token = await this.#pool.acquire(execution.signal)\n\t\ttry {\n\t\t\treturn await this.#handler(input, token.value, execution)\n\t\t} finally {\n\t\t\ttoken.release()\n\t\t}\n\t}\n\n\tasync #teardown(ending: PromiseWithResolvers<void>): Promise<void> {\n\t\tconst failures: unknown[] = []\n\t\ttry {\n\t\t\tawait this.#queue.destroy()\n\t\t} catch (error) {\n\t\t\tfailures.push(error)\n\t\t}\n\t\ttry {\n\t\t\tawait this.#pool.destroy()\n\t\t} catch (error) {\n\t\t\tfailures.push(error)\n\t\t}\n\t\tthis.#emitter.destroy()\n\t\tif (failures.length === 0) ending.resolve()\n\t\telse if (failures.length === 1) ending.reject(failures[0])\n\t\telse ending.reject(new AggregateError(failures, 'worker destroy cleanup failed'))\n\t}\n\n\t// Bridge the inner queue's lifecycle onto the worker's OWN emitter, once at construction.\n\t// Each listener re-emits the queue event directly on the worker's emitter, which isolates a\n\t// worker observer's throw (routing it to the worker's `error` handler). Because the bridge\n\t// listener itself never throws, the queue's own `#emitter.emit` — which invoked this\n\t// listener — sees no throw, so the inner queue's engine stays balanced regardless of what a\n\t// worker observer does. The events are already post-transition (they fire from the queue's\n\t// own post-settle / post-wake emits), so this stays observation.\n\t#bridge(): void {\n\t\tconst queue = this.#queue.emitter\n\t\tqueue.on('enqueue', (id) => this.#emitter.emit('enqueue', id))\n\t\tqueue.on('start', (id) => this.#emitter.emit('start', id))\n\t\tqueue.on('retry', (id, attempt) => this.#emitter.emit('retry', id, attempt))\n\t\tqueue.on('success', (id, result) => this.#emitter.emit('success', id, result))\n\t\tqueue.on('failure', (id, error) => this.#emitter.emit('failure', id, error))\n\t\tqueue.on('abort', (reason) => this.#emitter.emit('abort', reason))\n\t\tqueue.on('drain', () => this.#emitter.emit('drain'))\n\t}\n}\n","import type { WorkerInterface, WorkerOptions } from './types.js'\nimport { Worker } from './Worker.js'\n\n/**\n * Create a resource-backed job worker — a `Queue` (`@orkestrel/queue`) marrying a `Pool`\n * (`@orkestrel/pool`). Each enqueued input runs through the handler against an\n * automatically acquired pooled resource (released when the job settles), with the\n * queue's bounded concurrency, retries, and per-attempt timeout / abort.\n *\n * @remarks\n * The pool's `max` defaults to `concurrency`, so resources match the jobs in flight and\n * are reused across jobs. A handler that throws still releases its resource (the\n * acquire/release pair brackets the call in a `finally`), so a later job reuses it. The\n * lifecycle (`start` / `stop` / `pause` / `resume` / `abort` / `clear` / `destroy`)\n * delegates to the queue; `destroy` also tears the pool down. Observable (§13): a typed\n * `emitter` surfaces the queue lifecycle (`enqueue` / `start` / `success` / `failure` / …).\n *\n * @typeParam TInput - The work input each job carries\n * @typeParam TResource - The pooled resource each job runs against\n * @typeParam TResult - The value the handler resolves for a job\n * @param options - The `handler` and `pool` plus optional `concurrency` (default `1`),\n *   `retries` (default `0`), and a default per-attempt `timeout` in milliseconds\n * @returns A working {@link WorkerInterface}\n *\n * @example\n * ```ts\n * import { createWorker } from '@orkestrel/worker'\n *\n * const worker = createWorker<Query, Connection, Rows>({\n * \tpool: { create: () => connect(), destroy: (connection) => connection.close() },\n * \thandler: (query, connection, { signal }) => connection.run(query, signal),\n * \tconcurrency: 4,\n * \tretries: 1,\n * })\n *\n * const rows = await worker.enqueue(query)\n * ```\n */\nexport function createWorker<TInput, TResource, TResult>(\n\toptions: WorkerOptions<TInput, TResource, TResult>,\n): WorkerInterface<TInput, TResult> {\n\treturn new Worker(options)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,IAAa,SAAb,MAA4F;CAC3F;CACA;CAIA;CACA;CACA;CAEA,YAAY,SAAoD;EAC/D,MAAM,EACL,aAAa,qBACb,SACA,IACA,OACA,SACA,SACA,UACG;EACJ,MAAM,cAAc,wBAAwB,KAAA,IAAY,IAAI;EAC5D,KAAKG,WAAW;EAChB,KAAKD,WAAW,IAAI,QAAiC;GACpD,GAAI,OAAO,KAAA,IAAY,EAAE,GAAG,IAAI,CAAC;GACjC,GAAI,UAAU,KAAA,IAAY,EAAE,MAAM,IAAI,CAAC;EACxC,CAAC;EACD,KAAKF,SAAS,IAAI,MAAuB;GACxC,SAAS,KAAKI,QAAQ,KAAK,IAAI;GAC/B;GACA,GAAI,YAAY,KAAA,IAAY,EAAE,QAAQ,IAAI,CAAC;GAC3C,GAAI,YAAY,KAAA,IAAY,EAAE,QAAQ,IAAI,CAAC;GAC3C,GAAI,UAAU,KAAA,IAAY,EAAE,MAAM,IAAI,CAAC;EACxC,CAAC;EAED,MAAM,EAAE,KAAK,IAAI,QAAQ,OAAO,WAAW,QAAQ,SAAS,aAD/C,QAAQ;EAErB,KAAKH,QAAQ,IAAI,KAAgB;GAChC;GACA,KAAK,QAAQ,KAAA,IAAY,cAAc;GACvC,GAAI,WAAW,KAAA,IAAY,EAAE,IAAI,OAAO,IAAI,CAAC;GAC7C,GAAI,cAAc,KAAA,IAAY,EAAE,OAAO,UAAU,IAAI,CAAC;GACtD,GAAI,YAAY,KAAA,IAAY,EAAE,QAAQ,IAAI,CAAC;GAC3C,GAAI,aAAa,KAAA,IAAY,EAAE,SAAS,IAAI,CAAC;EAC9C,CAAC;EACD,KAAKI,QAAQ;CACd;CAEA,IAAI,UAAqD;EACxD,OAAO,KAAKH;CACb;CAEA,IAAI,QAAgB;EACnB,OAAO,KAAKF,OAAO;CACpB;CAEA,IAAI,SAAiB;EACpB,OAAO,KAAKA,OAAO;CACpB;CAEA,IAAI,SAAkB;EACrB,OAAO,KAAKA,OAAO;CACpB;CAEA,IAAI,UAAmB;EACtB,OAAO,KAAKA,OAAO;CACpB;CAEA,QAAQ,OAAe,SAA+C;EACrE,OAAO,KAAKA,OAAO,QAAQ,OAAO,OAAO;CAC1C;CAEA,UAAyB;EACxB,OAAO,KAAKA,OAAO,QAAQ;CAC5B;CAEA,QAAc;EACb,KAAKA,OAAO,MAAM;CACnB;CAEA,OAAsB;EACrB,OAAO,KAAKA,OAAO,KAAK;CACzB;CAEA,QAAc;EACb,KAAKA,OAAO,MAAM;CACnB;CAEA,SAAe;EACd,KAAKA,OAAO,OAAO;CACpB;CAEA,MAAM,QAAiC;EACtC,OAAO,KAAKA,OAAO,MAAM,MAAM;CAChC;CAEA,QAAuB;EACtB,OAAO,KAAKA,OAAO,MAAM;CAC1B;CAEA,UAAyB;EACxB,IAAI,KAAKM,YAAY,KAAA,GAAW,OAAO,KAAKA,QAAQ;EACpD,MAAM,SAAS,QAAQ,cAAoB;EAC3C,KAAKA,UAAU;EACf,KAAUC,UAAU,MAAM;EAC1B,OAAO,OAAO;CACf;CAEA,MAAMH,QAAQ,OAAe,WAA6C;EACzE,MAAM,QAAQ,MAAM,KAAKH,MAAM,QAAQ,UAAU,MAAM;EACvD,IAAI;GACH,OAAO,MAAM,KAAKE,SAAS,OAAO,MAAM,OAAO,SAAS;EACzD,UAAU;GACT,MAAM,QAAQ;EACf;CACD;CAEA,MAAMI,UAAU,QAAmD;EAClE,MAAM,WAAsB,CAAC;EAC7B,IAAI;GACH,MAAM,KAAKP,OAAO,QAAQ;EAC3B,SAAS,OAAO;GACf,SAAS,KAAK,KAAK;EACpB;EACA,IAAI;GACH,MAAM,KAAKC,MAAM,QAAQ;EAC1B,SAAS,OAAO;GACf,SAAS,KAAK,KAAK;EACpB;EACA,KAAKC,SAAS,QAAQ;EACtB,IAAI,SAAS,WAAW,GAAG,OAAO,QAAQ;OACrC,IAAI,SAAS,WAAW,GAAG,OAAO,OAAO,SAAS,EAAE;OACpD,OAAO,OAAO,IAAI,eAAe,UAAU,+BAA+B,CAAC;CACjF;CASA,UAAgB;EACf,MAAM,QAAQ,KAAKF,OAAO;EAC1B,MAAM,GAAG,YAAY,OAAO,KAAKE,SAAS,KAAK,WAAW,EAAE,CAAC;EAC7D,MAAM,GAAG,UAAU,OAAO,KAAKA,SAAS,KAAK,SAAS,EAAE,CAAC;EACzD,MAAM,GAAG,UAAU,IAAI,YAAY,KAAKA,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC;EAC3E,MAAM,GAAG,YAAY,IAAI,WAAW,KAAKA,SAAS,KAAK,WAAW,IAAI,MAAM,CAAC;EAC7E,MAAM,GAAG,YAAY,IAAI,UAAU,KAAKA,SAAS,KAAK,WAAW,IAAI,KAAK,CAAC;EAC3E,MAAM,GAAG,UAAU,WAAW,KAAKA,SAAS,KAAK,SAAS,MAAM,CAAC;EACjE,MAAM,GAAG,eAAe,KAAKA,SAAS,KAAK,OAAO,CAAC;CACpD;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC9JA,SAAgB,aACf,SACmC;CACnC,OAAO,IAAI,OAAO,OAAO;AAC1B"}
+{"version":3,"file":"index.js","names":["#queue","#pool","#emitter","#handler","#handle","#bridge","#ending","#teardown"],"sources":["../../../src/core/Worker.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { EmitterInterface } from '@orkestrel/emitter'\nimport type { QueueContext, QueueEntryOptions } from '@orkestrel/queue'\nimport type { WorkerEventMap, WorkerHandler, WorkerInterface, WorkerOptions } from './types.js'\nimport { Emitter } from '@orkestrel/emitter'\nimport { Pool } from '@orkestrel/pool'\nimport { Queue } from '@orkestrel/queue'\n\n/**\n * Represents a resource-backed job worker — a thin facade composing a `Queue`\n * (`@orkestrel/queue`) with a `Pool` (`@orkestrel/pool`).\n *\n * @remarks\n * - **Composition, not reimplementation.** The Worker owns a `Pool` (built from\n *   `options.pool`) and a `Queue` whose handler ACQUIRES a pooled resource, runs the\n *   user handler against it, and RELEASES it in a `finally`. All concurrency, retries,\n *   timeout, and lifecycle are the Queue's — the Worker adds only the resource pairing.\n * - **Resource ↔ concurrency.** The queue strictly validates `concurrency` as a positive\n *   safe integer after caller options are captured once. Only `undefined` defaults\n *   `concurrency` to `1` or pool `max` to that value; runtime `null` reaches the owning\n *   validator. The queue validates before the pool option is read; every declared pool member\n *   is then captured once by direct access, preserving inherited and non-enumerable structural\n *   options. At most one resource exists per in-flight job by default, and idle resources are\n *   reused across jobs.\n * - **Acquire over the attempt signal.** Each job acquires using the attempt's\n *   `context.signal`, so an `abort` / `timeout` while waiting for a resource rejects\n *   the acquire — the Queue then handles retry / rejection, and there is no token to\n *   release (the resource was never leased).\n * - **Lifecycle (§10).** `enqueue` / `restore` / `start` / `stop` / `pause` / `resume` /\n *   `abort` / `clear` delegate to the queue; `count` / `active` / `paused` / `stopped`\n *   read it. `stop` / `abort` / `clear` return the queue's own cleanup barriers.\n *   `destroy` returns one stable barrier while it tears down the queue, then the pool,\n *   and destroys the worker emitter last. A sole cleanup failure is preserved by\n *   identity; failures from both layers become an ordered `AggregateError`.\n * - **Durability.** An optional `store` is passed straight through to the queue, so the\n *   worker's outstanding jobs persist; `restore` re-runs them (delegated to the queue).\n * - **Observable (§13).** The owned {@link emitter} ({@link WorkerEventMap}) RE-EXPOSES the\n *   underlying queue's job lifecycle (`enqueue` / `start` / `retry` / `success` / `failure` /\n *   `abort` / `drain`) as the worker's OWN events — bridged from the inner queue's emitter at\n *   construction — so a consumer observes the worker without reaching through to internals.\n *   The bridge re-emits directly on the worker's own emitter; the worker emitter isolates a\n *   listener throw and routes it to its `error` handler (the `error` option), so a buggy\n *   worker observer can never corrupt the inner queue or pool — the bridge listener never\n *   throws, so the inner queue's own emit stays balanced. The pool's create / acquire /\n *   release events stay the pool's internal concern (a Worker manages its own resources);\n *   observe a `Pool` directly for those.\n */\nexport class Worker<TInput, TResource, TResult> implements WorkerInterface<TInput, TResult> {\n\treadonly #queue: Queue<TInput, TResult>\n\treadonly #pool: Pool<TResource>\n\t// The PUSH observation surface (§13) — the worker's OWN emitter, fed by the queue→worker\n\t// bridge. The emitter isolates a worker observer's throw (routing it to the `error`\n\t// handler), so it never escapes into queue or pool.\n\treadonly #emitter: Emitter<WorkerEventMap<TResult>>\n\treadonly #handler: WorkerHandler<TInput, TResource, TResult>\n\t#ending: PromiseWithResolvers<void> | undefined\n\n\tconstructor(options: WorkerOptions<TInput, TResource, TResult>) {\n\t\tconst {\n\t\t\tconcurrency: capturedConcurrency,\n\t\t\thandler,\n\t\t\ton,\n\t\t\terror,\n\t\t\tretries,\n\t\t\ttimeout,\n\t\t\tstore,\n\t\t} = options\n\t\tconst concurrency = capturedConcurrency === undefined ? 1 : capturedConcurrency\n\t\tthis.#handler = handler\n\t\tthis.#emitter = new Emitter<WorkerEventMap<TResult>>({\n\t\t\t...(on !== undefined ? { on } : {}),\n\t\t\t...(error !== undefined ? { error } : {}),\n\t\t})\n\t\tthis.#queue = new Queue<TInput, TResult>({\n\t\t\thandler: this.#handle.bind(this),\n\t\t\tconcurrency,\n\t\t\t...(retries !== undefined ? { retries } : {}),\n\t\t\t...(timeout !== undefined ? { timeout } : {}),\n\t\t\t...(store !== undefined ? { store } : {}),\n\t\t})\n\t\tconst pool = options.pool\n\t\tconst { max, on: poolOn, error: poolError, create, destroy, validate } = pool\n\t\tthis.#pool = new Pool<TResource>({\n\t\t\tcreate,\n\t\t\tmax: max === undefined ? concurrency : max,\n\t\t\t...(poolOn !== undefined ? { on: poolOn } : {}),\n\t\t\t...(poolError !== undefined ? { error: poolError } : {}),\n\t\t\t...(destroy !== undefined ? { destroy } : {}),\n\t\t\t...(validate !== undefined ? { validate } : {}),\n\t\t})\n\t\tthis.#bridge()\n\t}\n\n\tget emitter(): EmitterInterface<WorkerEventMap<TResult>> {\n\t\treturn this.#emitter\n\t}\n\n\tget count(): number {\n\t\treturn this.#queue.count\n\t}\n\n\tget active(): number {\n\t\treturn this.#queue.active\n\t}\n\n\tget paused(): boolean {\n\t\treturn this.#queue.paused\n\t}\n\n\tget stopped(): boolean {\n\t\treturn this.#queue.stopped\n\t}\n\n\tenqueue(input: TInput, options?: QueueEntryOptions): Promise<TResult> {\n\t\treturn this.#queue.enqueue(input, options)\n\t}\n\n\trestore(): Promise<void> {\n\t\treturn this.#queue.restore()\n\t}\n\n\tstart(): void {\n\t\tthis.#queue.start()\n\t}\n\n\tstop(): Promise<void> {\n\t\treturn this.#queue.stop()\n\t}\n\n\tpause(): void {\n\t\tthis.#queue.pause()\n\t}\n\n\tresume(): void {\n\t\tthis.#queue.resume()\n\t}\n\n\tabort(reason?: unknown): Promise<void> {\n\t\treturn this.#queue.abort(reason)\n\t}\n\n\tclear(): Promise<void> {\n\t\treturn this.#queue.clear()\n\t}\n\n\tdestroy(): Promise<void> {\n\t\tif (this.#ending !== undefined) return this.#ending.promise\n\t\tconst ending = Promise.withResolvers<void>()\n\t\tthis.#ending = ending\n\t\tvoid this.#teardown(ending)\n\t\treturn ending.promise\n\t}\n\n\tasync #handle(input: TInput, context: QueueContext): Promise<TResult> {\n\t\tconst token = await this.#pool.acquire(context.signal)\n\t\ttry {\n\t\t\treturn await this.#handler(input, token.value, context)\n\t\t} finally {\n\t\t\ttoken.release()\n\t\t}\n\t}\n\n\tasync #teardown(ending: PromiseWithResolvers<void>): Promise<void> {\n\t\tconst failures: unknown[] = []\n\t\ttry {\n\t\t\tawait this.#queue.destroy()\n\t\t} catch (error) {\n\t\t\tfailures.push(error)\n\t\t}\n\t\ttry {\n\t\t\tawait this.#pool.destroy()\n\t\t} catch (error) {\n\t\t\tfailures.push(error)\n\t\t}\n\t\tthis.#emitter.destroy()\n\t\tif (failures.length === 0) ending.resolve()\n\t\telse if (failures.length === 1) ending.reject(failures[0])\n\t\telse ending.reject(new AggregateError(failures, 'worker destroy cleanup failed'))\n\t}\n\n\t// Bridge the inner queue's lifecycle onto the worker's OWN emitter, once at construction.\n\t// Each listener re-emits the queue event directly on the worker's emitter, which isolates a\n\t// worker observer's throw (routing it to the worker's `error` handler). Because the bridge\n\t// listener itself never throws, the queue's own `#emitter.emit` — which invoked this\n\t// listener — sees no throw, so the inner queue's engine stays balanced regardless of what a\n\t// worker observer does. The events are already post-transition (they fire from the queue's\n\t// own post-settle / post-wake emits), so this stays observation.\n\t#bridge(): void {\n\t\tconst queue = this.#queue.emitter\n\t\tqueue.on('enqueue', (id) => this.#emitter.emit('enqueue', id))\n\t\tqueue.on('start', (id) => this.#emitter.emit('start', id))\n\t\tqueue.on('retry', (id, attempt) => this.#emitter.emit('retry', id, attempt))\n\t\tqueue.on('success', (id, result) => this.#emitter.emit('success', id, result))\n\t\tqueue.on('failure', (id, error) => this.#emitter.emit('failure', id, error))\n\t\tqueue.on('abort', (reason) => this.#emitter.emit('abort', reason))\n\t\tqueue.on('drain', () => this.#emitter.emit('drain'))\n\t}\n}\n","import type { WorkerInterface, WorkerOptions } from './types.js'\nimport { Worker } from './Worker.js'\n\n/**\n * Creates a resource-backed job worker — a `Queue` (`@orkestrel/queue`) marrying a `Pool`\n * (`@orkestrel/pool`). Each enqueued input runs through the handler against an\n * automatically acquired pooled resource (released when the job settles), with the\n * queue's bounded concurrency, retries, and per-attempt timeout / abort.\n *\n * @remarks\n * Default for the pool's `max`: the `concurrency` value, so resources match the jobs in flight.\n * Resources are reused across jobs. A handler that throws still releases its resource (the\n * acquire/release pair brackets the call in a `finally`), so a later job reuses it. The\n * lifecycle (`start` / `stop` / `pause` / `resume` / `abort` / `clear` / `destroy`)\n * delegates to the queue; `destroy` also tears the pool down. Observable (§13): a typed\n * `emitter` surfaces the queue lifecycle (`enqueue` / `start` / `success` / `failure` / …).\n *\n * @typeParam TInput - The work input each job carries\n * @typeParam TResource - The pooled resource each job runs against\n * @typeParam TResult - The value the handler resolves for a job\n * @param options - The `handler` and `pool` plus the optional `concurrency`, `retries`,\n *   `timeout`, `store`, `on`, and `error` keys (see {@link WorkerOptions})\n * @returns A working {@link WorkerInterface}\n *\n * @example\n * ```ts\n * import { createWorker } from '@orkestrel/worker'\n *\n * const worker = createWorker<Query, Connection, Rows>({\n * \tpool: { create: () => connect(), destroy: (connection) => connection.close() },\n * \thandler: (query, connection, { signal }) => connection.run(query, signal),\n * \tconcurrency: 4,\n * \tretries: 1,\n * })\n *\n * const rows = await worker.enqueue(query)\n * ```\n */\nexport function createWorker<TInput, TResource, TResult>(\n\toptions: WorkerOptions<TInput, TResource, TResult>,\n): WorkerInterface<TInput, TResult> {\n\treturn new Worker(options)\n}\n"],"mappings":"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"}

package/dist/src/server/index.cjs

@@ -4,9 +4,140 @@ let node_worker_threads = require("node:worker_threads");
 let _orkestrel_database_server = require("@orkestrel/database/server");
 let _orkestrel_queue = require("@orkestrel/queue");
 let _src_core = require("../core/index.cjs");
+//#region src/server/helpers.ts
+/**
+* Narrows an inbound `message` to a {@link Reply} for a given job `id` — no assertion.
+*
+* @remarks
+* A total predicate: a record whose `id` matches and whose `ok` discriminant is well-formed.
+* Anything else is rejected so a dispatch listener can ignore foreign or malformed messages.
+* It correlates against the `id` argument rather than narrowing one value alone, so it is a
+* correlated predicate rather than a `Guard<Reply>` and is not accepted where a `Guard` is.
+*
+* @param value - The inbound message to narrow
+* @param id - The job id a matching reply must carry
+* @returns True if the value is this job's well-formed reply; false otherwise
+*/
+function isReply(value, id) {
+	const outcome = (0, _orkestrel_contract.attempt)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+		if (value.id !== id) return false;
+		if (value.ok === true) return "value" in value;
+		return value.ok === false && typeof value.error === "string";
+	});
+	return outcome.success && outcome.value;
+}
+//#endregion
+//#region src/server/handlers.ts
+/**
+* Registers a worker-thread handler — the worker-side half of {@link createNodeWorker}.
+*
+* @remarks
+* Must be the spawned thread's module entry. It listens on the parent port for the
+* run/abort protocol: a `run` message narrows its `input` through `options.input` (an
+* invalid payload replies with an error envelope, never running the handler), then runs
+* `options.handler(input, { id: job, signal })` and replies `{ id, ok: true, value }` on success or
+* `{ id, ok: false, error }` on throw. Input-guard throws use the same failure envelope. If a
+* success value cannot be cloned, the post is retried as a clone-safe failure; if that post also
+* fails, the parent port closes so the main side observes thread exit instead of waiting forever.
+* The run envelope's `id` is fresh per dispatch and keys controllers, aborts, and replies;
+* its `job` is the stable Queue idempotency key exposed as `context.id` across retries
+* and restore. That job id identifies work, not a caller, and is not authentication or
+* authorization evidence. Each attempt has its own `AbortController`, so an `abort`
+* message for the correlation id fires the handler's `signal` (cooperative — the main
+* side ALSO terminates the thread, so a handler that ignores its signal is still stopped).
+* Every inbound message is narrowed with the inlined guards — no `as`. On the main thread
+* (`parentPort === null`) it is a no-op.
+*
+* @typeParam TInput - The work payload (inferred from `options.input`)
+* @typeParam TResult - The value the handler resolves (the reply payload)
+* @param options - The `input` guard and the `handler` (see {@link ServeWorkerOptions})
+*
+* @example
+* ```ts
+* // double.ts — a worker script
+* import { serveWorker } from '@orkestrel/worker/server'
+*
+* serveWorker<number, number>({
+* 	input: (value): value is number => typeof value === 'number',
+* 	handler: (value) => value * 2,
+* })
+* ```
+*/
+function serveWorker(options) {
+	const port = node_worker_threads.parentPort;
+	if (port === null) return;
+	const input = options.input;
+	const handler = options.handler;
+	const controllers = /* @__PURE__ */ new Map();
+	port.on("message", (raw) => {
+		let command;
+		let correlation;
+		let job;
+		let payload;
+		let carried = false;
+		try {
+			if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+				if ("command" in raw) command = raw.command;
+				if ("id" in raw) correlation = raw.id;
+				if ("job" in raw) job = raw.job;
+				if ("input" in raw) {
+					payload = raw.input;
+					carried = true;
+				}
+			}
+		} catch {
+			return;
+		}
+		if (typeof correlation !== "string") return;
+		const id = correlation;
+		if (command === "abort") {
+			controllers.get(id)?.abort();
+			return;
+		}
+		if (command !== "run" || typeof job !== "string" || !carried) return;
+		const entry = job;
+		const value = payload;
+		const controller = new AbortController();
+		controllers.set(id, controller);
+		Promise.resolve().then(() => {
+			if (!input(value)) throw new Error("input did not satisfy input guard");
+			return handler(value, {
+				id: entry,
+				signal: controller.signal
+			});
+		}).then((result) => {
+			controllers.delete(id);
+			port.postMessage({
+				id,
+				ok: true,
+				value: result
+			});
+		}).catch((error) => {
+			controllers.delete(id);
+			let message = "worker operation failed";
+			try {
+				message = error instanceof Error ? error.message : String(error);
+			} catch {}
+			try {
+				port.postMessage({
+					id,
+					ok: false,
+					error: message
+				});
+			} catch {
+				try {
+					port.close();
+				} catch {}
+			}
+		});
+	});
+}
+//#endregion
 //#region src/server/Thread.ts
 /**
-* Internal mutable implementation of the readonly {@link NodeThread} observation contract.
+* Represents the internal mutable implementation of the readonly {@link NodeThread} observation
+* contract.
 *
 * @remarks
 * Liveness and the first terminal error live behind runtime-private fields. Thread `error`,
@@ -83,43 +214,57 @@ var Thread = class {
 	}
 };
 //#endregion
-//#region src/server/validators.ts
+//#region src/server/Dispatch.ts
 /**
-* Narrow an inbound `message` to a {@link Reply} for a given job `id` — no assertion.
+* Represents one dispatched worker-thread job — the lifecycle entity behind a job posted to a
+* leased {@link NodeThread}, whose {@link promise} settles with the narrowed reply.
 *
 * @remarks
-* A total predicate: a record whose `id` matches and whose `ok` discriminant is well-formed.
-* Anything else is rejected so a dispatch listener can ignore foreign or malformed messages.
+* Mints a fresh per-dispatch correlation `id`, posts it with `job: context.id`, and settles
+* when the thread replies for that correlation id. The stable Queue job id reaches the worker
+* handler for idempotency across retries and restore; it is not caller identity or
+* authentication / authorization evidence. Per-job consumer context is explicit,
+* structured-cloneable `input`; ambient context is not worker-thread transport. A success
+* `value` is narrowed through `result` (a value that fails the guard rejects — the zero-`as`
+* type bridge); a failure rejects with the thread's error string. A thread that ALREADY died
+* rejects synchronously at construction from the latched {@link NodeThread.death} — its death
+* events fired before this dispatch existed and will never fire again, so waiting on the
+* listeners would dangle forever; the latch makes death total across every event ordering. If
+* the thread `error`s / `exit`s mid-flight the job rejects. On a `context.signal` abort it
+* contains the cooperative `abort` post, evicts the thread, and observes `terminate()`
+* settlement because CPU-bound work cannot honour the signal.
 *
-* @param value - The inbound message to narrow
-* @param id - The job id a matching reply must carry
-* @returns `true` when the value is this job's well-formed reply
-*/
-function isReply(value, id) {
-	const outcome = (0, _orkestrel_contract.attempt)(() => {
-		if (!(0, _orkestrel_contract.isRecord)(value)) return false;
-		if (value.id !== id) return false;
-		if (value.ok === true) return "value" in value;
-		return value.ok === false && typeof value.error === "string";
-	});
-	return outcome.success && outcome.value;
-}
-//#endregion
-//#region src/server/Dispatch.ts
-/**
-* Internal lifecycle entity for one dispatched worker-thread job.
+* It owns stable `message` / `messageerror` / death listener identities, settlement,
+* result-guard containment, and abort eviction for one dispatch. Deserialization failure, a
+* matching-id malformed reply, and abort each evict and terminate the thread before rejecting,
+* with termination failure preserved. Non-record, id-less, hostile-id, and foreign-id chatter
+* is ignored. Every per-job listener (`message` / `messageerror` / `error` / `exit` / `abort`)
+* is removed on settle.
 *
-* @remarks
-* Owns stable `message` / `messageerror` / death listener identities, settlement, result-guard
-* containment, and abort eviction for one dispatch. Deserialization failure, a matching-id
-* malformed reply, and abort each evict and terminate the thread before rejecting, with
-* termination failure preserved. Non-record, id-less, hostile-id, and foreign-id chatter is ignored.
+* Eviction reaches `alive` for a {@link NodeThread} this package produced. Against a
+* consumer-supplied `NodeThread` an abort or a `messageerror` still terminates the supplied
+* `worker` and rejects the job, and the implementer owns flipping its own `alive`.
+*
+* @typeParam TResult - The reply type the `result` guard narrows to
+*
+* @example
+* ```ts
+* import { createThread, Dispatch } from '@orkestrel/worker/server'
+*
+* const isNumber = (value: unknown): value is number => typeof value === 'number'
+*
+* const thread = await createThread(new URL('./double.js', import.meta.url))
+* const controller = new AbortController()
+* const job = new Dispatch(thread, 21, { id: 'job-1', signal: controller.signal }, isNumber)
+* console.log(await job.promise) // 42
+* await thread.worker.terminate()
+* ```
 */
 var Dispatch = class {
 	#thread;
 	#worker;
 	#input;
-	#execution;
+	#context;
 	#result;
 	#id = crypto.randomUUID();
 	#promise;
@@ -131,11 +276,11 @@ var Dispatch = class {
 	#exitHandler;
 	#abortHandler;
 	#settled = false;
-	constructor(thread, input, execution, result) {
+	constructor(thread, input, context, result) {
 		this.#thread = thread;
 		this.#worker = thread.worker;
 		this.#input = input;
-		this.#execution = execution;
+		this.#context = context;
 		this.#result = result;
 		const settlement = Promise.withResolvers();
 		this.#promise = settlement.promise;
@@ -160,15 +305,15 @@ var Dispatch = class {
 		this.#worker.on("messageerror", this.#messageErrorHandler);
 		this.#worker.on("error", this.#errorHandler);
 		this.#worker.on("exit", this.#exitHandler);
-		if (this.#execution.signal.aborted) {
+		if (this.#context.signal.aborted) {
 			this.#abort();
 			return;
 		}
-		this.#execution.signal.addEventListener("abort", this.#abortHandler, { once: true });
+		this.#context.signal.addEventListener("abort", this.#abortHandler, { once: true });
 		try {
 			this.#worker.postMessage({
 				id: this.#id,
-				job: this.#execution.id,
+				job: this.#context.id,
 				command: "run",
 				input: this.#input
 			});
@@ -215,7 +360,7 @@ var Dispatch = class {
 		} catch (cause) {
 			notification.push(cause);
 		}
-		this.#terminate(this.#execution.signal.reason, notification);
+		this.#terminate(this.#context.signal.reason, notification);
 	}
 	#terminate(error, notification = []) {
 		if (this.#settled) return;
@@ -259,183 +404,21 @@ var Dispatch = class {
 		this.#worker.off("messageerror", this.#messageErrorHandler);
 		this.#worker.off("error", this.#errorHandler);
 		this.#worker.off("exit", this.#exitHandler);
-		this.#execution.signal.removeEventListener("abort", this.#abortHandler);
+		this.#context.signal.removeEventListener("abort", this.#abortHandler);
 	}
 };
 //#endregion
-//#region src/server/helpers.ts
-/**
-* Spawn one worker thread and resolve a live {@link NodeThread} once it comes online.
-*
-* @remarks
-* Constructs the thread with the `script` module and the cloned `workerData`, then
-* resolves on the thread's `online` event (rejecting on an early `error` OR an `exit`
-* that arrives before `online`, so the spawn promise is total — it can never dangle on a
-* thread that died without erroring). The wrapper attaches persistent `error` / `exit`
-* listeners that flip `alive` to `false` AND latch the first terminal event on
-* {@link NodeThread.death}: a crash is observable to an in-flight {@link dispatch} (via
-* its own listeners), to the pool's `validate` (via `alive`), and — crucially — to a
-* dispatch that attaches AFTER the death (via the latch). A `messageerror` is terminal too,
-* so a thread whose inbound payload could not be deserialized is never reused. The latch
-* closes a real race: a thread can become terminal before the readiness promise continuation
-* hands it to `dispatch`, leaving no future death event for that dispatch to observe. Without
-* the latch, that job would wait forever. The pool's `create` hook calls this.
-*
-* @param script - The worker module each thread runs (must call `serveWorker`)
-* @param workerData - Opaque, structured-cloneable data handed to the thread at spawn
-* @returns A promise resolving the online {@link NodeThread}
-*/
-function spawnThread(script, workerData) {
-	return new Thread(script, workerData).promise;
-}
-/**
-* Dispatch one job to a leased {@link NodeThread} and await its narrowed reply.
-*
-* @remarks
-* Mints a fresh per-dispatch correlation `id`, posts it with `job: execution.id`, and
-* resolves when the thread replies for that correlation id. The stable Queue job id reaches
-* the worker handler for idempotency across retries and restore; it is not caller identity or
-* authentication / authorization evidence. Per-job consumer context remains explicit,
-* structured-cloneable `input`; ambient context is not worker-thread transport. A success
-* `value` is narrowed through `result` (a value that fails the guard
-* rejects — the zero-`as` type bridge), a failure rejects with the thread's error string.
-* A thread that ALREADY died rejects synchronously at entry from the latched
-* {@link NodeThread.death} — its death events fired before this dispatch existed and will
-* never fire again, so waiting on the listeners below would dangle forever; the latch makes
-* death total across every event ordering. If the thread `error`s / `exit`s mid-flight it is
-* marked dead and the
-* job rejects. An inbound `messageerror` also evicts and terminates the thread before
-* rejection. On `execution.signal` abort it contains the cooperative `abort` post,
-* evicts the thread, and observes `terminate()` settlement because CPU-bound work cannot
-* honour the signal; the freed pool slot then gets a fresh thread. Every per-job listener
-* (`message` / `messageerror` / `error` / `exit` / `abort`) is removed on settle.
-*
-* @typeParam TResult - The reply type the `result` guard narrows to
-* @param thread - The leased thread to run the job on
-* @param input - The work payload (structured-cloned to the thread)
-* @param execution - The per-attempt handle; its `signal` aborts → terminate + evict
-* @param result - The {@link Guard} narrowing the reply value with no assertion
-* @returns A promise resolving the narrowed `TResult`, or rejecting on error / abort
-*/
-function dispatch(thread, input, execution, result) {
-	return new Dispatch(thread, input, execution, result).promise;
-}
-//#endregion
-//#region src/server/handlers.ts
-/**
-* Register a worker-thread handler — the worker-side half of {@link createNodeWorker}.
-*
-* @remarks
-* Must be the spawned thread's module entry. It listens on the parent port for the
-* run/abort protocol: a `run` message narrows its `input` through `options.input` (an
-* invalid payload replies with an error envelope, never running the handler), then runs
-* `options.handler(input, { id: job, signal })` and replies `{ id, ok: true, value }` on success or
-* `{ id, ok: false, error }` on throw. Input-guard throws use the same failure envelope. If a
-* success value cannot be cloned, the post is retried as a clone-safe failure; if that post also
-* fails, the parent port closes so the main side observes thread exit instead of waiting forever.
-* The run envelope's `id` is fresh per dispatch and keys controllers, aborts, and replies;
-* its `job` is the stable Queue idempotency key exposed as `execution.id` across retries
-* and restore. That job id identifies work, not a caller, and is not authentication or
-* authorization evidence. Each attempt has its own `AbortController`, so an `abort`
-* message for the correlation id fires the handler's `signal` (cooperative — the main
-* side ALSO terminates the thread, so a handler that ignores its signal is still stopped).
-* Every inbound message is narrowed with the inlined guards — no `as`. On the main thread
-* (`parentPort === null`) it is a no-op.
-*
-* @typeParam TInput - The work payload (inferred from `options.input`)
-* @typeParam TResult - The value the handler resolves (the reply payload)
-* @param options - The `input` guard and the `handler` (see {@link ServeWorkerOptions})
-*
-* @example
-* ```ts
-* // double.ts — a worker script
-* import { serveWorker } from '@orkestrel/worker/server'
-*
-* serveWorker<number, number>({
-* 	input: (value): value is number => typeof value === 'number',
-* 	handler: (value) => value * 2,
-* })
-* ```
-*/
-function serveWorker(options) {
-	const port = node_worker_threads.parentPort;
-	if (port === null) return;
-	const input = options.input;
-	const handler = options.handler;
-	const controllers = /* @__PURE__ */ new Map();
-	port.on("message", (raw) => {
-		let command;
-		let correlation;
-		let job;
-		let payload;
-		let carried = false;
-		try {
-			if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
-				if ("command" in raw) command = raw.command;
-				if ("id" in raw) correlation = raw.id;
-				if ("job" in raw) job = raw.job;
-				if ("input" in raw) {
-					payload = raw.input;
-					carried = true;
-				}
-			}
-		} catch {
-			return;
-		}
-		if (typeof correlation !== "string") return;
-		const id = correlation;
-		if (command === "abort") {
-			controllers.get(id)?.abort();
-			return;
-		}
-		if (command !== "run" || typeof job !== "string" || !carried) return;
-		const execution = job;
-		const value = payload;
-		const controller = new AbortController();
-		controllers.set(id, controller);
-		Promise.resolve().then(() => {
-			if (!input(value)) throw new Error("input did not satisfy input guard");
-			return handler(value, {
-				id: execution,
-				signal: controller.signal
-			});
-		}).then((result) => {
-			controllers.delete(id);
-			port.postMessage({
-				id,
-				ok: true,
-				value: result
-			});
-		}).catch((error) => {
-			controllers.delete(id);
-			let message = "worker operation failed";
-			try {
-				message = error instanceof Error ? error.message : String(error);
-			} catch {}
-			try {
-				port.postMessage({
-					id,
-					ok: false,
-					error: message
-				});
-			} catch {
-				try {
-					port.close();
-				} catch {}
-			}
-		});
-	});
-}
-//#endregion
 //#region src/server/NodeWorker.ts
 /**
-* Internal composition entity backing {@link createNodeWorker}.
+* Represents the internal composition entity backing {@link createNodeWorker}.
 *
 * @remarks
 * Supplies bound Pool and Queue operations without nested function assignments. The resulting
-* public entity remains the plain core {@link WorkerInterface}.
+* public entity is the plain core {@link WorkerInterface}.
 */
 var NodeWorker = class {
+	#on;
+	#error;
 	#script;
 	#input;
 	#result;
@@ -445,6 +428,8 @@ var NodeWorker = class {
 	#timeout;
 	#store;
 	constructor(options) {
+		this.#on = options.on;
+		this.#error = options.error;
 		this.#script = options.script;
 		this.#input = options.input;
 		this.#result = options.result;
@@ -463,6 +448,8 @@ var NodeWorker = class {
 				...this.#concurrency !== void 0 ? { max: this.#concurrency } : {}
 			},
 			handler: this.#handle.bind(this),
+			...this.#on !== void 0 ? { on: this.#on } : {},
+			...this.#error !== void 0 ? { error: this.#error } : {},
 			...this.#concurrency !== void 0 ? { concurrency: this.#concurrency } : {},
 			...this.#retries !== void 0 ? { retries: this.#retries } : {},
 			...this.#timeout !== void 0 ? { timeout: this.#timeout } : {},
@@ -470,7 +457,7 @@ var NodeWorker = class {
 		});
 	}
 	#create() {
-		return spawnThread(this.#script, this.#workerData);
+		return new Thread(this.#script, this.#workerData).promise;
 	}
 	async #destroy(thread) {
 		await thread.worker.terminate();
@@ -478,21 +465,55 @@ var NodeWorker = class {
 	#validate(thread) {
 		return thread.alive && thread.worker.threadId > 0;
 	}
-	#handle(input, thread, execution) {
+	#handle(input, thread, context) {
 		const outcome = (0, _orkestrel_contract.attempt)(() => this.#input(input));
 		if (!outcome.success) return Promise.reject(outcome.error);
 		if (!outcome.value) return Promise.reject(/* @__PURE__ */ new Error("input did not satisfy input guard"));
-		return dispatch(thread, input, execution, this.#result);
+		return new Dispatch(thread, input, context, this.#result).promise;
 	}
 };
 //#endregion
 //#region src/server/factories.ts
 /**
-* Create a persistent JSON-file {@link QueueStoreInterface} — the core
+* Creates one live worker thread and resolves it as a {@link NodeThread} after it comes
+* online.
+*
+* @remarks
+* Constructs the thread with the `script` module and the cloned `workerData`, then
+* resolves on the thread's `online` event (rejecting on an early `error` OR an `exit`
+* that arrives before `online`, so the spawn promise is total — it can never dangle on a
+* thread that died without erroring). The returned entity attaches persistent `error` /
+* `exit` listeners that flip `alive` to `false` AND latch the first terminal event on
+* {@link NodeThread.death}: a crash is observable to an in-flight {@link Dispatch} (through
+* its own listeners), to a pool's `validate` (through `alive`), and — crucially — to a
+* dispatch that attaches AFTER the death (through the latch). A `messageerror` is terminal
+* too, so a thread whose inbound payload could not be deserialized is never reused. The latch
+* closes a real race: a thread can become terminal before the readiness promise continuation
+* hands it to a {@link Dispatch}, leaving no future death event for that dispatch to observe.
+* Without the latch, that job would wait forever. {@link createNodeWorker} spawns its pooled
+* threads the same way; reach for this to drive one thread yourself.
+*
+* @param script - The worker module the thread runs (its module must call `serveWorker`)
+* @param workerData - Opaque, structured-cloneable data handed to the thread at spawn
+* @returns A promise resolving the online {@link NodeThread}
+*
+* @example
+* ```ts
+* import { createThread } from '@orkestrel/worker/server'
+*
+* const thread = await createThread(new URL('./double.js', import.meta.url))
+* await thread.worker.terminate()
+* ```
+*/
+function createThread(script, workerData) {
+	return new Thread(script, workerData).promise;
+}
+/**
+* Creates a persistent JSON-file {@link QueueStoreInterface} — the core
 * `createDatabaseQueueStore` over a server {@link createJSONDriver}.
 *
 * @remarks
-* A queue's durable state is just a database table, so JSON persistence reuses the
+* A queue's durable state is a database table, so JSON persistence reuses the
 * existing JSON-file driver rather than a bespoke store: the entries are written to
 * (and reloaded from) the file at `path`, surviving a process restart. There is no new
 * class — the store engine ({@link createDatabaseQueueStore}) is shared, and only the
@@ -521,20 +542,21 @@ function createJSONQueueStore(path, input) {
 	return (0, _orkestrel_queue.createDatabaseQueueStore)(input, (0, _orkestrel_database_server.createJSONDriver)(path));
 }
 /**
-* Create a CPU-parallel worker over `node:worker_threads` — a thin specialization of the
+* Creates a CPU-parallel worker over `node:worker_threads` — a thin specialization of the
 * core `createWorker` whose pooled resource is a worker THREAD.
 *
 * @remarks
 * Composition, not reimplementation: all concurrency, retries, per-attempt timeout,
 * lifecycle, and durability are the core `Worker`'s (a `Queue` ⨉ `Pool`). This factory
-* supplies only the thread pairing — the pool `create`s a thread (via `spawnThread`),
-* `destroy`s it with `terminate()`, and `validate`s it by `alive && threadId > 0` (so an
-* evicted / crashed thread is dropped and replaced) — and an internal handler that
-* narrows the input through `options.input` (fail-fast before the structured-clone
-* boundary) then `dispatch`es the job to the leased thread, narrowing the reply through
+* supplies only the thread pairing — the pool `create`s a thread (the same spawn
+* {@link createThread} publishes), `destroy`s it with `terminate()`, and `validate`s it by
+* `alive && threadId > 0` (so an evicted / crashed thread is dropped and replaced) — and an
+* internal handler that narrows the input through `options.input` (fail-fast before the
+* structured-clone boundary) then runs a {@link Dispatch} against the leased thread,
+* narrowing the reply through
 * `options.result`. Both generics INFER from the `input` / `result` guards, so call sites
 * need no explicit type arguments. The boundary is crossed with ZERO `as`: the guards
-* reconstruct `TInput` / `TResult` by validation (AGENTS §14). An `abort` / `timeout`
+* reconstruct `TInput` / `TResult` by validation. An `abort` / `timeout`
 * TERMINATES the in-flight thread (CPU-bound work can't honour a signal) and evicts it; a
 * subsequent job spawns a fresh thread. The worker script's module must call
 * `serveWorker`. Returns the plain {@link WorkerInterface} — its methods are the Worker's.
@@ -542,7 +564,7 @@ function createJSONQueueStore(path, input) {
 * @typeParam TInput - The work payload each job carries (inferred from `input`)
 * @typeParam TResult - The value a thread resolves for a job (inferred from `result`)
 * @param options - The `script` plus the `input` / `result` guards and optional
-*   `workerData` / `concurrency` / `retries` / `timeout` / `store`
+*   `on` / `error` / `workerData` / `concurrency` / `retries` / `timeout` / `store`
 *   (see {@link NodeWorkerOptions})
 * @returns A working {@link WorkerInterface} backed by a thread pool
 *
@@ -565,11 +587,11 @@ function createNodeWorker(options) {
 	return new NodeWorker(options).build();
 }
 //#endregion
+exports.Dispatch = Dispatch;
 exports.createJSONQueueStore = createJSONQueueStore;
 exports.createNodeWorker = createNodeWorker;
-exports.dispatch = dispatch;
+exports.createThread = createThread;
 exports.isReply = isReply;
 exports.serveWorker = serveWorker;
-exports.spawnThread = spawnThread;
 
 //# sourceMappingURL=index.cjs.map