@orkestrel/worker 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orkestrel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @orkestrel/worker
+
+A typed, resource-backed **job worker** for the `@orkestrel` line: a `Worker`
+is a `Queue` (`@orkestrel/queue`) whose handler runs against an automatically
+acquired resource leased from a `Pool` (`@orkestrel/pool`) — released when the
+job settles, even on throw. Composition, not reimplementation: all
+concurrency, retries, per-attempt timeout, abort, and durability are the
+Queue's; all idle reuse and `max` backpressure are the Pool's. The worker is
+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. Part
+of the `@orkestrel` line.
+
+## Install
+
+```sh
+npm install @orkestrel/worker
+```
+
+## Requirements
+
+- Node.js >= 24
+- ESM and CommonJS builds ship for both the core and server entry points
+
+## Usage
+
+```ts
+import { createWorker } from '@orkestrel/worker'
+
+const worker = createWorker<Query, Connection, Rows>({
+	pool: { create: () => connect(), destroy: (connection) => connection.close() },
+	handler: (query, connection, { signal }) => connection.run(query, signal),
+	concurrency: 4, // up to four jobs in flight; the pool defaults its `max` to match
+	retries: 1,
+})
+
+const rows = await worker.enqueue(query)
+worker.destroy() // tears down the queue, then the pool
+```
+
+CPU-parallel jobs over `node:worker_threads`:
+
+```ts
+import { createNodeWorker } from '@orkestrel/worker/server'
+
+const isNumber = (value: unknown): value is number => typeof value === 'number'
+
+const worker = createNodeWorker({
+	script: new URL('./double.js', import.meta.url),
+	input: isNumber,
+	result: isNumber,
+	concurrency: 4,
+})
+
+const doubled = await worker.enqueue(21) // 42, computed on a worker thread
+```
+
+## Guide
+
+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).
+
+## Package
+
+Published with two entry points per the `exports` field in `package.json`:
+the environment-agnostic core (`.`) and the Node-only server surface
+(`./server`).
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).

package/dist/src/core/index.cjs

