@orkestrel/worker 0.0.10 → 0.0.11

package/README.md

@@ -10,13 +10,13 @@ observable (a typed `emitter` re-exposes the underlying queue's job lifecycle
 — `enqueue` / `start` / `retry` / `success` / `failure` / `abort` / `drain`).
 For CPU-parallel work, the server surface's `createNodeWorker` specializes the
 core `createWorker` over a pool of `node:worker_threads`, crossing the
-structured-clone boundary with zero `as` via `input` / `result` guards. Each
+structured-clone boundary with zero `as` through `input` / `result` guards. Each
 thread handler receives `{ id, signal }`: `id` is the Queue's stable idempotency
 key across retries and crash restore, while `signal` is per attempt. The wire
 protocol separately mints a fresh correlation id for each dispatch so a stale
 reply cannot settle a later retry. The stable id identifies work, not a caller,
 and is not authentication or authorization evidence; per-job consumer context
-remains explicit structured-cloneable input rather than ambient thread state.
+is explicit, structured-cloneable input rather than ambient thread state.
 Part of the `@orkestrel` line.
 
 ## Install
@@ -27,6 +27,8 @@ npm install @orkestrel/worker
 
 ## Requirements
 
+The package runs under these conditions:
+
 - Node.js >= 22.12.0
 - ESM and CommonJS builds ship for both the core and server entry points
 
@@ -68,11 +70,11 @@ await worker.destroy()
 
 For the full surface — the `Worker` facade, `createNodeWorker` / `serveWorker`,
 the durable `createJSONQueueStore`, the observable `emitter`, and usage
-patterns — see [`guides/src/worker.md`](guides/src/worker.md).
+patterns — see [`guides/worker.md`](guides/worker.md).
 
 ## Package
 
-Published with two entry points per the `exports` field in `package.json`:
+Published with the entry points the `exports` field in `package.json` names:
 the environment-agnostic core (`.`) and the Node-only server surface
 (`./server`).
 

package/dist/src/core/index.cjs

