@lostgradient/weft 0.2.0

package/dist/worker/worker-protocol-incompatible-error.js

@@ -0,0 +1,15 @@
+import { WeftError } from "../core/weft-error.js";
+export function workerProtocolIncompatibleMessage(versions) {
+  const receivedDisplay = versions.received === void 0 ? "unknown" : String(versions.received);
+  return `This server requires Weft worker protocol v${String(versions.expected)}; got v${receivedDisplay}. Upgrade the worker SDK to use qualified activity names (workflowType.activityName).`;
+}
+
+export class WorkerProtocolIncompatibleError extends WeftError {
+  expectedProtocolVersion;
+  receivedProtocolVersion;
+  constructor(versions) {
+    super("WorkerProtocolIncompatibleError", workerProtocolIncompatibleMessage(versions));
+    this.expectedProtocolVersion = versions.expected;
+    this.receivedProtocolVersion = versions.received;
+  }
+}

package/dist/worker/workflow-activity-binding.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Worker-side helper that turns a `workflows` map into the qualified-name
+ * activity table the RemoteWorker advertises and dispatches against.
+ *
+ * Protocol v2 (Phase 4) shifted activity advertisements from bare activity
+ * names to `${workflowType}.${activityName}` qualified names. This module owns
+ * the worker-side normalization:
+ *
+ *   - the outer map key is canonical — if `workflow.name` disagrees with the
+ *     key, throw immediately (same rule as the engine-side `Engine.create({
+ *     workflows })`).
+ *   - workflow names and activity keys are validated through the shared
+ *     `validateWorkflowOrActivityName` helper so a `.` in either name is
+ *     rejected at construction time, not in the middle of a task dispatch.
+ *   - the resulting table keys every activity under
+ *     `${workflowType}.${activityName}`, which is exactly the string the
+ *     server matches against the `RegisterMessage.activities` array.
+ *
+ * Bare function activities and `{ execute }` objects are both accepted, matching
+ * the engine-side `activities()` builder contract.
+ *
+ * @module worker/workflow-activity-binding
+ */
+import type { RemoteActivityContext } from './remote-activity-context.ts';
+/**
+ * An activity implementation accepted by the worker-side `workflows` map.
+ *
+ * Returns a `Promise<unknown>` to match `executeWithInterceptors`. Sync
+ * activities can return `Promise.resolve(...)` or be declared `async`.
+ *
+ * @example
+ * ```ts
+ * import type { RemoteWorkerActivityFunction } from '@lostgradient/weft';
+ *
+ * const formatGreeting: RemoteWorkerActivityFunction = async (input) =>
+ *   `hi ${String((input as { name: string }).name)}`;
+ * ```
+ */
+export type RemoteWorkerActivityFunction = (input: unknown, context?: RemoteActivityContext) => Promise<unknown>;
+/**
+ * Either a bare function or an `{ execute }` object — same shape the engine
+ * accepts when normalising a builder's `.activities({ ... })` map.
+ *
+ * @example
+ * ```ts
+ * import type { RemoteWorkerActivityImplementation } from '@lostgradient/weft';
+ *
+ * const bare: RemoteWorkerActivityImplementation = async () => 'a';
+ * const shaped: RemoteWorkerActivityImplementation = { execute: async () => 'b' };
+ * ```
+ */
+export type RemoteWorkerActivityImplementation = RemoteWorkerActivityFunction | {
+    execute: RemoteWorkerActivityFunction;
+};
+/**
+ * Minimal workflow shape the worker SDK consumes from a `workflows` map. Only
+ * `name` and `activities` are read; the rest of the engine-side definition is
+ * irrelevant to dispatch.
+ *
+ * @example
+ * ```ts
+ * import type { RemoteWorkerWorkflowDefinition } from '@lostgradient/weft';
+ *
+ * const welcome: RemoteWorkerWorkflowDefinition = {
+ *   name: 'welcome',
+ *   activities: { formatGreeting: async () => 'hi' },
+ * };
+ * ```
+ */
+export type RemoteWorkerWorkflowDefinition = {
+    name: string;
+    activities: Record<string, RemoteWorkerActivityImplementation>;
+};
+/**
+ * Build a flat `qualifiedName → executor` table from a `workflows` map.
+ *
+ * Throws if any workflow's `name` disagrees with the outer key, or if any
+ * workflow/activity name fails the wire-safe grammar.
+ *
+ * @example
+ * ```ts
+ * import { buildQualifiedActivityTable } from '@lostgradient/weft';
+ *
+ * const table = buildQualifiedActivityTable({
+ *   welcome: {
+ *     name: 'welcome',
+ *     activities: {
+ *       formatGreeting: async (input) =>
+ *         `hi ${String((input as { name: string }).name)}`,
+ *     },
+ *   },
+ * });
+ * // table['welcome.formatGreeting'] is the bound executor.
+ * ```
+ */
+export declare function buildQualifiedActivityTable(workflows: Record<string, RemoteWorkerWorkflowDefinition>): Record<string, RemoteWorkerActivityFunction>;