@@ -0,0 +1,169 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_emitter = require("@orkestrel/emitter");
+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`).
+*
+* @remarks
+* - **Composition, not reimplementation.** The Worker owns a `Pool` (built from
+*   `options.pool`) and a `Queue` whose handler ACQUIRES a pooled resource, runs the
+*   user handler against it, and RELEASES it in a `finally`. All concurrency, retries,
+*   timeout, and lifecycle are the Queue's — the Worker adds only the resource pairing.
+* - **Resource ↔ concurrency.** The pool's `max` defaults to the worker's
+*   `concurrency` (default `1`), so at most one resource exists per in-flight job 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
+*   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` /
+*   `abort` / `clear` delegate to the queue; `count` / `active` / `paused` / `stopped`
+*   read it. `destroy` destroys the queue then tears the pool down, idempotently.
+* - **Durability.** An optional `store` is passed straight through to the queue, so the
+*   worker's outstanding jobs persist; `restore` re-runs them (delegated to the queue).
+* - **Observable (§13).** The owned {@link emitter} ({@link WorkerEventMap}) RE-EXPOSES the
+*   underlying queue's job lifecycle (`enqueue` / `start` / `retry` / `success` / `failure` /
+*   `abort` / `drain`) as the worker's OWN events — bridged from the inner queue's emitter at
+*   construction — so a consumer observes the worker without reaching through to internals.
+*   The bridge re-emits directly on the worker's own emitter; the worker emitter isolates a
+*   listener throw and routes it to its `error` handler (the `error` option), so a buggy
+*   worker observer can never corrupt the inner queue or pool — the bridge listener never
+*   throws, so the inner queue's own emit stays balanced. The pool's create / acquire /
+*   release events stay the pool's internal concern (a Worker manages its own resources);
+*   observe a `Pool` directly for those.
+*/
+var Worker = class {
+	#queue;
+	#pool;
+	#emitter;
+	#destroyed = false;
+	constructor(options) {
+		const concurrency = Math.max(1, options.concurrency ?? 1);
+		this.#emitter = new _orkestrel_emitter.Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#pool = new _orkestrel_pool.Pool({
+			...options.pool,
+			max: options.pool.max ?? concurrency
+		});
+		this.#queue = new _orkestrel_queue.Queue({
+			handler: async (input, execution) => {
+				const token = await this.#pool.acquire(execution.signal);
+				try {
+					return await options.handler(input, token.value, execution);
+				} finally {
+					token.release();
+				}
+			},
+			concurrency,
+			retries: options.retries,
+			timeout: options.timeout,
+			store: options.store
+		});
+		this.#bridge();
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get count() {
+		return this.#queue.count;
+	}
+	get active() {
+		return this.#queue.active;
+	}
+	get paused() {
+		return this.#queue.paused;
+	}
+	get stopped() {
+		return this.#queue.stopped;
+	}
+	enqueue(input, options) {
+		return this.#queue.enqueue(input, options);
+	}
+	restore() {
+		return this.#queue.restore();
+	}
+	start() {
+		this.#queue.start();
+	}
+	stop() {
+		this.#queue.stop();
+	}
+	pause() {
+		this.#queue.pause();
+	}
+	resume() {
+		this.#queue.resume();
+	}
+	abort(reason) {
+		this.#queue.abort(reason);
+	}
+	clear() {
+		this.#queue.clear();
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.#queue.destroy();
+		this.#pool.destroy();
+	}
+	#bridge() {
+		const queue = this.#queue.emitter;
+		queue.on("enqueue", (id) => this.#emitter.emit("enqueue", id));
+		queue.on("start", (id) => this.#emitter.emit("start", id));
+		queue.on("retry", (id, attempt) => this.#emitter.emit("retry", id, attempt));
+		queue.on("success", (id, result) => this.#emitter.emit("success", id, result));
+		queue.on("failure", (id, error) => this.#emitter.emit("failure", id, error));
+		queue.on("abort", (reason) => this.#emitter.emit("abort", reason));
+		queue.on("drain", () => this.#emitter.emit("drain"));
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create 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
+* 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
+* `emitter` surfaces the queue lifecycle (`enqueue` / `start` / `success` / `failure` / …).
+*
+* @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
+* @returns A working {@link WorkerInterface}
+*
+* @example
+* ```ts
+* import { createWorker } from '@src/core'
+*
+* const worker = createWorker<Query, Connection, Rows>({
+* 	pool: { create: () => connect(), destroy: (connection) => connection.close() },
+* 	handler: (query, connection, { signal }) => connection.run(query, signal),
+* 	concurrency: 4,
+* 	retries: 1,
+* })
+*
+* const rows = await worker.enqueue(query)
+* ```
+*/
+function createWorker(options) {
+	return new Worker(options);
+}
+//#endregion
+exports.Worker = Worker;
+exports.createWorker = createWorker;
+
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["#queue","#pool","#emitter","#bridge","#destroyed"],"sources":["../../../src/core/Worker.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { EmitterInterface } from '@orkestrel/emitter'\nimport type { QueueEntryOptions } from '@orkestrel/queue'\nimport type { WorkerEventMap, 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 pool's `max` defaults to the worker's\n *   `concurrency` (default `1`), so at most one resource exists per in-flight job and\n *   idle resources are 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. `destroy` destroys the queue then tears the pool down, idempotently.\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\t#destroyed = false\n\n\tconstructor(options: WorkerOptions<TInput, TResource, TResult>) {\n\t\tconst concurrency = Math.max(1, options.concurrency ?? 1)\n\t\tthis.#emitter = new Emitter<WorkerEventMap<TResult>>({ on: options?.on, error: options?.error })\n\t\tthis.#pool = new Pool<TResource>({\n\t\t\t...options.pool,\n\t\t\tmax: options.pool.max ?? concurrency,\n\t\t})\n\t\tthis.#queue = new Queue<TInput, TResult>({\n\t\t\thandler: async (input, execution) => {\n\t\t\t\tconst token = await this.#pool.acquire(execution.signal)\n\t\t\t\ttry {\n\t\t\t\t\treturn await options.handler(input, token.value, execution)\n\t\t\t\t} finally {\n\t\t\t\t\ttoken.release()\n\t\t\t\t}\n\t\t\t},\n\t\t\tconcurrency,\n\t\t\tretries: options.retries,\n\t\t\ttimeout: options.timeout,\n\t\t\tstore: options.store,\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(): void {\n\t\tthis.#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): void {\n\t\tthis.#queue.abort(reason)\n\t}\n\n\tclear(): void {\n\t\tthis.#queue.clear()\n\t}\n\n\tdestroy(): void {\n\t\tif (this.#destroyed) return\n\t\tthis.#destroyed = true\n\t\tthis.#queue.destroy()\n\t\tvoid this.#pool.destroy()\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 '@src/core'\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,IAAa,SAAb,MAA4F;CAC3F;CACA;CAIA;CACA,aAAa;CAEb,YAAY,SAAoD;EAC/D,MAAM,cAAc,KAAK,IAAI,GAAG,QAAQ,eAAe,CAAC;EACxD,KAAKE,WAAW,IAAI,mBAAA,QAAiC;GAAE,IAAI,SAAS;GAAI,OAAO,SAAS;EAAM,CAAC;EAC/F,KAAKD,QAAQ,IAAI,gBAAA,KAAgB;GAChC,GAAG,QAAQ;GACX,KAAK,QAAQ,KAAK,OAAO;EAC1B,CAAC;EACD,KAAKD,SAAS,IAAI,iBAAA,MAAuB;GACxC,SAAS,OAAO,OAAO,cAAc;IACpC,MAAM,QAAQ,MAAM,KAAKC,MAAM,QAAQ,UAAU,MAAM;IACvD,IAAI;KACH,OAAO,MAAM,QAAQ,QAAQ,OAAO,MAAM,OAAO,SAAS;IAC3D,UAAU;KACT,MAAM,QAAQ;IACf;GACD;GACA;GACA,SAAS,QAAQ;GACjB,SAAS,QAAQ;GACjB,OAAO,QAAQ;EAChB,CAAC;EACD,KAAKE,QAAQ;CACd;CAEA,IAAI,UAAqD;EACxD,OAAO,KAAKD;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,OAAa;EACZ,KAAKA,OAAO,KAAK;CAClB;CAEA,QAAc;EACb,KAAKA,OAAO,MAAM;CACnB;CAEA,SAAe;EACd,KAAKA,OAAO,OAAO;CACpB;CAEA,MAAM,QAAwB;EAC7B,KAAKA,OAAO,MAAM,MAAM;CACzB;CAEA,QAAc;EACb,KAAKA,OAAO,MAAM;CACnB;CAEA,UAAgB;EACf,IAAI,KAAKI,YAAY;EACrB,KAAKA,aAAa;EAClB,KAAKJ,OAAO,QAAQ;EACpB,KAAUC,MAAM,QAAQ;CACzB;CASA,UAAgB;EACf,MAAM,QAAQ,KAAKD,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC9GA,SAAgB,aACf,SACmC;CACnC,OAAO,IAAI,OAAO,OAAO;AAC1B"}

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

@@ -0,0 +1,193 @@
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { PoolOptions } from '@orkestrel/pool';
+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`
+ * (`@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
+ * 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
+ * `emitter` surfaces the queue lifecycle (`enqueue` / `start` / `success` / `failure` / …).
+ *
+ * @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
+ * @returns A working {@link WorkerInterface}
+ *
+ * @example
+ * ```ts
+ * import { createWorker } from '@src/core'
+ *
+ * const worker = createWorker<Query, Connection, Rows>({
+ * 	pool: { create: () => connect(), destroy: (connection) => connection.close() },
+ * 	handler: (query, connection, { signal }) => connection.run(query, signal),
+ * 	concurrency: 4,
+ * 	retries: 1,
+ * })
+ *
+ * const rows = await worker.enqueue(query)
+ * ```
+ */
+export declare function createWorker<TInput, TResource, TResult>(options: WorkerOptions<TInput, TResource, TResult>): WorkerInterface<TInput, TResult>;
+
+/**
+ * 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
+ *   `options.pool`) and a `Queue` whose handler ACQUIRES a pooled resource, runs the
+ *   user handler against it, and RELEASES it in a `finally`. All concurrency, retries,
+ *   timeout, and lifecycle are the Queue's — the Worker adds only the resource pairing.
+ * - **Resource ↔ concurrency.** The pool's `max` defaults to the worker's
+ *   `concurrency` (default `1`), so at most one resource exists per in-flight job 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
+ *   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` /
+ *   `abort` / `clear` delegate to the queue; `count` / `active` / `paused` / `stopped`
+ *   read it. `destroy` destroys the queue then tears the pool down, idempotently.
+ * - **Durability.** An optional `store` is passed straight through to the queue, so the
+ *   worker's outstanding jobs persist; `restore` re-runs them (delegated to the queue).
+ * - **Observable (§13).** The owned {@link emitter} ({@link WorkerEventMap}) RE-EXPOSES the
+ *   underlying queue's job lifecycle (`enqueue` / `start` / `retry` / `success` / `failure` /
+ *   `abort` / `drain`) as the worker's OWN events — bridged from the inner queue's emitter at
+ *   construction — so a consumer observes the worker without reaching through to internals.
+ *   The bridge re-emits directly on the worker's own emitter; the worker emitter isolates a
+ *   listener throw and routes it to its `error` handler (the `error` option), so a buggy
+ *   worker observer can never corrupt the inner queue or pool — the bridge listener never
+ *   throws, so the inner queue's own emit stays balanced. The pool's create / acquire /
+ *   release events stay the pool's internal concern (a Worker manages its own resources);
+ *   observe a `Pool` directly for those.
+ */
+declare class Worker_2<TInput, TResource, TResult> implements WorkerInterface<TInput, TResult> {
+    #private;
+    constructor(options: WorkerOptions<TInput, TResource, TResult>);
+    get emitter(): EmitterInterface<WorkerEventMap<TResult>>;
+    get count(): number;
+    get active(): number;
+    get paused(): boolean;
+    get stopped(): boolean;
+    enqueue(input: TInput, options?: QueueEntryOptions): Promise<TResult>;
+    restore(): Promise<void>;
+    start(): void;
+    stop(): void;
+    pause(): void;
+    resume(): void;
+    abort(reason?: unknown): void;
+    clear(): void;
+    destroy(): void;
+}
+export { Worker_2 as Worker }
+
+/**
+ * The push observation surface of a {@link WorkerInterface} (AGENTS §13) — 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`.
+ *
+ * @typeParam TResult - The value a job resolves (the `success` payload), mirroring the
+ *   {@link WorkerInterface}'s own `TResult`.
+ *
+ * @remarks
+ * A Worker is a `Queue`⨉`Pool` facade (both from their own `@orkestrel` packages); this
+ * 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
+ * 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).
+ */
+export declare type WorkerEventMap<TResult> = {
+    /** A job was accepted — its id (delegated from the underlying queue's `enqueue`). */
+    readonly enqueue: readonly [id: string];
+    /** A job's attempt began running — its id. */
+    readonly start: readonly [id: string];
+    /** 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. */
+    readonly success: readonly [id: string, result: TResult];
+    /** A job settled with a terminal failure — its id + the error. */
+    readonly failure: readonly [id: string, error: unknown];
+    /** The worker was aborted — the cancel reason. */
+    readonly abort: readonly [reason: unknown];
+    /** The worker went idle — no pending jobs and none in flight. */
+    readonly drain: readonly [];
+};
+
+/** 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;
+
+/**
+ * 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
+ * ({@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`
+ * handler, the `error` option).
+ */
+export declare interface WorkerInterface<TInput, TResult> {
+    readonly emitter: EmitterInterface<WorkerEventMap<TResult>>;
+    readonly count: number;
+    readonly active: number;
+    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. */
+    restore(): Promise<void>;
+    start(): void;
+    stop(): void;
+    pause(): void;
+    resume(): void;
+    abort(reason?: unknown): void;
+    clear(): void;
+    destroy(): void;
+}
+
+/**
+ * Options for `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`. Floored at `1`.
+ * - `retries` — the default extra attempts per job on failure; defaults to `0`.
+ * - `timeout` — the default per-attempt deadline in milliseconds; defaults to none.
+ * - `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
+ *   {@link WorkerEventMap} (the job lifecycle it surfaces from its underlying queue), wired
+ *   at construction.
+ */
+export declare interface WorkerOptions<TInput, TResource, TResult> {
+    readonly on?: EmitterHooks<WorkerEventMap<TResult>>;
+    /** The emitter's listener-error handler (AGENTS §13) — 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;
+    readonly timeout?: number;
+    readonly store?: QueueStoreInterface<TInput>;
+}
+
+export { }