@@ -4,8 +4,8 @@ let _orkestrel_pool = require("@orkestrel/pool");
 let _orkestrel_queue = require("@orkestrel/queue");
 //#region src/core/Worker.ts
 /**
-* A resource-backed job worker — a thin facade composing a `Queue` (`@orkestrel/queue`)
-* with a `Pool` (`@orkestrel/pool`).
+* Represents a resource-backed job worker — a thin facade composing a `Queue`
+* (`@orkestrel/queue`) with a `Pool` (`@orkestrel/pool`).
 *
 * @remarks
 * - **Composition, not reimplementation.** The Worker owns a `Pool` (built from
@@ -20,7 +20,7 @@ let _orkestrel_queue = require("@orkestrel/queue");
 *   options. At most one resource exists per in-flight job by default, and idle resources are
 *   reused across jobs.
 * - **Acquire over the attempt signal.** Each job acquires using the attempt's
-*   `execution.signal`, so an `abort` / `timeout` while waiting for a resource rejects
+*   `context.signal`, so an `abort` / `timeout` while waiting for a resource rejects
 *   the acquire — the Queue then handles retry / rejection, and there is no token to
 *   release (the resource was never leased).
 * - **Lifecycle (§10).** `enqueue` / `restore` / `start` / `stop` / `pause` / `resume` /
@@ -120,10 +120,10 @@ var Worker = class {
 		this.#teardown(ending);
 		return ending.promise;
 	}
-	async #handle(input, execution) {
-		const token = await this.#pool.acquire(execution.signal);
+	async #handle(input, context) {
+		const token = await this.#pool.acquire(context.signal);
 		try {
-			return await this.#handler(input, token.value, execution);
+			return await this.#handler(input, token.value, context);
 		} finally {
 			token.release();
 		}
@@ -159,14 +159,14 @@ var Worker = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create a resource-backed job worker — a `Queue` (`@orkestrel/queue`) marrying a `Pool`
+* Creates a resource-backed job worker — a `Queue` (`@orkestrel/queue`) marrying a `Pool`
 * (`@orkestrel/pool`). Each enqueued input runs through the handler against an
 * automatically acquired pooled resource (released when the job settles), with the
 * queue's bounded concurrency, retries, and per-attempt timeout / abort.
 *
 * @remarks
-* The pool's `max` defaults to `concurrency`, so resources match the jobs in flight and
-* are reused across jobs. A handler that throws still releases its resource (the
+* Default for the pool's `max`: the `concurrency` value, so resources match the jobs in flight.
+* Resources are reused across jobs. A handler that throws still releases its resource (the
 * acquire/release pair brackets the call in a `finally`), so a later job reuses it. The
 * lifecycle (`start` / `stop` / `pause` / `resume` / `abort` / `clear` / `destroy`)
 * delegates to the queue; `destroy` also tears the pool down. Observable (§13): a typed
@@ -175,8 +175,8 @@ var Worker = class {
 * @typeParam TInput - The work input each job carries
 * @typeParam TResource - The pooled resource each job runs against
 * @typeParam TResult - The value the handler resolves for a job
-* @param options - The `handler` and `pool` plus optional `concurrency` (default `1`),
-*   `retries` (default `0`), and a default per-attempt `timeout` in milliseconds
+* @param options - The `handler` and `pool` plus the optional `concurrency`, `retries`,
+*   `timeout`, `store`, `on`, and `error` keys (see {@link WorkerOptions})
 * @returns A working {@link WorkerInterface}
 *
 * @example

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

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","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,mBAAA,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,iBAAA,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,gBAAA,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.cjs","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/core/index.d.cts

@@ -2,19 +2,19 @@ import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { PoolOptions } from '@orkestrel/pool';
+import { QueueContext } from '@orkestrel/queue';
 import { QueueEntryOptions } from '@orkestrel/queue';
-import { QueueExecution } from '@orkestrel/queue';
 import { QueueStoreInterface } from '@orkestrel/queue';
 
 /**
- * Create a resource-backed job worker — a `Queue` (`@orkestrel/queue`) marrying a `Pool`
+ * Creates a resource-backed job worker — a `Queue` (`@orkestrel/queue`) marrying a `Pool`
  * (`@orkestrel/pool`). Each enqueued input runs through the handler against an
  * automatically acquired pooled resource (released when the job settles), with the
  * queue's bounded concurrency, retries, and per-attempt timeout / abort.
  *
  * @remarks
- * The pool's `max` defaults to `concurrency`, so resources match the jobs in flight and
- * are reused across jobs. A handler that throws still releases its resource (the
+ * Default for the pool's `max`: the `concurrency` value, so resources match the jobs in flight.
+ * Resources are reused across jobs. A handler that throws still releases its resource (the
  * acquire/release pair brackets the call in a `finally`), so a later job reuses it. The
  * lifecycle (`start` / `stop` / `pause` / `resume` / `abort` / `clear` / `destroy`)
  * delegates to the queue; `destroy` also tears the pool down. Observable (§13): a typed
@@ -23,8 +23,8 @@ import { QueueStoreInterface } from '@orkestrel/queue';
  * @typeParam TInput - The work input each job carries
  * @typeParam TResource - The pooled resource each job runs against
  * @typeParam TResult - The value the handler resolves for a job
- * @param options - The `handler` and `pool` plus optional `concurrency` (default `1`),
- *   `retries` (default `0`), and a default per-attempt `timeout` in milliseconds
+ * @param options - The `handler` and `pool` plus the optional `concurrency`, `retries`,
+ *   `timeout`, `store`, `on`, and `error` keys (see {@link WorkerOptions})
  * @returns A working {@link WorkerInterface}
  *
  * @example
@@ -44,8 +44,8 @@ import { QueueStoreInterface } from '@orkestrel/queue';
 export declare function createWorker<TInput, TResource, TResult>(options: WorkerOptions_2<TInput, TResource, TResult>): WorkerInterface<TInput, TResult>;
 
 /**
- * A resource-backed job worker — a thin facade composing a `Queue` (`@orkestrel/queue`)
- * with a `Pool` (`@orkestrel/pool`).
+ * Represents a resource-backed job worker — a thin facade composing a `Queue`
+ * (`@orkestrel/queue`) with a `Pool` (`@orkestrel/pool`).
  *
  * @remarks
  * - **Composition, not reimplementation.** The Worker owns a `Pool` (built from
@@ -60,7 +60,7 @@ export declare function createWorker<TInput, TResource, TResult>(options: Worker
  *   options. At most one resource exists per in-flight job by default, and idle resources are
  *   reused across jobs.
  * - **Acquire over the attempt signal.** Each job acquires using the attempt's
- *   `execution.signal`, so an `abort` / `timeout` while waiting for a resource rejects
+ *   `context.signal`, so an `abort` / `timeout` while waiting for a resource rejects
  *   the acquire — the Queue then handles retry / rejection, and there is no token to
  *   release (the resource was never leased).
  * - **Lifecycle (§10).** `enqueue` / `restore` / `start` / `stop` / `pause` / `resume` /
@@ -103,7 +103,7 @@ declare class Worker_2<TInput, TResource, TResult> implements WorkerInterface<TI
 export { Worker_2 as Worker }
 
 /**
- * The push observation surface of a {@link WorkerInterface} (AGENTS §13) — the job
+ * Represents the push observation surface of a {@link WorkerInterface} — the job
  * lifecycle a fire-and-forget observer subscribes to, surfacing the underlying queue's
  * moments so a Worker consumer never reaches through to the internal `Queue`.
  *
@@ -115,37 +115,37 @@ export { Worker_2 as Worker }
  * map RE-EXPOSES the queue lifecycle the worker surfaces (`enqueue` / `start` / `retry` /
  * `success` / `failure` / `abort` / `drain`) as the worker's OWN events — wired from the
  * underlying queue's emitter at construction, so a buggy observer is isolated exactly as
- * on the queue (a throw routes to the worker emitter's `error` handler, AGENTS §13). The
+ * on the queue (a throw routes to the worker emitter's `error` handler). The
  * pool's create / acquire / release events stay the pool's internal concern (a Worker
  * manages its own resources); a consumer who wants them observes a `Pool` directly.
  * Declared as a `type` alias (§4.5).
  */
 declare type WorkerEventMap_2<TResult> = {
-    /** A job was accepted — its id (delegated from the underlying queue's `enqueue`). */
+    /** Fires when a job is accepted — its id (delegated from the underlying queue's `enqueue`). */
     readonly enqueue: readonly [id: string];
-    /** A job's attempt began running — its id. */
+    /** Fires when a job's attempt begins running — its id. */
     readonly start: readonly [id: string];
-    /** A failed job attempt is being retried — its id + the next (1-based) attempt index. */
+    /** Fires when a failed job attempt is being retried — its id + the next (1-based) attempt index. */
     readonly retry: readonly [id: string, attempt: number];
-    /** A job settled successfully — its id + the resolved result. */
+    /** Fires when a job settles successfully — its id + the resolved result. */
     readonly success: readonly [id: string, result: TResult];
-    /** A job settled with a terminal failure — its id + the error. */
+    /** Fires when a job settles with a terminal failure — its id + the error. */
     readonly failure: readonly [id: string, error: unknown];
-    /** The worker was aborted — the queue's coded abort error retaining the caller reason. */
+    /** Fires when the worker is aborted — the queue's coded abort error retaining the caller reason. */
     readonly abort: readonly [reason: unknown];
-    /** The worker went idle — no pending jobs and none in flight. */
+    /** Fires when the worker goes idle — no pending jobs and none in flight. */
     readonly drain: readonly [];
 };
 export { WorkerEventMap_2 as WorkerEventMap }
 
 /** Runs one worker job with a leased pool resource. */
