@orkestrel/worker 0.0.4 → 0.0.6

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

@@ -1,4 +1,5 @@
 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';
@@ -25,8 +26,8 @@ import { WorkerInterface } from '../core/index.ts';
  *
  * @example
  * ```ts
- * import { stringShape } from '@src/core'
- * import { createJSONQueueStore } from '@src/server'
+ * import { stringShape } from '@orkestrel/contract'
+ * import { createJSONQueueStore } from '@orkestrel/worker/server'
  *
  * const store = createJSONQueueStore('data/queue.json', stringShape())
  * await store.save({ id: 'job-1', input: 'https://example.com', attempts: 0 })
@@ -65,7 +66,7 @@ export declare function createJSONQueueStore<TInput extends ContractShape>(path:
  *
  * @example
  * ```ts
- * import { createNodeWorker } from '@src/server'
+ * import { createNodeWorker } from '@orkestrel/worker/server'
  *
  * const worker = createNodeWorker({
  * 	script: new URL('./double.js', import.meta.url),
@@ -75,7 +76,7 @@ export declare function createJSONQueueStore<TInput extends ContractShape>(path:
  * })
  *
  * const doubled = await worker.enqueue(21) // 42, computed on a worker thread
- * worker.destroy() // terminates every thread
+ * await worker.destroy() // terminates every thread
  * ```
  */
 export declare function createNodeWorker<TInput, TResult>(options: NodeWorkerOptions<TInput, TResult>): WorkerInterface<TInput, TResult>;
@@ -84,19 +85,23 @@ export declare function createNodeWorker<TInput, TResult>(options: NodeWorkerOpt
  * Dispatch one job to a leased {@link NodeThread} and await its narrowed reply.
  *
  * @remarks
- * Mints a fresh `id`, posts a `run` envelope, and resolves when the thread replies for
- * that id: a success `value` is narrowed through `result` (a value that fails the guard
+ * Mints a fresh per-dispatch correlation `id`, posts it with `job: execution.id`, and
+ * resolves when the thread replies for that correlation id. The stable Queue job id reaches
+ * the worker handler for idempotency across retries and restore; it is not caller identity or
+ * authentication / authorization evidence. Per-job consumer context remains explicit,
+ * structured-cloneable `input`; ambient context is not worker-thread transport. A success
+ * `value` is narrowed through `result` (a value that fails the guard
  * rejects — the zero-`as` type bridge), a failure rejects with the thread's error string.
  * A thread that ALREADY died rejects synchronously at entry from the latched
- * {@link NodeThread.death} — its death events fired before this dispatch existed (under
- * load they arrive in one batched exit drain) and will never fire again, so waiting on
- * the listeners below would dangle forever; the latch makes the death total across every
- * event ordering. If the thread `error`s / `exit`s mid-flight it is marked dead and the
- * job rejects. On `execution.signal` abort it posts an `abort` envelope (cooperative) AND
- * evicts the thread — `alive = false` + `terminate()` — because CPU-bound work cannot
- * honour the signal; the freed pool slot then gets a fresh thread. Every listener (the
- * thread's `message` / `error` / `exit` and the signal's `abort`) is removed on settle,
- * and a `settled` guard prevents a double-settle.
+ * {@link NodeThread.death} — its death events fired before this dispatch existed and will
+ * never fire again, so waiting on the listeners below would dangle forever; the latch makes
+ * death total across every event ordering. If the thread `error`s / `exit`s mid-flight it is
+ * marked dead and the
+ * job rejects. An inbound `messageerror` also evicts and terminates the thread before
+ * rejection. On `execution.signal` abort it contains the cooperative `abort` post,
+ * evicts the thread, and observes `terminate()` settlement because CPU-bound work cannot
+ * honour the signal; the freed pool slot then gets a fresh thread. Every per-job listener
+ * (`message` / `messageerror` / `error` / `exit` / `abort`) is removed on settle.
  *
  * @typeParam TResult - The reply type the `result` guard narrows to
  * @param thread - The leased thread to run the job on
@@ -107,23 +112,6 @@ export declare function createNodeWorker<TInput, TResult>(options: NodeWorkerOpt
  */
 export declare function dispatch<TResult>(thread: NodeThread, input: unknown, execution: QueueExecution, result: Guard<TResult>): Promise<TResult>;
 
-/**
- * A runtime type predicate used to narrow a wire payload with no assertion.
- *
- * @remarks
- * Mirrors the core `Guard<T>` (a total `(value: unknown) => value is T` predicate,
- * AGENTS §14) but is re-declared here so the server workers surface is self-describing
- * and the worker-side `serve.ts` — which may not import from `@src/core` (it loads as
- * raw `.ts` inside a spawned thread) — shares the same vocabulary. A `Guard` NEVER
- * throws; adversarial input returns `false`. It is the zero-`as` bridge across the
- * structured-clone boundary: the main side narrows each reply value through the
- * `result` guard and the input through the `input` guard, so a generic `TInput` /
- * `TResult` is reconstructed by validation rather than asserted.
- *
- * @typeParam T - The type a value is narrowed to when the predicate holds
- */
-export declare type Guard<T> = (value: unknown) => value is T;
-
 /**
  * Narrow an inbound `message` to a {@link Reply} for a given job `id` — no assertion.
  *
@@ -142,16 +130,16 @@ export declare function isReply(value: unknown, id: string): value is Reply;
  * {@link createNodeWorker} leases per job.
  *
  * @remarks
- * `alive` starts `true` and flips to `false` the moment the thread `error`s, `exit`s, or
- * is evicted on abort; the pool's `validate` reads `alive && worker.threadId > 0`, so a
+ * `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
- * terminal event (`error`'s `Error`, or a synthesized one on `exit`) — the death-signal
+ * 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
  * death events already fired and will never fire again) rejects immediately instead of
- * awaiting events that already happened. Under event-loop pressure Node delivers a dead
- * thread's `online` + `error` + `exit` in ONE synchronous exit-drain batch, starving the
- * microtask chain that attaches the dispatch listeners until after every death event —
- * the latch is what makes that ordering safe. `worker` is the underlying
+ * 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).
  */
 export declare interface NodeThread {
@@ -165,8 +153,9 @@ export declare interface NodeThread {
  *
  * @remarks
  * - `script` — the worker module each pooled thread runs; its module must call
- *   `serveWorker(...)`. A `.ts` script requires Node ≥ 23.6 (native type-stripping); on
- *   older Node point this at a built `.js` / `.mjs`.
+ *   `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
  *   (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
@@ -174,7 +163,8 @@ export declare interface NodeThread {
  * - `workerData` — opaque data cloned to every thread once at spawn (read there via
  *   `serveWorker`'s host `workerData`); 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`. Floored at `1`.
+ *   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.
  * - `store` — durable backing for outstanding jobs (survives a restart; `restore()`
@@ -202,11 +192,11 @@ export declare interface NodeWorkerOptions<TInput, TResult> {
  * @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
- * `true` carries any opaque `value` (narrowed at the boundary by the `result` {@link Guard},
+ * `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
- * shape structurally. The `id` ties a reply to its job, so a stray / foreign-id message is
- * ignored.
+ * 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.
  */
 export declare type Reply = {
     readonly id: string;
@@ -225,9 +215,15 @@ export declare type Reply = {
  * Must be the spawned thread's module entry. It listens on the parent port for the
  * run/abort protocol: a `run` message narrows its `input` through `options.input` (an
  * invalid payload replies with an error envelope, never running the handler), then runs
- * `options.handler(input, { signal })` and replies `{ id, ok: true, value }` on success or
- * `{ id, ok: false, error }` on throw. Each in-flight job has its own `AbortController`,
- * so an `abort` message for that id fires the handler's `signal` (cooperative — the main
+ * `options.handler(input, { id: job, signal })` and replies `{ id, ok: true, value }` on success or
+ * `{ id, ok: false, error }` on throw. Input-guard throws use the same failure envelope. If a
+ * success value cannot be cloned, the post is retried as a clone-safe failure; if that post also
+ * fails, the parent port closes so the main side observes thread exit instead of waiting forever.
+ * The run envelope's `id` is fresh per dispatch and keys controllers, aborts, and replies;
+ * its `job` is the stable Queue idempotency key exposed as `execution.id` across retries
+ * and restore. That job id identifies work, not a caller, and is not authentication or
+ * authorization evidence. Each attempt has its own `AbortController`, so an `abort`
+ * message for the correlation id fires the handler's `signal` (cooperative — the main
  * side ALSO terminates the thread, so a handler that ignores its signal is still stopped).
  * Every inbound message is narrowed with the inlined guards — no `as`. On the main thread
  * (`parentPort === null`) it is a no-op.
@@ -239,7 +235,7 @@ export declare type Reply = {
  * @example
  * ```ts
  * // double.ts — a worker script
- * import { serveWorker } from '@src/server'
+ * import { serveWorker } from '@orkestrel/worker/server'
  *
  * serveWorker<number, number>({
  * 	input: (value): value is number => typeof value === 'number',
@@ -256,18 +252,19 @@ export declare function serveWorker<TInput, TResult>(options: ServeWorkerOptions
  * - `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 a `{ signal }` execution
- *   whose `AbortSignal` fires when the main side aborts the job (cooperative). May be
- *   async; its resolved value (which must be structured-cloneable) is the reply.
+ * - `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;
+ *   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
+ *   (cooperative). The handler may be async; its resolved value (which must be
+ *   structured-cloneable) is the reply.
  *
  * @typeParam TInput - The work payload (inferred from `input`)
  * @typeParam TResult - The value the handler resolves (the reply payload)
  */
 export declare interface ServeWorkerOptions<TInput, TResult> {
     readonly input: Guard<TInput>;
-    readonly handler: (input: TInput, execution: {
-        readonly signal: AbortSignal;
-    }) => Promise<TResult> | TResult;
+    readonly handler: (input: TInput, execution: QueueExecution) => Promise<TResult> | TResult;
 }
 
 /**
@@ -281,11 +278,11 @@ export declare interface ServeWorkerOptions<TInput, TResult> {
  * 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). The latch closes a real race:
- * under event-loop pressure a dead thread's `online` + `error` + `exit` are delivered in
- * ONE synchronous exit-drain batch, so every death event fires before the microtask chain
- * resolving this spawn can hand the thread to `dispatch` — without the latch that job
- * would await events that already fired, forever. The pool's `create` hook calls this.
+ * 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