@lostgradient/weft 0.2.0

package/dist/worker/registry/types.d.ts

@@ -0,0 +1,123 @@
+import type { RemoteWorkerCapabilities } from '../protocol.ts';
+/** Lifecycle health state of a connected worker. */
+export type WorkerHealth = 'active' | 'draining' | 'drained';
+/**
+ * Full internal state record for a connected worker, held by the registry.
+ * `drainReason` and `drainStartedAt` are present only when a worker-level
+ * drain marker has been set.
+ */
+export interface WorkerInfo {
+    id: string;
+    queue: string;
+    activities: string[];
+    concurrency: number;
+    inFlight: number;
+    connectedAt: number;
+    lastHeartbeat: number;
+    startedAt: number;
+    capabilities: RemoteWorkerCapabilities;
+    deploymentName?: string;
+    buildId?: string;
+    runtimeVersion?: string;
+    gitSha?: string;
+    drainReason?: string;
+    drainStartedAt?: number;
+}
+/** Shape accepted by {@link WorkerRegistry.register}. */
+export type WorkerRegistrationInfo = {
+    id: string;
+    queue: string;
+    activities: string[];
+    concurrency: number;
+    deploymentName?: string;
+    buildId?: string;
+    runtimeVersion?: string;
+    gitSha?: string;
+    startedAt?: number;
+    capabilities?: RemoteWorkerCapabilities;
+};
+/**
+ * Per-worker projection reported by {@link WorkerRegistry.getWorkerSummaries}.
+ * Derived view used by the public `weft.workers.list` operation and joined
+ * into `weft.task.queues.list` to compute per-queue in-flight totals. The
+ * `now` parameter passed to `getWorkerSummaries` is the same `now` the
+ * operation uses for queue-age math, so a single response is internally
+ * consistent across both data sources.
+ */
+export type WorkerSummary = {
+    id: string;
+    queue: string;
+    activities: string[];
+    concurrency: number;
+    inFlight: number;
+    availableCapacity: number;
+    connectedAt: number;
+    lastHeartbeatAt: number;
+    heartbeatAgeMs: number;
+    startedAt: number;
+    capabilities: RemoteWorkerCapabilities;
+    health: WorkerHealth;
+    deploymentName?: string | undefined;
+    buildId?: string | undefined;
+    runtimeVersion?: string | undefined;
+    gitSha?: string | undefined;
+};
+export type WorkerDrainMutationResult = {
+    target: 'worker';
+    workerId: string;
+    affectedWorkers: number;
+    inFlight: number;
+    health: WorkerHealth;
+} | {
+    target: 'deployment';
+    deploymentName: string;
+    affectedWorkers: number;
+    inFlight: number;
+    health: WorkerHealth;
+};
+export type WorkerDrainOptions = {
+    reason?: string;
+    updatedAt?: number;
+};
+/**
+ * Strategy used by {@link WorkerRegistry.findWorker} to pick among eligible workers.
+ *
+ * - `'least-loaded'` (default) picks the worker with the lowest `inFlight` count.
+ *   Best general-purpose policy when tasks are roughly uniform.
+ * - `'round-robin'` rotates through workers in registration order, giving each
+ *   equal opportunity regardless of load. Useful when tasks are uniform and you
+ *   want deterministic distribution for debugging or fairness across workers.
+ * - `'fair-share'` picks the worker whose in-flight count for the current
+ *   `fairShareKey` (e.g. customer id) is lowest, preventing any single key from
+ *   monopolizing capacity when tasks are heterogeneous.
+ */
+export type RoutingPolicy = 'least-loaded' | 'round-robin' | 'fair-share';
+export interface RoutingOptions {
+    /** Preferred worker ID for cache locality (wins when it still has capacity). */
+    sticky?: string;
+    queue?: string;
+    /**
+     * Partition key for `'fair-share'` routing. Typically a customer id.
+     * Ignored by other policies. When omitted under `'fair-share'` the policy
+     * degrades gracefully to `'least-loaded'`.
+     */
+    fairShareKey?: string;
+    /**
+     * Worker IDs to exclude from eligibility — used by `serve()` to skip
+     * workers currently in the reconnect grace window so dispatches do not
+     * land on a dead socket while peers are available.
+     */
+    excludeWorkerIds?: ReadonlySet<string>;
+}
+export interface InFlightTask {
+    operationId: string;
+    workerId: string;
+    deadline: number;
+    visibilityTimeout: number;
+    /** Optional fair-share partition key the task was assigned under. */
+    fairShareKey?: string;
+}
+export interface WorkerRegistryOptions {
+    /** Routing policy used by {@link WorkerRegistry.findWorker}. Default: `'least-loaded'`. */
+    policy?: RoutingPolicy;
+}