-export declare type WorkerHandler<TInput, TResource, TResult> = (input: TInput, resource: TResource, execution: QueueExecution) => Promise<TResult> | TResult;
+export declare type WorkerHandler<TInput, TResource, TResult> = (input: TInput, resource: TResource, context: QueueContext) => Promise<TResult> | TResult;
 
 /**
- * A resource-backed job worker — a Queue whose handler runs against a pooled resource.
+ * Represents a resource-backed job worker — a Queue whose handler runs against a pooled resource.
  *
  * @remarks
- * Exposes a typed {@link emitter} (AGENTS §13) carrying the job lifecycle
+ * Exposes a typed {@link emitter} carrying the job lifecycle
  * ({@link WorkerEventMap}) — the underlying queue's moments re-exposed as the worker's own,
  * so a consumer never reaches through to internals. Emitting is observation-only: a buggy
  * observer is isolated exactly as on the queue (a throw routes to the emitter's `error`
@@ -158,24 +158,24 @@ export declare interface WorkerInterface<TInput, TResult> {
     readonly paused: boolean;
     readonly stopped: boolean;
     enqueue(input: TInput, options?: QueueEntryOptions): Promise<TResult>;
-    /** Re-enqueue outstanding entries loaded from the store; no-op without a store. */
+    /** Re-enqueues outstanding entries loaded from the store; no-op without a store. */
     restore(): Promise<void>;
     start(): void;
