@orkestrel/worker 0.0.10 → 0.0.12

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

@@ -1,22 +1,25 @@
-import { ContractShape } from '@orkestrel/contract';
-import { Guard } from '@orkestrel/contract';
-import { Infer } from '@orkestrel/contract';
-import { QueueExecution } from '@orkestrel/queue';
-import { QueueStoreInterface } from '@orkestrel/queue';
-import { Worker } from 'node:worker_threads';
-import { WorkerInterface } from '@orkestrel/worker';
+import type { ContractShape } from '@orkestrel/contract';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { Guard } from '@orkestrel/contract';
+import type { Infer } from '@orkestrel/contract';
+import type { QueueContext } from '@orkestrel/queue';
+import type { QueueStoreInterface } from '@orkestrel/queue';
+import type { Worker } from 'node:worker_threads';
+import type { WorkerEventMap } from '@orkestrel/worker';
+import type { WorkerInterface } from '@orkestrel/worker';
 
 /**
- * Create a persistent JSON-file {@link QueueStoreInterface} — the core
+ * 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
  * driver changes where the bytes live. The `input` shape must be JSON-serializable
- * (the JSON driver round-trips it as JSON). Build a second store over the SAME `path` to
+ * (the JSON driver round-trips it as JSON). Build a second store over the same `path` to
  * resume the outstanding entries a prior store persisted.
  *
  * @typeParam TInput - The contract shape of each entry's `input` payload
@@ -39,28 +42,29 @@ import { WorkerInterface } from '@orkestrel/worker';
 export declare function createJSONQueueStore<TInput extends ContractShape>(path: string, input: TInput): QueueStoreInterface<Infer<TInput>>;
 
 /**
- * Create a CPU-parallel worker over `node:worker_threads` — a thin specialization of the
- * core `createWorker` whose pooled resource is a worker THREAD.
+ * 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
- * `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`
- * TERMINATES the in-flight thread (CPU-bound work can't honour a signal) and evicts it; a
+ * 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`. `TInput` and `TResult` infer from the `input` and `result` guards, so
+ * call sites need no explicit type arguments. The boundary is crossed with no `as`: the
+ * guards 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.
  *
  * @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
  *
@@ -82,65 +86,126 @@ export declare function createJSONQueueStore<TInput extends ContractShape>(path:
 export declare function createNodeWorker<TInput, TResult>(options: NodeWorkerOptions<TInput, TResult>): WorkerInterface<TInput, TResult>;
 
 /**
- * Dispatch one job to a leased {@link NodeThread} and await its narrowed reply.
+ * Creates one live worker thread and resolves it as a {@link NodeThread} after it comes
+ * online.
  *
  * @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,
+ * 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 on 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 only 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()
+ * ```
+ */
+export declare function createThread(script: string | URL, workerData?: unknown): Promise<NodeThread>;
+
+/**
+ * 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
+ * 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 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.
+ * `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 had 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.
+ *
+ * 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.
+ *
+ * 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
- * @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
+ *
+ * @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()
+ * ```
  */