package/dist/worker/registry.d.ts

@@ -0,0 +1,94 @@
+import { type WorkerDeploymentSummary } from './registry/summary.ts';
+import type { InFlightTask, RoutingOptions, RoutingPolicy, WorkerDrainMutationResult, WorkerDrainOptions, WorkerInfo, WorkerRegistrationInfo, WorkerRegistryOptions, WorkerSummary } from './registry/types.ts';
+export type { WorkerDeploymentSummary } from './registry/summary.ts';
+export type { InFlightTask, RoutingOptions, RoutingPolicy, WorkerDrainMutationResult, WorkerDrainOptions, WorkerHealth, WorkerInfo, WorkerRegistrationInfo, WorkerRegistryOptions, WorkerSummary, } from './registry/types.ts';
+/**
+ * Server-side registry of connected remote workers with pluggable routing
+ * policies. Tracks which workers are connected, which activities they support,
+ * and how many tasks they have in flight. `findWorker` selects the best worker
+ * for a given activity per the configured {@link RoutingPolicy} (default
+ * `'least-loaded'`). Used internally by `serve()`; most applications access it
+ * through {@link WeftServer.registry}.
+ *
+ * @example
+ * ```ts
+ * import { WorkerRegistry } from '@lostgradient/weft';
+ * const registry = new WorkerRegistry({ policy: 'least-loaded' });
+ * registry.register({ id: 'worker-1', queue: 'default', activities: ['sendEmail'], concurrency: 10 });
+ * const best = registry.findWorker('sendEmail', { queue: 'default' });
+ * ```
+ */
+export declare class WorkerRegistry {
+    #private;
+    constructor(options?: WorkerRegistryOptions);
+    /** The routing policy this registry was configured with. */
+    get policy(): RoutingPolicy;
+    /** Register a worker. */
+    register(info: WorkerRegistrationInfo): void;
+    /** Unregister a worker. Purges fair-share counters and in-flight task entries for this worker. */
+    unregister(workerId: string): WorkerInfo | undefined;
+    /** Record a heartbeat from a worker. */
+    heartbeat(workerId: string): void;
+    /** Increment in-flight count for a worker. */
+    taskAssigned(workerId: string): void;
+    /** Decrement in-flight count. */
+    taskCompleted(workerId: string): void;
+    /**
+     * Find the best worker for a task using the configured {@link RoutingPolicy}.
+     *
+     * Common preconditions for every policy:
+     * 1. If `options.queue` is set, only workers on that queue are considered.
+     * 2. Only workers that advertise `activityName` in their `activities` list are
+     *    considered.
+     * 3. Workers at `inFlight >= concurrency` are excluded.
+     * 4. A `sticky` worker that also satisfies the above wins regardless of policy.
+     */
+    findWorker(activityName: string, options?: RoutingOptions): WorkerInfo | undefined;
+    /** Track a task assignment with a visibility timeout deadline. */
+    assignTask(workerId: string, operationId: string, visibilityTimeout: number, fairShareKey?: string): void;
+    /** Return tasks whose deadline has passed and remove them from tracking. */
+    checkExpiredTasks(now: number): InFlightTask[];
+    /**
+     * Reset the deadline for an in-flight task to `now + extension`. Returns the
+     * new deadline, or `undefined` if the task was not found.
+     */
+    extendVisibility(operationId: string, extension: number): number | undefined;
+    /** Return all in-flight tasks assigned to a given worker. */
+    getWorkerTasks(workerId: string): InFlightTask[];
+    /** True when `operationId` is in flight on `workerId` — used at the trust boundary to reject stale completions after takeover. */
+    isAssignedToWorker(operationId: string, workerId: string): boolean;
+    /** Check whether an operation is currently assigned to a worker. */
+    isAssigned(operationId: string): boolean;
+    /** Look up an in-flight task by operationId in O(1). */
+    getTask(operationId: string): InFlightTask | undefined;
+    /** Complete an in-flight task: remove tracking and decrement the worker's counter. */
+    completeTask(operationId: string): InFlightTask | undefined;
+    /** Look up a worker by ID. */
+    getWorker(workerId: string): WorkerInfo | undefined;
+    /** Get all registered workers. */
+    getAll(): WorkerInfo[];
+    /** Mark one connected worker as draining so routing excludes it from new tasks. */
+    markWorkerDraining(workerId: string, options?: WorkerDrainOptions): WorkerDrainMutationResult | undefined;
+    /** Clear an explicit worker drain marker. Deployment-level drains can still apply. */
+    clearWorkerDrain(workerId: string): WorkerDrainMutationResult | undefined;
+    /** Mark every current and future worker with this deployment name as draining. */
+    markDeploymentDraining(deploymentName: string, options?: WorkerDrainOptions): WorkerDrainMutationResult;
+    /** Clear the deployment-level drain marker for matching current and future workers. */
+    clearDeploymentDrain(deploymentName: string): WorkerDrainMutationResult;
+    /**
+     * Stable, sorted-by-id snapshot of every connected worker for the public
+     * `weft.workers.list` operation. The caller passes a per-request `now`
+     * so heartbeat ages across the response use one consistent clock; the
+     * same `now` should be reused by the task-queue operation when both run
+     * in the same request to keep the join honest.
+     */
+    getWorkerSummaries(now: number): WorkerSummary[];
+    /**
+     * Deployment-group snapshot for operator views. Workers without deployment
+     * metadata are grouped together under `null` identity fields so anonymous
+     * fleets remain visible without inventing placeholder names.
+     */
+    getDeploymentSummaries(_now: number): WorkerDeploymentSummary[];
+    /** Get worker count. */
+    get size(): number;
+}