-    /** Stop the queue and await current-loop and durable cleanup quiescence. */
+    /** Stops the queue and awaits current-loop and durable cleanup quiescence. */
     stop(): Promise<void>;
     pause(): void;
     resume(): void;
     /**
-     * Cancel in-flight work, reject pending work, and await queue-owned cleanup.
+     * Cancels in-flight work, rejects pending work, and awaits queue-owned cleanup.
      *
      * @param reason - Optional cause retained by the queue's coded abort error
      * @returns The underlying queue's stable abort barrier
      */
     abort(reason?: unknown): Promise<void>;
-    /** Drop pending work and await its durable cleanup. */
+    /** Drops pending work and awaits its durable cleanup. */
     clear(): Promise<void>;
     /**
-     * Tear down the queue, then the pool, and finally the worker emitter.
+     * Tears down the queue, then the pool, and finally the worker emitter.
      *
      * @returns One stable barrier shared by every call; it rejects with the original sole
      *   cleanup failure or an ordered `AggregateError` when both queue and pool fail
@@ -184,17 +184,18 @@ export declare interface WorkerInterface<TInput, TResult> {
 }
 
 /**
- * Options for `createWorker`.
+ * Configures `createWorker`.
  *
  * @remarks
  * - `handler` — runs each job against an acquired pool resource; rejecting triggers a
  *   retry while attempts remain (delegated to the underlying queue).
- * - `pool` — the {@link PoolOptions} for the resource the handler runs against; its
- *   `max` defaults to `concurrency` so resources match the jobs in flight.
- * - `concurrency` — the maximum jobs in flight at once; defaults to `1` and must be a
- *   positive safe integer, as validated by the underlying queue.
- * - `retries` — the default extra attempts per job on failure; defaults to `0`.
- * - `timeout` — the default per-attempt deadline in milliseconds; defaults to none.
+ * - `pool` — the {@link PoolOptions} for the resource the handler runs against, sized so
+ *   resources match the jobs in flight. Default for its `max`: the `concurrency` value.
+ * - `concurrency` — the maximum jobs in flight at once; it must be a positive safe
+ *   integer, as validated by the underlying queue. Default: 1.
+ * - `retries` — the default extra attempts per job on failure. Default: 0.
+ * - `timeout` — the default per-attempt deadline in milliseconds. Default: no per-attempt
+ *   deadline.
  * - `store` — durable backing; outstanding entries survive a restart; call
  *   `restore()` to re-run them.
  * - `on` — the reserved {@link EmitterHooks} key (§8): initial listeners for the worker's
@@ -203,13 +204,13 @@ export declare interface WorkerInterface<TInput, TResult> {
  */
 declare interface WorkerOptions_2<TInput, TResource, TResult> {
     readonly on?: EmitterHooks<WorkerEventMap_2<TResult>>;
-    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    /** Holds the emitter's listener-error handler; a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
     readonly handler: WorkerHandler<TInput, TResource, TResult>;
     readonly pool: PoolOptions<TResource>;
     readonly concurrency?: number;
     readonly retries?: number;
-    /** Integer milliseconds in `0..2_147_483_647`; `0` disables the per-attempt deadline. */
+    /** Holds integer milliseconds in `0..2_147_483_647`; `0` disables the per-attempt deadline. */
     readonly timeout?: number;
     readonly store?: QueueStoreInterface<TInput>;
 }