package/dist/worker/workflow-activity-binding.js

@@ -0,0 +1,22 @@
+import { validateWorkflowOrActivityName } from "../core/types/name-grammar.js";
+export function buildQualifiedActivityTable(workflows) {
+  const table = {};
+  for (const [key, workflow] of Object.entries(workflows)) {
+    if (workflow.name !== key)
+      throw Error(`Worker workflow map key "${key}" does not match workflow.name "${workflow.name}"`);
+    validateWorkflowOrActivityName(key, "workflow");
+    for (const [activityKey, implementation] of Object.entries(workflow.activities)) {
+      validateWorkflowOrActivityName(activityKey, "activity");
+      const qualifiedName = `${key}.${activityKey}`;
+      table[qualifiedName] = resolveActivityExecutor(implementation, qualifiedName);
+    }
+  }
+  return table;
+}
+function resolveActivityExecutor(implementation, qualifiedName) {
+  if (typeof implementation === "function")
+    return implementation;
+  if (implementation === null || typeof implementation !== "object" || typeof implementation.execute !== "function")
+    throw TypeError(`Activity "${qualifiedName}" must be a function or an object with a callable "execute" method`);
+  return implementation.execute;
+}

package/dist/workers/activity-runner.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Request payload sent to a Web Worker (or passed to {@link executeActivity})
+ * describing a single activity execution.
+ *
+ * Generated by the worker dispatcher and consumed by the activity runner
+ * inside the worker.  Callers do not normally construct this directly — it is
+ * built by the engine's task-dispatch path.
+ *
+ * @example
+ * ```ts
+ * import { executeActivity, type ActivityExecutionRequest } from '@lostgradient/weft';
+ *
+ * const request: ActivityExecutionRequest = {
+ *   operationId: crypto.randomUUID(),
+ *   activityName: 'sendEmail',
+ *   input: { to: 'user@example.com' },
+ *   attempt: 1,
+ * };
+ * const result = await executeActivity(request, async (input) => {
+ *   return `sent to ${(input as { to: string }).to}`;
+ * });
+ * console.log(result.status); // 'completed'
+ * ```
+ */
+export interface ActivityExecutionRequest {
+    operationId: string;
+    activityName: string;
+    input: unknown;
+    attempt: number;
+}
+/**
+ * Result payload returned by {@link executeActivity} and posted back by the
+ * Web Worker after activity execution.
+ *
+ * Check `status` first: `'completed'` means `value` holds the return value;
+ * `'failed'` means `error` holds a human-readable failure message.  The
+ * `operationId` mirrors the request so the dispatcher can match results.
+ *
+ * @example
+ * ```ts
+ * import { executeActivity, type ActivityExecutionResult } from '@lostgradient/weft';
+ *
+ * const result: ActivityExecutionResult = await executeActivity(
+ *   { operationId: 'op-1', activityName: 'add', input: [1, 2], attempt: 1 },
+ *   async (input) => (input as number[])[0]! + (input as number[])[1]!,
+ * );
+ *
+ * if (result.status === 'completed') {
+ *   console.log(result.value); // 3
+ * }
+ * ```
+ */
+export interface ActivityExecutionResult {
+    operationId: string;
+    status: 'completed' | 'failed';
+    value?: unknown;
+    error?: string;
+    /** Error constructor name used by retry classification and diagnostics. */
+    errorName?: string;
+}
+/**
+ * Executes an activity function with structured error handling and optional
+ * abort-signal support.
+ *
+ * Returns a resolved {@link ActivityExecutionResult} regardless of whether the
+ * function throws — failures are caught and returned as `{ status: 'failed' }`.
+ * If `signal` is already aborted before execution begins, the function is
+ * skipped and a failed result is returned immediately.
+ *
+ * @example
+ * ```ts
+ * import { executeActivity } from '@lostgradient/weft';
+ *
+ * const result = await executeActivity(
+ *   {
+ *     operationId: 'op-abc',
+ *     activityName: 'greet',
+ *     input: { name: 'World' },
+ *     attempt: 1,
+ *   },
+ *   async (input) => `Hello, ${(input as { name: string }).name}!`,
+ * );
+ * console.log(result.status); // 'completed'
+ * console.log(result.value);  // 'Hello, World!'
+ * ```
+ */
+export declare function executeActivity(request: ActivityExecutionRequest, activityFunction: (...arguments_: unknown[]) => unknown, signal?: AbortSignal): Promise<ActivityExecutionResult>;