package/dist/worker/registry.js

@@ -0,0 +1,305 @@
+import { compareScores, scoreWorker } from "./registry/fair-share.js";
+import { matchesWorkerCapabilities, pickLeastLoaded } from "./registry/routing.js";
+import {
+  deploymentHealth,
+  projectDeploymentSummaries,
+  projectWorkerSummaries
+} from "./registry/summary.js";
+
+export class WorkerRegistry {
+  #workers;
+  #inFlightTasks;
+  #deploymentDrainStates;
+  #policy;
+  #roundRobinCursor;
+  #fairShareCounts;
+  constructor(options) {
+    this.#workers = new Map;
+    this.#inFlightTasks = new Map;
+    this.#deploymentDrainStates = new Map;
+    this.#policy = options?.policy ?? "least-loaded";
+    this.#roundRobinCursor = new Map;
+    this.#fairShareCounts = new Map;
+  }
+  get policy() {
+    return this.#policy;
+  }
+  register(info) {
+    const now = Date.now();
+    let inFlight = 0;
+    for (const task of this.#inFlightTasks.values())
+      if (task.workerId === info.id)
+        inFlight += 1;
+    this.#workers.set(info.id, {
+      id: info.id,
+      queue: info.queue,
+      activities: [...info.activities],
+      concurrency: info.concurrency,
+      ...info.deploymentName !== void 0 ? { deploymentName: info.deploymentName } : {},
+      ...info.buildId !== void 0 ? { buildId: info.buildId } : {},
+      ...info.runtimeVersion !== void 0 ? { runtimeVersion: info.runtimeVersion } : {},
+      ...info.gitSha !== void 0 ? { gitSha: info.gitSha } : {},
+      startedAt: info.startedAt ?? now,
+      capabilities: { ...info.capabilities },
+      inFlight,
+      connectedAt: now,
+      lastHeartbeat: now
+    });
+  }
+  unregister(workerId) {
+    const info = this.#workers.get(workerId);
+    if (info === void 0)
+      return;
+    this.#workers.delete(workerId);
+    this.#fairShareCounts.delete(workerId);
+    for (const [operationId, task] of this.#inFlightTasks)
+      if (task.workerId === workerId)
+        this.#inFlightTasks.delete(operationId);
+    return info;
+  }
+  heartbeat(workerId) {
+    const info = this.#workers.get(workerId);
+    if (info !== void 0)
+      info.lastHeartbeat = Date.now();
+  }
+  taskAssigned(workerId) {
+    const info = this.#workers.get(workerId);
+    if (info !== void 0)
+      info.inFlight += 1;
+  }
+  taskCompleted(workerId) {
+    const info = this.#workers.get(workerId);
+    if (info !== void 0)
+      info.inFlight = Math.max(0, info.inFlight - 1);
+  }
+  findWorker(activityName, options = {}) {
+    const { queue, sticky: stickyId, fairShareKey, excludeWorkerIds } = options, eligible = [];
+    let stickyCandidate;
+    for (const worker of this.#workers.values()) {
+      if (!this.#workerIsEligible(worker, activityName, queue, excludeWorkerIds))
+        continue;
+      if (stickyId !== void 0 && worker.id === stickyId)
+        stickyCandidate = worker;
+      eligible.push(worker);
+    }
+    if (stickyCandidate !== void 0)
+      return stickyCandidate;
+    if (eligible.length === 0)
+      return;
+    return this.#selectByPolicy(eligible, queue, activityName, fairShareKey);
+  }
+  #workerIsEligible(worker, activityName, queue, excludeWorkerIds) {
+    if (excludeWorkerIds?.has(worker.id))
+      return !1;
+    if (!matchesWorkerCapabilities(worker, activityName, queue))
+      return !1;
+    if (this.#isWorkerDraining(worker))
+      return !1;
+    return !0;
+  }
+  #selectByPolicy(eligible, queue, activityName, fairShareKey) {
+    if (this.#policy === "round-robin")
+      return this.#pickRoundRobin(eligible, queue, activityName);
+    if (this.#policy === "fair-share" && fairShareKey !== void 0)
+      return this.#pickFairShare(eligible, fairShareKey);
+    return pickLeastLoaded(eligible);
+  }
+  #pickRoundRobin(eligible, queue, activityName) {
+    const key = `${queue ?? "__default__"}::${activityName}`, cursor = this.#roundRobinCursor.get(key) ?? 0, pick = eligible[cursor % eligible.length];
+    this.#roundRobinCursor.set(key, cursor + 1);
+    return pick;
+  }
+  #pickFairShare(eligible, fairShareKey) {
+    const winner = eligible.map((worker) => scoreWorker({
+      id: worker.id,
+      inFlight: worker.inFlight,
+      keyLoad: this.#fairShareCounts.get(worker.id)?.get(fairShareKey) ?? 0
+    })).reduce((best, candidate) => compareScores(candidate, best) < 0 ? candidate : best);
+    return this.#workers.get(winner.id);
+  }
+  assignTask(workerId, operationId, visibilityTimeout, fairShareKey) {
+    const deadline = Date.now() + visibilityTimeout, task = {
+      operationId,
+      workerId,
+      deadline,
+      visibilityTimeout
+    };
+    if (fairShareKey !== void 0) {
+      task.fairShareKey = fairShareKey;
+      let workerCounts = this.#fairShareCounts.get(workerId);
+      if (workerCounts === void 0) {
+        workerCounts = new Map;
+        this.#fairShareCounts.set(workerId, workerCounts);
+      }
+      workerCounts.set(fairShareKey, (workerCounts.get(fairShareKey) ?? 0) + 1);
+    }
+    this.#inFlightTasks.set(operationId, task);
+    this.taskAssigned(workerId);
+  }
+  checkExpiredTasks(now) {
+    const expired = [];
+    for (const task of this.#inFlightTasks.values())
+      if (task.deadline <= now)
+        expired.push(task);
+    for (const task of expired) {
+      this.#inFlightTasks.delete(task.operationId);
+      this.#releaseFairShare(task);
+    }
+    return expired;
+  }
+  extendVisibility(operationId, extension) {
+    const task = this.#inFlightTasks.get(operationId);
+    if (task === void 0)
+      return;
+    task.deadline = Date.now() + extension;
+    return task.deadline;
+  }
+  getWorkerTasks(workerId) {
+    const tasks = [];
+    for (const task of this.#inFlightTasks.values())
+      if (task.workerId === workerId)
+        tasks.push(task);
+    return tasks;
+  }
+  isAssignedToWorker(operationId, workerId) {
+    return this.#inFlightTasks.get(operationId)?.workerId === workerId;
+  }
+  isAssigned(operationId) {
+    return this.#inFlightTasks.has(operationId);
+  }
+  getTask(operationId) {
+    return this.#inFlightTasks.get(operationId);
+  }
+  completeTask(operationId) {
+    const task = this.#inFlightTasks.get(operationId);
+    if (task === void 0)
+      return;
+    this.#inFlightTasks.delete(operationId);
+    this.taskCompleted(task.workerId);
+    this.#releaseFairShare(task);
+    return task;
+  }
+  getWorker(workerId) {
+    return this.#workers.get(workerId);
+  }
+  getAll() {
+    return [...this.#workers.values()];
+  }
+  markWorkerDraining(workerId, options) {
+    const worker = this.#workers.get(workerId);
+    if (worker === void 0)
+      return;
+    const record = createDrainRecord(options);
+    worker.drainStartedAt = record.startedAt;
+    if (record.reason !== void 0)
+      worker.drainReason = record.reason;
+    else
+      delete worker.drainReason;
+    return {
+      target: "worker",
+      workerId,
+      affectedWorkers: 1,
+      inFlight: worker.inFlight,
+      health: this.#workerHealth(worker)
+    };
+  }
+  clearWorkerDrain(workerId) {
+    const worker = this.#workers.get(workerId);
+    if (worker === void 0)
+      return;
+    delete worker.drainReason;
+    delete worker.drainStartedAt;
+    return {
+      target: "worker",
+      workerId,
+      affectedWorkers: 1,
+      inFlight: worker.inFlight,
+      health: this.#workerHealth(worker)
+    };
+  }
+  markDeploymentDraining(deploymentName, options) {
+    const record = createDrainRecord(options);
+    this.#deploymentDrainStates.set(deploymentName, record);
+    return this.#deploymentDrainResult(deploymentName);
+  }
+  clearDeploymentDrain(deploymentName) {
+    this.#deploymentDrainStates.delete(deploymentName);
+    return this.#deploymentDrainResult(deploymentName);
+  }
+  getWorkerSummaries(now) {
+    return projectWorkerSummaries(this.#workerSnapshots(), now);
+  }
+  #workerSnapshots() {
+    return [...this.#workers.values()].map((worker) => ({
+      id: worker.id,
+      queue: worker.queue,
+      activities: worker.activities,
+      concurrency: worker.concurrency,
+      inFlight: worker.inFlight,
+      connectedAt: worker.connectedAt,
+      lastHeartbeat: worker.lastHeartbeat,
+      startedAt: worker.startedAt,
+      capabilities: worker.capabilities,
+      health: this.#workerHealth(worker),
+      deploymentName: worker.deploymentName,
+      buildId: worker.buildId,
+      runtimeVersion: worker.runtimeVersion,
+      gitSha: worker.gitSha
+    }));
+  }
+  getDeploymentSummaries(_now) {
+    const snapshots = this.#workerSnapshots();
+    return projectDeploymentSummaries(snapshots, (name) => this.#deploymentDrainStates.has(name));
+  }
+  get size() {
+    return this.#workers.size;
+  }
+  #deploymentDrainResult(deploymentName) {
+    const workers = [...this.#workers.values()].filter((worker) => worker.deploymentName === deploymentName), inFlight = workers.reduce((total, worker) => total + worker.inFlight, 0), healthValues = workers.map((worker) => this.#workerHealth(worker));
+    return {
+      target: "deployment",
+      deploymentName,
+      affectedWorkers: workers.length,
+      inFlight,
+      health: deploymentHealth(healthValues, this.#deploymentDrainStates.has(deploymentName))
+    };
+  }
+  #isWorkerDraining(worker) {
+    return this.#drainRecordForWorker(worker) !== void 0;
+  }
+  #workerHealth(worker) {
+    if (!this.#isWorkerDraining(worker))
+      return "active";
+    return worker.inFlight > 0 ? "draining" : "drained";
+  }
+  #drainRecordForWorker(worker) {
+    if (worker.drainStartedAt !== void 0)
+      return {
+        startedAt: worker.drainStartedAt,
+        ...worker.drainReason !== void 0 ? { reason: worker.drainReason } : {}
+      };
+    if (worker.deploymentName === void 0)
+      return;
+    return this.#deploymentDrainStates.get(worker.deploymentName);
+  }
+  #releaseFairShare(task) {
+    if (task.fairShareKey === void 0)
+      return;
+    const workerCounts = this.#fairShareCounts.get(task.workerId);
+    if (workerCounts === void 0)
+      return;
+    const current = workerCounts.get(task.fairShareKey) ?? 0, next = Math.max(0, current - 1);
+    if (next === 0) {
+      workerCounts.delete(task.fairShareKey);
+      if (workerCounts.size === 0)
+        this.#fairShareCounts.delete(task.workerId);
+    } else
+      workerCounts.set(task.fairShareKey, next);
+  }
+}
+function createDrainRecord(options) {
+  return {
+    startedAt: options?.updatedAt ?? Date.now(),
+    ...options?.reason !== void 0 ? { reason: options.reason } : {}
+  };
+}