package/dist/src/core/index.d.ts

@@ -2,19 +2,19 @@ import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { PoolOptions } from '@orkestrel/pool';
+import { QueueContext } from '@orkestrel/queue';
 import { QueueEntryOptions } from '@orkestrel/queue';
-import { QueueExecution } from '@orkestrel/queue';
 import { QueueStoreInterface } from '@orkestrel/queue';
 
 /**
- * Create a resource-backed job worker — a `Queue` (`@orkestrel/queue`) marrying a `Pool`
+ * Creates a resource-backed job worker — a `Queue` (`@orkestrel/queue`) marrying a `Pool`
  * (`@orkestrel/pool`). Each enqueued input runs through the handler against an
  * automatically acquired pooled resource (released when the job settles), with the
  * queue's bounded concurrency, retries, and per-attempt timeout / abort.
  *
  * @remarks
- * The pool's `max` defaults to `concurrency`, so resources match the jobs in flight and
- * are reused across jobs. A handler that throws still releases its resource (the
+ * Default for the pool's `max`: the `concurrency` value, so resources match the jobs in flight.
+ * Resources are reused across jobs. A handler that throws still releases its resource (the
  * acquire/release pair brackets the call in a `finally`), so a later job reuses it. The
  * lifecycle (`start` / `stop` / `pause` / `resume` / `abort` / `clear` / `destroy`)
  * delegates to the queue; `destroy` also tears the pool down. Observable (§13): a typed
@@ -23,8 +23,8 @@ import { QueueStoreInterface } from '@orkestrel/queue';
  * @typeParam TInput - The work input each job carries
  * @typeParam TResource - The pooled resource each job runs against
  * @typeParam TResult - The value the handler resolves for a job
- * @param options - The `handler` and `pool` plus optional `concurrency` (default `1`),
- *   `retries` (default `0`), and a default per-attempt `timeout` in milliseconds
+ * @param options - The `handler` and `pool` plus the optional `concurrency`, `retries`,
+ *   `timeout`, `store`, `on`, and `error` keys (see {@link WorkerOptions})
  * @returns A working {@link WorkerInterface}
  *
  * @example
@@ -44,8 +44,8 @@ import { QueueStoreInterface } from '@orkestrel/queue';
 export declare function createWorker<TInput, TResource, TResult>(options: WorkerOptions_2<TInput, TResource, TResult>): WorkerInterface<TInput, TResult>;
 
 /**
- * A resource-backed job worker — a thin facade composing a `Queue` (`@orkestrel/queue`)
- * with a `Pool` (`@orkestrel/pool`).
+ * Represents a resource-backed job worker — a thin facade composing a `Queue`
+ * (`@orkestrel/queue`) with a `Pool` (`@orkestrel/pool`).
  *
  * @remarks
  * - **Composition, not reimplementation.** The Worker owns a `Pool` (built from
@@ -60,7 +60,7 @@ export declare function createWorker<TInput, TResource, TResult>(options: Worker
  *   options. At most one resource exists per in-flight job by default, and idle resources are
  *   reused across jobs.
  * - **Acquire over the attempt signal.** Each job acquires using the attempt's
- *   `execution.signal`, so an `abort` / `timeout` while waiting for a resource rejects
+ *   `context.signal`, so an `abort` / `timeout` while waiting for a resource rejects
  *   the acquire — the Queue then handles retry / rejection, and there is no token to
  *   release (the resource was never leased).
  * - **Lifecycle (§10).** `enqueue` / `restore` / `start` / `stop` / `pause` / `resume` /
@@ -103,7 +103,7 @@ declare class Worker_2<TInput, TResource, TResult> implements WorkerInterface<TI
 export { Worker_2 as Worker }
 
 /**
- * The push observation surface of a {@link WorkerInterface} (AGENTS §13) — the job
+ * Represents the push observation surface of a {@link WorkerInterface} — the job
  * lifecycle a fire-and-forget observer subscribes to, surfacing the underlying queue's
  * moments so a Worker consumer never reaches through to the internal `Queue`.
  *
@@ -115,37 +115,37 @@ export { Worker_2 as Worker }
  * map RE-EXPOSES the queue lifecycle the worker surfaces (`enqueue` / `start` / `retry` /
  * `success` / `failure` / `abort` / `drain`) as the worker's OWN events — wired from the
  * underlying queue's emitter at construction, so a buggy observer is isolated exactly as
- * on the queue (a throw routes to the worker emitter's `error` handler, AGENTS §13). The
+ * on the queue (a throw routes to the worker emitter's `error` handler). The
  * pool's create / acquire / release events stay the pool's internal concern (a Worker
  * manages its own resources); a consumer who wants them observes a `Pool` directly.
  * Declared as a `type` alias (§4.5).
  */
 declare type WorkerEventMap_2<TResult> = {
-    /** A job was accepted — its id (delegated from the underlying queue's `enqueue`). */
+    /** Fires when a job is accepted — its id (delegated from the underlying queue's `enqueue`). */
     readonly enqueue: readonly [id: string];
-    /** A job's attempt began running — its id. */
+    /** Fires when a job's attempt begins running — its id. */
     readonly start: readonly [id: string];
-    /** A failed job attempt is being retried — its id + the next (1-based) attempt index. */
+    /** Fires when a failed job attempt is being retried — its id + the next (1-based) attempt index. */
     readonly retry: readonly [id: string, attempt: number];
-    /** A job settled successfully — its id + the resolved result. */
+    /** Fires when a job settles successfully — its id + the resolved result. */
     readonly success: readonly [id: string, result: TResult];
-    /** A job settled with a terminal failure — its id + the error. */
+    /** Fires when a job settles with a terminal failure — its id + the error. */
     readonly failure: readonly [id: string, error: unknown];
-    /** The worker was aborted — the queue's coded abort error retaining the caller reason. */
+    /** Fires when the worker is aborted — the queue's coded abort error retaining the caller reason. */
     readonly abort: readonly [reason: unknown];
-    /** The worker went idle — no pending jobs and none in flight. */
+    /** Fires when the worker goes idle — no pending jobs and none in flight. */
     readonly drain: readonly [];
 };
 export { WorkerEventMap_2 as WorkerEventMap }
 
 /** Runs one worker job with a leased pool resource. */