package/dist/workers/activity-runner.js

@@ -0,0 +1,29 @@
+export async function executeActivity(request, activityFunction, signal) {
+  if (signal?.aborted)
+    return {
+      operationId: request.operationId,
+      status: "failed",
+      error: `Activity "${request.activityName}" aborted before execution`,
+      errorName: "AbortError"
+    };
+  try {
+    const result = await activityFunction(request.input);
+    return {
+      operationId: request.operationId,
+      status: "completed",
+      value: result
+    };
+  } catch (error) {
+    return {
+      operationId: request.operationId,
+      status: "failed",
+      error: `Activity "${request.activityName}" failed (attempt ${request.attempt}): ${formatError(error)}`,
+      ...error instanceof Error ? { errorName: error.name } : {}
+    };
+  }
+}
+function formatError(error) {
+  if (error instanceof Error)
+    return error.message;
+  return String(error);
+}

package/dist/workers/activity-worker-dispatcher.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Dispatches activity execution requests to a pool of Web Workers.
+ *
+ * Wraps {@link WorkerPool} with a request-response pattern: acquire a worker,
+ * post the activity request, wait for the result, and release the worker.
+ *
+ * @module workers/activity-worker-dispatcher
+ */
+import type { ActivityExecutionRequest, ActivityExecutionResult } from './activity-runner.ts';
+import type { WorkerPool } from './pool.ts';
+/**
+ * Options for {@link ActivityWorkerDispatcher}.
+ *
+ * Currently the only option is `timeoutMilliseconds`, which controls how long
+ * the dispatcher waits for a worker to respond before treating the task as
+ * failed and terminating the worker.
+ *
+ * @example
+ * ```ts
+ * import { ActivityWorkerDispatcher, WorkerPool, type ActivityWorkerDispatcherOptions } from '@lostgradient/weft';
+ *
+ * const options: ActivityWorkerDispatcherOptions = {
+ *   timeoutMilliseconds: 60_000,
+ * };
+ * const pool = new WorkerPool({ concurrency: 4, workerUrl: './worker.ts' });
+ * using dispatcher = new ActivityWorkerDispatcher(pool, options);
+ * void dispatcher;
+ * ```
+ */
+export type ActivityWorkerDispatcherOptions = {
+    /** Maximum time in milliseconds to wait for a worker to respond before
+     *  rejecting and terminating the worker. Default: 30 000 (30 seconds). */
+    timeoutMilliseconds?: number;
+};
+/**
+ * Dispatches activity execution requests to a pool of Web Workers and awaits
+ * their results, implementing a request-response pattern over the Worker
+ * message protocol.
+ *
+ * Acquires a worker from the {@link WorkerPool}, posts the
+ * {@link ActivityExecutionRequest}, waits for the matching
+ * {@link ActivityExecutionResult}, then releases the worker back to the pool.
+ * If no response arrives within the configured timeout, the task fails and the
+ * worker is terminated.
+ *
+ * @example
+ * ```ts
+ * import { ActivityWorkerDispatcher, WorkerPool } from '@lostgradient/weft';
+ *
+ * const pool = new WorkerPool({
+ *   concurrency: 4,
+ *   workerUrl: new URL('./my-worker.ts', import.meta.url),
+ * });
+ * using dispatcher = new ActivityWorkerDispatcher(pool, { timeoutMilliseconds: 30_000 });
+ *
+ * const result = await dispatcher.execute({
+ *   operationId: crypto.randomUUID(),
+ *   activityName: 'processImage',
+ *   input: { url: 'https://example.com/img.png' },
+ *   attempt: 1,
+ * });
+ * console.log(result.status); // 'completed' or 'failed'
+ * ```
+ */
+export declare class ActivityWorkerDispatcher implements Disposable, AsyncDisposable {
+    #private;
+    constructor(pool: WorkerPool, options?: ActivityWorkerDispatcherOptions);
+    /**
+     * Dispatch an activity execution request to a worker and wait for the result.
+     * Acquires a worker from the pool, sends the request, waits for a matching
+     * response, then releases the worker back to the pool.
+     *
+     * If the worker does not respond within the configured timeout, the promise
+     * resolves with a `failed` result and the worker is terminated.
+     */
+    execute(request: ActivityExecutionRequest): Promise<ActivityExecutionResult>;
+    /** Get the number of available workers. */
+    get availableCount(): number;
+    /** Get the total number of workers in the pool. */
+    get totalCount(): number;
+    /** Get the number of pending dispatch requests. */
+    get pendingCount(): number;
+    [Symbol.dispose](): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/workers/activity-worker-dispatcher.js

@@ -0,0 +1,68 @@
+const DEFAULT_WORKER_TIMEOUT_MILLISECONDS = 30000;
+
+export class ActivityWorkerDispatcher {
+  #pool;
+  #timeoutMilliseconds;
+  constructor(pool, options) {
+    this.#pool = pool;
+    this.#timeoutMilliseconds = options?.timeoutMilliseconds ?? DEFAULT_WORKER_TIMEOUT_MILLISECONDS;
+  }
+  async execute(request) {
+    const worker = await this.#pool.acquire();
+    let terminated = !1;
+    try {
+      return await new Promise((resolve) => {
+        let settled = !1;
+        const settle = (result) => {
+          if (settled)
+            return;
+          settled = !0;
+          cleanup();
+          resolve(result);
+        }, onMessage = (event) => {
+          if (event.data.operationId === request.operationId)
+            settle(event.data);
+        }, onError = (event) => {
+          settle({
+            operationId: request.operationId,
+            status: "failed",
+            error: `Activity worker crashed: ${event.message ?? "unknown error"}`
+          });
+        }, timer = setTimeout(() => {
+          settle({
+            operationId: request.operationId,
+            status: "failed",
+            error: `Activity "${request.activityName}" timed out after ${this.#timeoutMilliseconds}ms (operationId: ${request.operationId})`
+          });
+          terminated = !0;
+          worker.terminate();
+        }, this.#timeoutMilliseconds), cleanup = () => {
+          clearTimeout(timer);
+          worker.removeEventListener("message", onMessage);
+          worker.removeEventListener("error", onError);
+        };
+        worker.addEventListener("message", onMessage);
+        worker.addEventListener("error", onError);
+        worker.postMessage(request);
+      });
+    } finally {
+      if (!terminated)
+        this.#pool.release(worker);
+    }
+  }
+  get availableCount() {
+    return this.#pool.availableCount;
+  }
+  get totalCount() {
+    return this.#pool.totalCount;
+  }
+  get pendingCount() {
+    return this.#pool.pendingCount;
+  }
+  [Symbol.dispose]() {
+    this.#pool[Symbol.dispose]();
+  }
+  async[Symbol.asyncDispose]() {
+    await this.#pool[Symbol.asyncDispose]();
+  }
+}

package/dist/workers/activity-worker-entry.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Web Worker entry point for activity execution.
+ *
+ * Sets up `self.onmessage` to handle {@link ActivityExecutionRequest} and
+ * posts back {@link ActivityExecutionResult} via `self.postMessage`. Uses
+ * the existing `executeActivity` helper from `activity-runner.ts`.
+ *
+ * @module workers/activity-worker-entry
+ */
+/**
+ * Function type that resolves an activity name to its handler function, or
+ * returns `undefined` when the activity is not registered.
+ *
+ * Passed to `initializeActivityWorkerMessageLoop` to wire up the message
+ * handler inside a Web Worker.  Typically backed by a `Map` built at worker
+ * startup from the activity registration object.
+ *
+ * @example
+ * ```ts
+ * import { type ActivityHandlerLookup } from '@lostgradient/weft';
+ *
+ * const activities = new Map<string, (input: unknown) => unknown>([
+ *   ['double', (n: unknown) => (n as number) * 2],
+ * ]);
+ *
+ * const lookup: ActivityHandlerLookup = (name) => activities.get(name);
+ * console.log(lookup('double')); // [Function: double]
+ * console.log(lookup('missing')); // undefined
+ * ```
+ */
+export type ActivityHandlerLookup = (name: string) => ((input: unknown) => unknown) | undefined;
+/**
+ * Initialize the activity worker message loop. Call this from within a Web
+ * Worker to wire up the activity execution protocol.
+ *
+ * @param getActivity - Resolves an activity name to its function. Typically
+ *   backed by a registration map built at worker creation time.
+ *
+ * @example
+ * ```ts
+ * import { initializeActivityWorkerMessageLoop } from '@lostgradient/weft';
+ *
+ * const activities = new Map<string, (input: unknown) => unknown>();
+ * activities.set('greet', (input: unknown) => {
+ *   if (typeof input !== 'object' || input === null || !('name' in input)) {
+ *     throw new Error('Expected greeting input');
+ *   }
+ *   if (typeof input.name !== 'string') {
+ *     throw new Error('Expected greeting name');
+ *   }
+ *   return `Hello, ${input.name}!`;
+ * });
+ *
+ * // Call inside a Worker file to start listening for tasks:
+ * initializeActivityWorkerMessageLoop((name) => activities.get(name));
+ * ```
+ */
+export declare function initializeActivityWorkerMessageLoop(getActivity: ActivityHandlerLookup): void;
+/**
+ * Create a Blob URL that can be used to spawn an activity Web Worker with
+ * the given activity registrations.
+ *
+ * @param registrations - Map of activity names to handler functions. The
+ *   handlers must be serializable (no closures over local state).
+ * @returns A Blob URL string suitable for the `activityExecution.workerUrl`
+ *   option. Call {@link revokeActivityWorkerEntryUrl} when the URL is no
+ *   longer needed (e.g., during engine disposal) to free the registration.
+ * @throws {Error} If any handler function cannot be safely serialized.
+ *
+ * @example
+ * ```ts
+ * import { createActivityWorkerEntryUrl, revokeActivityWorkerEntryUrl } from '@lostgradient/weft';
+ *
+ * const registrations = new Map<string, (input: unknown) => unknown>();
+ * registrations.set('double', (n: unknown) => (n as number) * 2);
+ *
+ * const url = createActivityWorkerEntryUrl(registrations);
+ * // Pass url to Engine as activityExecution.workerUrl
+ * revokeActivityWorkerEntryUrl(url); // cleanup when done
+ * ```
+ */
+export declare function createActivityWorkerEntryUrl(registrations: Map<string, (input: unknown) => unknown>): string;
+/**
+ * Revoke a Blob URL previously created by {@link createActivityWorkerEntryUrl}.
+ * Call this once all workers that need the URL have been constructed (e.g.,
+ * during engine disposal) to free the URL registration and prevent leaks.
+ *
+ * @example
+ * ```ts
+ * import { createActivityWorkerEntryUrl, revokeActivityWorkerEntryUrl } from '@lostgradient/weft';
+ *
+ * const registrations = new Map<string, (input: unknown) => unknown>();
+ * registrations.set('greet', (input: unknown) => 'hello');
+ * const url = createActivityWorkerEntryUrl(registrations);
+ * // After all workers using this URL have been created:
+ * revokeActivityWorkerEntryUrl(url);
+ * ```
+ */
+export declare function revokeActivityWorkerEntryUrl(url: string): void;

package/dist/workers/activity-worker-entry.js

@@ -0,0 +1,59 @@
+import { executeActivity } from "./activity-runner.js";
+export function initializeActivityWorkerMessageLoop(getActivity) {
+  self.addEventListener("message", async (event) => {
+    const request = event.data, activityFunction = getActivity(request.activityName);
+    if (!activityFunction) {
+      const result = {
+        operationId: request.operationId,
+        status: "failed",
+        error: `Unknown activity in worker: "${request.activityName}"`
+      };
+      self.postMessage(result);
+      return;
+    }
+    const result = await executeActivity(request, activityFunction);
+    self.postMessage(result);
+  });
+}
+const CLOSURE_PATTERNS = [
+  {
+    pattern: /\bthis\b/,
+    description: "references `this` (class method or bound context)"
+  },
+  {
+    pattern: /\bimport\s*\(/,
+    description: "uses dynamic `import()`"
+  },
+  {
+    pattern: /\brequire\s*\(/,
+    description: "uses `require()`"
+  }
+];
+function stripStringsAndComments(source) {
+  return source.replace(/\/\/[^\n]*|\/\*[\s\S]*?\*\/|`(?:\\[\s\S]|[^`\\])*`|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'/g, "");
+}
+function validateHandlerSerializable(name, handler) {
+  const source = handler.toString();
+  if (source.includes("[native code]"))
+    throw Error(`Activity handler "${name}" is a native function and cannot be serialized for worker execution.`);
+  const codeOnly = stripStringsAndComments(source);
+  for (const { pattern, description } of CLOSURE_PATTERNS)
+    if (pattern.test(codeOnly))
+      throw Error(`Activity handler "${name}" ${description}. Handlers passed to createActivityWorkerEntryUrl must be self-contained functions without closures over outer scope, class instances, or module-level variables.`);
+}
+export function createActivityWorkerEntryUrl(registrations) {
+  for (const [name, handler] of registrations)
+    validateHandlerSerializable(name, handler);
+  const script = `
+const activities = new Map();
+${[...registrations.entries()].map(([name, handler]) => `  activities.set(${JSON.stringify(name)}, ${handler.toString()});`).join(`
+`)}
+
+import { initializeActivityWorkerMessageLoop } from '${import.meta.url}';
+initializeActivityWorkerMessageLoop((name) => activities.get(name));
+`, blob = new Blob([script], { type: "application/javascript" });
+  return URL.createObjectURL(blob);
+}
+export function revokeActivityWorkerEntryUrl(url) {
+  URL.revokeObjectURL(url);
+}

package/dist/workers/pool.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Construction options for {@link WorkerPool}.
+ *
+ * `concurrency` sets the maximum number of Worker instances created; once this
+ * limit is reached, `acquire()` calls queue until a worker is released.
+ * `workerUrl` is the script URL passed to `new Worker()`.  Set `smol: true` on
+ * Bun to request a reduced-heap worker.
+ *
+ * @example
+ * ```ts
+ * import { WorkerPool, type WorkerPoolOptions } from '@lostgradient/weft';
+ *
+ * const options: WorkerPoolOptions = {
+ *   concurrency: 4,
+ *   workerUrl: new URL('./activity-worker.ts', import.meta.url),
+ *   smol: false,
+ * };
+ * using pool = new WorkerPool(options);
+ * void pool;
+ * ```
+ */
+export interface WorkerPoolOptions {
+    concurrency: number;
+    workerUrl: string | URL;
+    smol?: boolean;
+}
+/**
+ * Bounded pool of Web Workers with acquire/release lifecycle management.
+ *
+ * Workers are created lazily up to `concurrency` and reused across tasks.
+ * `acquire()` returns a `Worker` immediately if one is available, creates a new
+ * one if under the limit, or queues the request until a worker is released.
+ * Use `[Symbol.asyncDispose]()` for a graceful shutdown that waits for
+ * in-flight workers to finish, or `[Symbol.dispose]()` for immediate
+ * termination.
+ *
+ * @example
+ * ```ts
+ * import { WorkerPool } from '@lostgradient/weft';
+ *
+ * await using pool = new WorkerPool({
+ *   concurrency: 2,
+ *   workerUrl: new URL('./worker.ts', import.meta.url),
+ * });
+ *
+ * const worker = await pool.acquire();
+ * worker.postMessage({ task: 'hello' });
+ * // ... wait for message event ...
+ * pool.release(worker);
+ * ```
+ */
+export declare class WorkerPool implements Disposable, AsyncDisposable {
+    #private;
+    constructor(options: WorkerPoolOptions);
+    /** Acquire a worker from the pool. Blocks if at capacity. */
+    acquire(): Promise<Worker>;
+    /**
+     * Acquire a specific worker once it is released back to the pool.
+     *
+     * This is intentionally narrower than `acquire()`: it preserves worker-local
+     * generator state for parked workflow execution without reserving unrelated
+     * idle workers while the target worker is still busy.
+     */
+    acquireSpecificWorker(worker: Worker): Promise<Worker>;
+    /**
+     * Remove a failed worker from the pool without returning it to the available
+     * set. Pending requests for that exact worker fail; generic waiters may get
+     * a replacement worker if the pool still has capacity.
+     */
+    discard(worker: Worker): void;
+    /** Release a worker back to the pool. */
+    release(worker: Worker): void;
+    /** Get the number of available workers. */
+    get availableCount(): number;
+    /** Get the total number of workers. */
+    get totalCount(): number;
+    /** Get the number of pending acquire requests. */
+    get pendingCount(): number;
+    /** Immediate termination. */
+    [Symbol.dispose](): void;
+    /** Graceful: wait for in-flight, then terminate. */
+    [Symbol.asyncDispose](): Promise<void>;
+}