package/dist/worker/remote-activity-context.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Context object passed to activity implementations executed by a
+ * {@link RemoteWorker}. Carries the per-task `AbortSignal` so a long-running
+ * activity can observe cancellation requested from the server.
+ *
+ * Lives in its own leaf module so worker-side helpers (e.g. the qualified-name
+ * activity binder) can depend on the type without pulling in the full
+ * `RemoteWorker` class graph.
+ *
+ * @module worker/remote-activity-context
+ */
+/** Context passed to activity functions executed by a remote worker. */
+export type RemoteActivityContext = {
+    signal: AbortSignal;
+};

package/dist/worker/task-result-outbox.d.ts

@@ -0,0 +1,40 @@
+import type { TaskResultMessage } from './protocol.ts';
+/**
+ * Hard ceiling on unsent `taskResult` frames buffered for resend across a
+ * reconnect. Reaching it triggers intake backpressure on the worker so the
+ * buffer cannot grow without bound; completed results are never dropped.
+ */
+export declare const MAX_BUFFERED_TASK_RESULTS = 1000;
+/**
+ * Whether the outbox is at or above its ceiling. Extracted as a pure helper so
+ * the backpressure threshold is unit-testable without fabricating a full buffer.
+ */
+export declare function isOutboxFull(size: number, max: number): boolean;
+/**
+ * Buffers terminal task results that could not be sent immediately so the
+ * worker can re-send them after a reconnect rather than silently dropping them
+ * (a dropped result would be redelivered by the server and re-execute the
+ * activity). Keyed by `operationId`: a `Map` gives dedup-by-operation and
+ * deterministic insertion-order flush in one structure.
+ */
+export declare class TaskResultOutbox {
+    #private;
+    constructor(max?: number);
+    /** Current number of buffered results. */
+    get size(): number;
+    /** Whether the buffer is at or above its ceiling. */
+    get full(): boolean;
+    /**
+     * Warn at most once that the buffer is full. Returns `true` the first time it
+     * is called after the cap is reached, so the caller can emit a single log.
+     */
+    shouldWarnFull(): boolean;
+    /** Buffer (or replace by `operationId`) a result for later resend. */
+    buffer(message: TaskResultMessage): void;
+    /** Drop a buffered result once it has been confirmed sent. */
+    delete(operationId: string): void;
+    /** Snapshot of buffered results in insertion (flush) order. */
+    drainOrder(): TaskResultMessage[];
+    /** Discard all buffered results (terminal disposal). */
+    clear(): void;
+}