-export declare type WorkerHandler<TInput, TResource, TResult> = (input: TInput, resource: TResource, execution: QueueExecution) => Promise<TResult> | TResult;
+export declare type WorkerHandler<TInput, TResource, TResult> = (input: TInput, resource: TResource, context: QueueContext) => Promise<TResult> | TResult;
 
 /**
- * A resource-backed job worker — a Queue whose handler runs against a pooled resource.
+ * Represents a resource-backed job worker — a Queue whose handler runs against a pooled resource.
  *
  * @remarks
- * Exposes a typed {@link emitter} (AGENTS §13) carrying the job lifecycle
+ * Exposes a typed {@link emitter} carrying the job lifecycle
  * ({@link WorkerEventMap}) — the underlying queue's moments re-exposed as the worker's own,
  * so a consumer never reaches through to internals. Emitting is observation-only: a buggy
  * observer is isolated exactly as on the queue (a throw routes to the emitter's `error`
@@ -158,24 +158,24 @@ export declare interface WorkerInterface<TInput, TResult> {
     readonly paused: boolean;
     readonly stopped: boolean;
     enqueue(input: TInput, options?: QueueEntryOptions): Promise<TResult>;
-    /** Re-enqueue outstanding entries loaded from the store; no-op without a store. */
+    /** Re-enqueues outstanding entries loaded from the store; no-op without a store. */
     restore(): Promise<void>;
     start(): void;
