@orkestrel/worker 0.0.1

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

@@ -0,0 +1,299 @@
+import { ContractShape } 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 '../core/index.ts';
+
+/**
+ * Create 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
+ * 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
+ * resume the outstanding entries a prior store persisted.
+ *
+ * @typeParam TInput - The contract shape of each entry's `input` payload
+ * @param path - The JSON file the entries are loaded from and flushed to
+ * @param input - The {@link ContractShape} for the work payload (the `input` column)
+ * @returns A JSON-file-backed {@link QueueStoreInterface}, typed by `input`
+ *
+ * @example
+ * ```ts
+ * import { stringShape } from '@src/core'
+ * import { createJSONQueueStore } from '@src/server'
+ *
+ * const store = createJSONQueueStore('data/queue.json', stringShape())
+ * await store.save({ id: 'job-1', input: 'https://example.com', attempts: 0 })
+ * // A later process resumes the outstanding work:
+ * const resumed = createJSONQueueStore('data/queue.json', stringShape())
+ * const outstanding = await resumed.load()
+ * ```
+ */
+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.
+ *
+ * @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
+ * 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`
+ *   (see {@link NodeWorkerOptions})
+ * @returns A working {@link WorkerInterface} backed by a thread pool
+ *
+ * @example
+ * ```ts
+ * import { createNodeWorker } from '@src/server'
+ *
+ * const worker = createNodeWorker({
+ * 	script: new URL('./double.js', import.meta.url),
+ * 	input: (value): value is number => typeof value === 'number',
+ * 	result: (value): value is number => typeof value === 'number',
+ * 	concurrency: 4,
+ * })
+ *
+ * const doubled = await worker.enqueue(21) // 42, computed on a worker thread
+ * worker.destroy() // terminates every thread
+ * ```
+ */
+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.
+ *
+ * @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
+ * 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.
+ *
+ * @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
+ */
+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.
+ *
+ * @remarks
+ * A total {@link Guard}-style predicate (never throws): a record whose `id` matches and
+ * whose `ok` discriminant is well-formed (a `true` carries any `value`; a `false` carries a
+ * string `error`). Anything else — another job's reply, a malformed payload — is `false`, so
+ * a {@link dispatch} listener ignores it (a thread that chatters on the channel can't corrupt
+ * a job).
+ *
+ * @param value - The inbound message to narrow
+ * @param id - The job id a matching reply must carry
+ * @returns `true` (narrowing `value` to {@link Reply}) when it is this job's well-formed reply
+ */
+export declare function isReply(value: unknown, id: string): value is Reply;
+
+/**
+ * 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` the moment the thread `error`s, `exit`s, 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
+ * 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
+ * `node:worker_threads` thread (its `postMessage` / `terminate` drive the protocol).
+ */
+export declare interface NodeThread {
+    readonly worker: Worker;
+    alive: boolean;
+    death: Error | undefined;
+}
+
+/**
+ * Options for `createNodeWorker` — a CPU-parallel worker over `node:worker_threads`.
+ *
+ * @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`.
+ * - `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.
+ * - `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`.
+ * - `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()`
+ *   re-runs them).
+ *
+ * @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 script: string | URL;
+    readonly input: Guard<TInput>;
+    readonly result: Guard<TResult>;
+    readonly workerData?: unknown;
+    readonly concurrency?: number;
+    readonly retries?: number;
+    readonly timeout?: number;
+    readonly store?: QueueStoreInterface<TInput>;
+}
+
+/**
+ * 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`
+ * 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
+ * `true` carries any opaque `value` (narrowed at the boundary by the `result` {@link 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.
+ */
+export declare type Reply = {
+    readonly id: string;
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly id: string;
+    readonly ok: false;
+    readonly error: string;
+};
+
+/**
+ * Register a worker-thread handler — the worker-side half of {@link createNodeWorker}.
+ *
+ * @remarks
+ * Must be the spawned thread's module entry. It listens on the parent port for the
+ * run/abort protocol: a `run` message narrows its `input` through `options.input` (an
+ * invalid payload replies with an error envelope, never running the handler), then runs
+ * `options.handler(input, { 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
+ * side ALSO terminates the thread, so a handler that ignores its signal is still stopped).
+ * Every inbound message is narrowed with the inlined guards — no `as`. On the main thread
+ * (`parentPort === null`) it is a no-op.
+ *
+ * @typeParam TInput - The work payload (inferred from `options.input`)
+ * @typeParam TResult - The value the handler resolves (the reply payload)
+ * @param options - The `input` guard and the `handler` (see {@link ServeWorkerOptions})
+ *
+ * @example
+ * ```ts
+ * // double.ts — a worker script
+ * import { serveWorker } from '@src/server'
+ *
+ * serveWorker<number, number>({
+ * 	input: (value): value is number => typeof value === 'number',
+ * 	handler: (value) => value * 2,
+ * })
+ * ```
+ */
+export declare function serveWorker<TInput, TResult>(options: ServeWorkerOptions<TInput, TResult>): void;
+
+/**
+ * Options for `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 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.
+ *
+ * @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;
+}
+
+/**
+ * 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). 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.
+ *
+ * @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 { }

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

@@ -0,0 +1,299 @@
+import { ContractShape } 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 '../core/index.ts';
+
+/**
+ * Create 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
+ * 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
+ * resume the outstanding entries a prior store persisted.
+ *
+ * @typeParam TInput - The contract shape of each entry's `input` payload
+ * @param path - The JSON file the entries are loaded from and flushed to
+ * @param input - The {@link ContractShape} for the work payload (the `input` column)
+ * @returns A JSON-file-backed {@link QueueStoreInterface}, typed by `input`
+ *
+ * @example
+ * ```ts
+ * import { stringShape } from '@src/core'
+ * import { createJSONQueueStore } from '@src/server'
+ *
+ * const store = createJSONQueueStore('data/queue.json', stringShape())
+ * await store.save({ id: 'job-1', input: 'https://example.com', attempts: 0 })
+ * // A later process resumes the outstanding work:
+ * const resumed = createJSONQueueStore('data/queue.json', stringShape())
+ * const outstanding = await resumed.load()
+ * ```
+ */
+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.
+ *
+ * @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
+ * 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`
+ *   (see {@link NodeWorkerOptions})
+ * @returns A working {@link WorkerInterface} backed by a thread pool
+ *
+ * @example
+ * ```ts
+ * import { createNodeWorker } from '@src/server'
+ *
+ * const worker = createNodeWorker({
+ * 	script: new URL('./double.js', import.meta.url),
+ * 	input: (value): value is number => typeof value === 'number',
+ * 	result: (value): value is number => typeof value === 'number',
+ * 	concurrency: 4,
+ * })
+ *
+ * const doubled = await worker.enqueue(21) // 42, computed on a worker thread
+ * worker.destroy() // terminates every thread
+ * ```
+ */
+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.
+ *
+ * @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
+ * 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.
+ *
+ * @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
+ */
+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.
+ *
+ * @remarks
+ * A total {@link Guard}-style predicate (never throws): a record whose `id` matches and
+ * whose `ok` discriminant is well-formed (a `true` carries any `value`; a `false` carries a
+ * string `error`). Anything else — another job's reply, a malformed payload — is `false`, so
+ * a {@link dispatch} listener ignores it (a thread that chatters on the channel can't corrupt
+ * a job).
+ *
+ * @param value - The inbound message to narrow
+ * @param id - The job id a matching reply must carry
+ * @returns `true` (narrowing `value` to {@link Reply}) when it is this job's well-formed reply
+ */
+export declare function isReply(value: unknown, id: string): value is Reply;
+
+/**
+ * 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` the moment the thread `error`s, `exit`s, 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
+ * 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
+ * `node:worker_threads` thread (its `postMessage` / `terminate` drive the protocol).
+ */
+export declare interface NodeThread {
+    readonly worker: Worker;
+    alive: boolean;
+    death: Error | undefined;
+}
+
+/**
+ * Options for `createNodeWorker` — a CPU-parallel worker over `node:worker_threads`.
+ *
+ * @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`.
+ * - `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.
+ * - `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`.
+ * - `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()`
+ *   re-runs them).
+ *
+ * @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 script: string | URL;
+    readonly input: Guard<TInput>;
+    readonly result: Guard<TResult>;
+    readonly workerData?: unknown;
+    readonly concurrency?: number;
+    readonly retries?: number;
+    readonly timeout?: number;
+    readonly store?: QueueStoreInterface<TInput>;
+}
+
+/**
+ * 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`
+ * 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
+ * `true` carries any opaque `value` (narrowed at the boundary by the `result` {@link 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.
+ */
+export declare type Reply = {
+    readonly id: string;
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly id: string;
+    readonly ok: false;
+    readonly error: string;
+};
+
+/**
+ * Register a worker-thread handler — the worker-side half of {@link createNodeWorker}.
+ *
+ * @remarks
+ * Must be the spawned thread's module entry. It listens on the parent port for the
+ * run/abort protocol: a `run` message narrows its `input` through `options.input` (an
+ * invalid payload replies with an error envelope, never running the handler), then runs
+ * `options.handler(input, { 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
+ * side ALSO terminates the thread, so a handler that ignores its signal is still stopped).
+ * Every inbound message is narrowed with the inlined guards — no `as`. On the main thread
+ * (`parentPort === null`) it is a no-op.
+ *
+ * @typeParam TInput - The work payload (inferred from `options.input`)
+ * @typeParam TResult - The value the handler resolves (the reply payload)
+ * @param options - The `input` guard and the `handler` (see {@link ServeWorkerOptions})
+ *
+ * @example
+ * ```ts
+ * // double.ts — a worker script
+ * import { serveWorker } from '@src/server'
+ *
+ * serveWorker<number, number>({
+ * 	input: (value): value is number => typeof value === 'number',
+ * 	handler: (value) => value * 2,
+ * })
+ * ```
+ */
+export declare function serveWorker<TInput, TResult>(options: ServeWorkerOptions<TInput, TResult>): void;
+
+/**
+ * Options for `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 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.
+ *
+ * @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;
+}
+
+/**
+ * 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). 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.
+ *
+ * @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 { }