package/dist/worker/task-result-outbox.js

@@ -0,0 +1,42 @@
+export const MAX_BUFFERED_TASK_RESULTS = 1000;
+export function isOutboxFull(size, max) {
+  return size >= max;
+}
+
+export class TaskResultOutbox {
+  #entries = new Map;
+  #max;
+  #warnedFull = !1;
+  constructor(max = MAX_BUFFERED_TASK_RESULTS) {
+    if (!Number.isInteger(max) || max < 0)
+      throw RangeError(`maxBufferedResults must be a non-negative integer, received ${String(max)}`);
+    this.#max = max;
+  }
+  get size() {
+    return this.#entries.size;
+  }
+  get full() {
+    return isOutboxFull(this.#entries.size, this.#max);
+  }
+  shouldWarnFull() {
+    if (this.#warnedFull)
+      return !1;
+    this.#warnedFull = !0;
+    return !0;
+  }
+  buffer(message) {
+    this.#entries.set(message.operationId, message);
+  }
+  delete(operationId) {
+    this.#entries.delete(operationId);
+    if (!this.full)
+      this.#warnedFull = !1;
+  }
+  drainOrder() {
+    return [...this.#entries.values()];
+  }
+  clear() {
+    this.#entries.clear();
+    this.#warnedFull = !1;
+  }
+}

package/dist/worker/worker-protocol-incompatible-error.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Error raised when a worker advertises an incompatible RemoteWorker protocol
+ * version during handshake.
+ *
+ * Phase 4 of the workflow-builder refactor bumped the wire protocol from v1 to
+ * v2: each entry in `RegisterMessage.activities` is now a qualified
+ * `${workflowType}.${activityName}` name rather than a bare activity name. A
+ * worker built against the old SDK has no way to produce the qualified names
+ * the server expects, so the server rejects the handshake before any task is
+ * dispatched — the failure points at the protocol mismatch, not at a missing
+ * activity later in replay.
+ *
+ * @module worker/worker-protocol-incompatible-error
+ */
+import { WeftError } from '../core/weft-error.ts';
+/**
+ * Build the canonical user-facing message for a protocol-version mismatch.
+ *
+ * Extracted so the server-side handshake path and the error class itself agree
+ * on the exact wording — tests pin on this string.
+ *
+ * @example
+ * ```ts
+ * import { workerProtocolIncompatibleMessage } from '@lostgradient/weft';
+ *
+ * const message = workerProtocolIncompatibleMessage({ expected: 2, received: 1 });
+ * ```
+ */
+export declare function workerProtocolIncompatibleMessage(versions: {
+    expected: number;
+    received: number | undefined;
+}): string;
+/**
+ * Thrown / surfaced when a connecting worker advertises a `protocolVersion`
+ * that this server cannot accept. Carries the expected and received versions
+ * so operators can distinguish "no worker registered" from "old worker SDK".
+ *
+ * @example
+ * ```ts
+ * import { WorkerProtocolIncompatibleError } from '@lostgradient/weft';
+ *
+ * throw new WorkerProtocolIncompatibleError({ expected: 2, received: 1 });
+ * ```
+ */
+export declare class WorkerProtocolIncompatibleError extends WeftError<'WorkerProtocolIncompatibleError'> {
+    readonly expectedProtocolVersion: number;
+    readonly receivedProtocolVersion: number | undefined;
+    constructor(versions: {
+        expected: number;
+        received: number | undefined;
+    });
+}