-    /** Stop the queue and await current-loop and durable cleanup quiescence. */
+    /** Stops the queue and awaits current-loop and durable cleanup quiescence. */
     stop(): Promise<void>;
     pause(): void;
     resume(): void;
     /**
-     * Cancel in-flight work, reject pending work, and await queue-owned cleanup.
+     * Cancels in-flight work, rejects pending work, and awaits queue-owned cleanup.
      *
      * @param reason - Optional cause retained by the queue's coded abort error
      * @returns The underlying queue's stable abort barrier
      */
     abort(reason?: unknown): Promise<void>;
-    /** Drop pending work and await its durable cleanup. */
+    /** Drops pending work and awaits its durable cleanup. */
     clear(): Promise<void>;
     /**
-     * Tear down the queue, then the pool, and finally the worker emitter.
+     * Tears down the queue, then the pool, and finally the worker emitter.
      *
      * @returns One stable barrier shared by every call; it rejects with the original sole
      *   cleanup failure or an ordered `AggregateError` when both queue and pool fail
@@ -184,17 +184,18 @@ export declare interface WorkerInterface<TInput, TResult> {
 }
 
 /**
- * Options for `createWorker`.
+ * Configures `createWorker`.
  *
  * @remarks
  * - `handler` — runs each job against an acquired pool resource; rejecting triggers a
  *   retry while attempts remain (delegated to the underlying queue).
- * - `pool` — the {@link PoolOptions} for the resource the handler runs against; its
- *   `max` defaults to `concurrency` so resources match the jobs in flight.
- * - `concurrency` — the maximum jobs in flight at once; defaults to `1` and must be a
- *   positive safe integer, as validated by the underlying queue.
- * - `retries` — the default extra attempts per job on failure; defaults to `0`.
- * - `timeout` — the default per-attempt deadline in milliseconds; defaults to none.
+ * - `pool` — the {@link PoolOptions} for the resource the handler runs against, sized so
+ *   resources match the jobs in flight. Default for its `max`: the `concurrency` value.
+ * - `concurrency` — the maximum jobs in flight at once; it must be a positive safe
+ *   integer, as validated by the underlying queue. Default: 1.
+ * - `retries` — the default extra attempts per job on failure. Default: 0.
+ * - `timeout` — the default per-attempt deadline in milliseconds. Default: no per-attempt
+ *   deadline.
  * - `store` — durable backing; outstanding entries survive a restart; call
  *   `restore()` to re-run them.
  * - `on` — the reserved {@link EmitterHooks} key (§8): initial listeners for the worker's
@@ -203,13 +204,13 @@ export declare interface WorkerInterface<TInput, TResult> {
  */
 declare interface WorkerOptions_2<TInput, TResource, TResult> {
     readonly on?: EmitterHooks<WorkerEventMap_2<TResult>>;
-    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    /** Holds the emitter's listener-error handler; a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
     readonly handler: WorkerHandler<TInput, TResource, TResult>;
     readonly pool: PoolOptions<TResource>;
     readonly concurrency?: number;
     readonly retries?: number;
-    /** Integer milliseconds in `0..2_147_483_647`; `0` disables the per-attempt deadline. */
+    /** Holds integer milliseconds in `0..2_147_483_647`; `0` disables the per-attempt deadline. */
     readonly timeout?: number;
     readonly store?: QueueStoreInterface<TInput>;
 }