-export declare function dispatch<TResult>(thread: NodeThread, input: unknown, execution: QueueExecution, result: Guard<TResult>): Promise<TResult>;
+export declare class Dispatch<TResult> {
+    #private;
+    constructor(thread: NodeThread, input: unknown, context: QueueContext, result: Guard<TResult>);
+    get promise(): Promise<TResult>;
+}
 
 /**
- * Narrow an inbound `message` to a {@link Reply} for a given job `id` — no assertion.
+ * Narrows an inbound `message` to a {@link Reply} for a given correlation `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` when the value is this job's well-formed reply
+ * @param id - The per-dispatch correlation id a matching reply must carry
+ * @returns True if the value is this dispatch's well-formed reply; false otherwise
  */
 export declare function isReply(value: unknown, id: string): value is Reply;
 
 /**
- * A live worker thread plus its latched liveness state — the pooled resource a
+ * Represents a live worker thread plus its latched liveness state — the pooled resource a
  * {@link createNodeWorker} leases per job.
  *
  * @remarks
  * `alive` starts `true` and flips to `false` when the thread `error`s, reports a
  * `messageerror`, exits, or is evicted on abort; the pool's `validate` reads
  * `alive && worker.threadId > 0`, so a
- * dead thread is destroyed and replaced rather than reused. `death` LATCHES the first
+ * dead thread is destroyed and replaced rather than reused. `death` latches the first
  * terminal event (`error` / `messageerror`, or a synthesized error on `exit`) — the death-signal
- * record a `dispatch` checks at entry, so a job dispatched AFTER the thread died (its
+ * record a {@link Dispatch} checks at construction, so a job dispatched after the thread died (its
  * death events already fired and will never fire again) rejects immediately instead of
  * awaiting events that already happened. A thread can become terminal before the readiness
  * promise continuation attaches dispatch listeners; the latch is what makes that ordering
  * safe. `worker` is the underlying
  * `node:worker_threads` thread (its `postMessage` / `terminate` drive the protocol).
+ *
+ * A dispatch marks a thread dead for a `NodeThread` this package produced, through
+ * {@link createThread} or a {@link createNodeWorker} pool. A foreign implementation of this
+ * interface owns flipping its own `alive` when its `worker` is terminated: an abort or a
+ * `messageerror` terminates the supplied `worker` and rejects the job, and leaves the
+ * implementer's `alive` and `death` exactly as the implementer reports them.
  */
 export declare interface NodeThread {
     readonly worker: Worker;
@@ -149,31 +214,40 @@ export declare interface NodeThread {
 }
 
 /**
- * Options for `createNodeWorker` — a CPU-parallel worker over `node:worker_threads`.
+ * Configures `createNodeWorker` — a CPU-parallel worker over `node:worker_threads`.
  *
  * @remarks
  * - `script` — the worker module each pooled thread runs; its module must call
  *   `serveWorker(...)`. Raw TypeScript is unflagged on Node 22.18+ and Node 23.6+;
  *   Node 22.12–22.17 and Node 23.0–23.5 require `--experimental-strip-types`. A built
- *   `.js` / `.mjs` script remains an alternative across supported Node versions.
- * - `input` — narrows the work payload BEFORE it crosses the structured-clone boundary
+ *   `.js` / `.mjs` script is an alternative across supported Node versions.
+ * - `input` — narrows the work payload before it crosses the structured-clone boundary
  *   (fail-fast) and supplies the `TInput` inference, so call sites need no type argument.
  * - `result` — narrows every reply value coming back from a thread; an invalid reply
  *   rejects the job. This is the zero-`as` type bridge — `TResult` is inferred from it.
- * - `workerData` — opaque data cloned to every thread once at spawn (read there via
- *   `serveWorker`'s host `workerData`); must be structured-cloneable.
+ * - `workerData` — opaque data cloned to every thread at spawn; the key mirrors the
+ *   `node:worker_threads` `Worker` constructor option of the same name, and the thread reads
+ *   it back from `node:worker_threads`. It must be structured-cloneable.
  * - `concurrency` — the maximum jobs in flight at once; the thread pool's `max` matches
- *   it, so at most this many threads exist. 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 / timeout; defaults to `0`.
- * - `timeout` — the default per-attempt deadline in milliseconds; defaults to none.
+ *   it, so at most this many threads exist. It must be a positive safe integer, as
+ *   validated by the underlying queue. Default: 1.
+ * - `retries` — the default extra attempts per job on failure / timeout. Default: 0.
+ * - `timeout` — the default per-attempt deadline in milliseconds. Default: no per-attempt
+ *   deadline.
  * - `store` — durable backing for outstanding jobs (survives a restart; `restore()`
  *   re-runs them).
+ * - `on` — the reserved {@link EmitterHooks} key: initial listeners for the worker's
+ *   {@link WorkerEventMap} (the job lifecycle it surfaces from its underlying queue), wired
+ *   at construction. A thread worker takes the same hooks as the core worker.
+ * - `error` — the emitter's listener-error handler; a listener throw routes
+ *   here, not to a domain event.
  *
  * @typeParam TInput - The work payload each job carries (inferred from `input`)
  * @typeParam TResult - The value a thread resolves for a job (inferred from `result`)
  */
 export declare interface NodeWorkerOptions<TInput, TResult> {
+    readonly on?: EmitterHooks<WorkerEventMap<TResult>>;
+    readonly error?: EmitterErrorHandler;
     readonly script: string | URL;
     readonly input: Guard<TInput>;
     readonly result: Guard<TResult>;
@@ -185,16 +259,15 @@ export declare interface NodeWorkerOptions<TInput, TResult> {
 }
 
 /**
- * A thread→main reply envelope — a success carrying an opaque `value`, or a failure with a
- * message — part of the internal wire protocol `createNodeWorker` posts and `serveWorker`
+ * Represents a thread→main reply envelope — a success carrying an opaque `value`, or a failure with a
+ * message — the reply half of the wire protocol `createNodeWorker` posts and `serveWorker`
  * answers.
  *
  * @remarks
- * Internal plumbing rather than public call surface, but centralized here per AGENTS §5 (an
- * impl file holds only its class / functions). A reply is a discriminated union on `ok`: a
+ * A reply is a discriminated union on `ok`: a
  * `true` carries any opaque `value` (narrowed at the boundary by the `result` guard,
  * with no `as`); a `false` carries a string `error`. The worker-side `serve.ts` cannot import
- * this (it loads as raw source in a spawned thread, AGENTS §5 exception) and posts the same
+ * this because it loads as raw source in a spawned thread, and posts the same
  * shape structurally. The `id` ties a reply to its job: id-less / foreign-id chatter is ignored,
  * while a matching-id malformed envelope taints the thread and causes dispatch to terminate it.
  */
@@ -209,7 +282,7 @@ export declare type Reply = {
 };
 
 /**
- * Register a worker-thread handler — the worker-side half of {@link createNodeWorker}.
+ * 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
@@ -220,11 +293,11 @@ export declare type Reply = {
  * 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
+ * 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).
+ * 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.
  *
@@ -246,16 +319,16 @@ export declare type Reply = {
 export declare function serveWorker<TInput, TResult>(options: ServeWorkerOptions<TInput, TResult>): void;
 
 /**
- * Options for `serveWorker` — the worker-side entry a thread script registers.
+ * Configures `serveWorker` — the worker-side entry a thread script registers.
  *
  * @remarks
  * - `input` — narrows each inbound payload inside the thread; an invalid payload replies
  *   with an error envelope rather than running the handler. Supplies the `TInput`
  *   inference for the handler.
- * - `handler` — runs one job; receives the narrowed input and the Queue's execution.
- *   `execution.id` is the stable Queue idempotency key across retries and crash restore;
+ * - `handler` — runs one job; receives the narrowed input and the Queue's context.
+ *   `context.id` is the stable Queue idempotency key across retries and crash restore;
  *   it identifies work, not a caller, and is not authentication or authorization evidence.
- *   `execution.signal` is per attempt and fires when the main side aborts that attempt
+ *   `context.signal` is per attempt and fires when the main side aborts that attempt
  *   (cooperative). The handler may be async; its resolved value (which must be
  *   structured-cloneable) is the reply.
  *
@@ -264,30 +337,7 @@ export declare function serveWorker<TInput, TResult>(options: ServeWorkerOptions
  */
 export declare interface ServeWorkerOptions<TInput, TResult> {
     readonly input: Guard<TInput>;
-    readonly handler: (input: TInput, execution: QueueExecution) => Promise<TResult> | TResult;
+    readonly handler: (input: TInput, context: QueueContext) => Promise<TResult> | TResult;
 }
 
-/**
- * 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}
- */
-export declare function spawnThread(script: string | URL, workerData: unknown): Promise<NodeThread>;
-
 export { }