package/dist/src/core/index.js

@@ -3,8 +3,8 @@ import { Pool } from "@orkestrel/pool";
 import { Queue } from "@orkestrel/queue";
 //#region src/core/Worker.ts
 /**
-* A resource-backed job worker — a thin facade composing a `Queue` (`@orkestrel/queue`)
-* with a `Pool` (`@orkestrel/pool`).
+* Represents a resource-backed job worker — a thin facade composing a `Queue`
+* (`@orkestrel/queue`) with a `Pool` (`@orkestrel/pool`).
 *
 * @remarks
 * - **Composition, not reimplementation.** The Worker owns a `Pool` (built from
@@ -19,7 +19,7 @@ import { Queue } from "@orkestrel/queue";
 *   options. At most one resource exists per in-flight job by default, and idle resources are
 *   reused across jobs.
 * - **Acquire over the attempt signal.** Each job acquires using the attempt's
-*   `execution.signal`, so an `abort` / `timeout` while waiting for a resource rejects
+*   `context.signal`, so an `abort` / `timeout` while waiting for a resource rejects
 *   the acquire — the Queue then handles retry / rejection, and there is no token to
 *   release (the resource was never leased).
 * - **Lifecycle (§10).** `enqueue` / `restore` / `start` / `stop` / `pause` / `resume` /
@@ -119,10 +119,10 @@ var Worker = class {
 		this.#teardown(ending);
 		return ending.promise;
 	}
-	async #handle(input, execution) {
-		const token = await this.#pool.acquire(execution.signal);
+	async #handle(input, context) {
+		const token = await this.#pool.acquire(context.signal);
 		try {
-			return await this.#handler(input, token.value, execution);
+			return await this.#handler(input, token.value, context);
 		} finally {
 			token.release();
 		}
@@ -158,14 +158,14 @@ var Worker = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create a resource-backed job worker — a `Queue` (`@orkestrel/queue`) marrying a `Pool`
+* Creates a resource-backed job worker — a `Queue` (`@orkestrel/queue`) marrying a `Pool`
 * (`@orkestrel/pool`). Each enqueued input runs through the handler against an
 * automatically acquired pooled resource (released when the job settles), with the
 * queue's bounded concurrency, retries, and per-attempt timeout / abort.
 *
 * @remarks
-* The pool's `max` defaults to `concurrency`, so resources match the jobs in flight and
-* are reused across jobs. A handler that throws still releases its resource (the
+* Default for the pool's `max`: the `concurrency` value, so resources match the jobs in flight.
+* Resources are reused across jobs. A handler that throws still releases its resource (the
 * acquire/release pair brackets the call in a `finally`), so a later job reuses it. The
 * lifecycle (`start` / `stop` / `pause` / `resume` / `abort` / `clear` / `destroy`)
 * delegates to the queue; `destroy` also tears the pool down. Observable (§13): a typed
@@ -174,8 +174,8 @@ var Worker = class {
 * @typeParam TInput - The work input each job carries
 * @typeParam TResource - The pooled resource each job runs against
 * @typeParam TResult - The value the handler resolves for a job
-* @param options - The `handler` and `pool` plus optional `concurrency` (default `1`),
-*   `retries` (default `0`), and a default per-attempt `timeout` in milliseconds
+* @param options - The `handler` and `pool` plus the optional `concurrency`, `retries`,
+*   `timeout`, `store`, `on`, and `error` keys (see {@link WorkerOptions})
 * @returns A working {@link WorkerInterface}
 *
 * @example