@lostgradient/weft 0.17.0 → 0.19.0

package/dist/server/runtime/task-reconciliation.js

@@ -1,14 +1,15 @@
-import { decode } from "../../core/codec.js";
 import { ActivityFailedEvent } from "../../core/events.js";
-import { calculateBackoff } from "../../core/scheduler.js";
-import { KEYS } from "../../storage/interface.js";
 import { restoreExtendedDeadlineIfStillActive } from "../runtime-helpers.js";
 import {
-  isTaskDeadLettered,
-  transitionInflightToQueued,
-  transitionInflightToResolved
-} from "../task-state.js";
-import { dispatchTaskImpl, scheduleDelayedDispatch } from "./task-dispatch.js";
+  canDeleteRetainedTerminalTask,
+  requeueExpiredAttempt
+} from "../task-ledger-transitions.js";
+import {
+  decodeRemoteTaskRecord,
+  taskLedgerKey
+} from "../task-ledger.js";
+import { scheduleDelayedDispatch } from "./task-dispatch.js";
+import { commitTaskLedgerDelete, commitTaskLedgerTransition } from "./task-ledger-runtime.js";
 import {
   isTaskHeartbeatStaleForMetrics,
   recordTaskRequeueMetric,
@@ -16,7 +17,6 @@ import {
   recordTaskStaleHeartbeatMetric,
   recordWorkerCapacitySaturationMetric
 } from "./task-metrics.js";
-import { isInflightRecord } from "./websocket-worker.js";
 const manualTaskReconciliationRegistrations = new WeakMap;
 export function useManualTaskReconciliationForTesting(options) {
   const registration = {};
@@ -42,69 +42,65 @@ export function consumeManualTaskReconciliationForTesting(options, context, clea
   return !0;
 }
 export async function reassignOrExpireTask(context, options, operationId, record, reason = "visibility-timeout") {
-  const nextAttempt = (record.attempt ?? 1) + 1, policy = record.retryPolicy, nextRetryCount = Math.max(record.retryCount ?? 0, nextAttempt - 1);
-  if (hasExceededMaxAttempts(policy, nextAttempt)) {
-    await expireTaskAfterMaxAttempts(context, options, operationId, record, policy);
+  const skipDeadlineCheck = reason === "worker-disconnect", result = await commitTaskLedgerTransition(options.engine.storage, operationId, (current, now) => requeueExpiredAttempt(current, { attemptToken: record.attemptToken, requeueReason: reason, skipDeadlineCheck }, now), 1);
+  if (!result.ok) {
+    console.error(`[weft] Failed to requeue/expire task "${operationId}": ${result.reason}`);
+    return;
+  }
+  recordWorkerCapacitySaturationMetric(context.metricsCollector, context.registry);
+  if (result.record.state === "terminal") {
+    options.engine.dispatchEvent(new ActivityFailedEvent(operationId, record.workflowId ?? "", record.activityName, Error(result.record.error), record.attempt));
     return;
   }
-  const queuedRecord = createRequeuedRecord(record, nextAttempt, nextRetryCount, reason);
-  await transitionInflightToQueued(options.engine.storage, operationId, queuedRecord);
   recordTaskRetryMetric(context.metricsCollector);
   recordTaskRequeueMetric(context.metricsCollector);
-  recordWorkerCapacitySaturationMetric(context.metricsCollector, context.registry);
-  scheduleTaskRedispatch(context, options, createRequeuedTaskDispatch(record, nextAttempt), policy);
-}
-function hasExceededMaxAttempts(policy, nextAttempt) {
-  return policy !== void 0 && nextAttempt > policy.maxAttempts;
-}
-async function expireTaskAfterMaxAttempts(context, options, operationId, record, policy) {
-  await transitionInflightToResolved(options.engine.storage, operationId, "failed", {
-    record,
-    resolutionReason: "max-attempts-exceeded"
-  });
-  recordWorkerCapacitySaturationMetric(context.metricsCollector, context.registry);
-  options.engine.dispatchEvent(new ActivityFailedEvent(record.operationId, record.workflowId ?? "", record.activityName, Error(`Activity "${record.activityName}" exhausted all ${policy.maxAttempts} retry attempts`), record.attempt ?? 1));
+  const delay = Math.max(0, result.record.availableAt - Date.now());
+  scheduleDelayedDispatch(context, options, taskDispatchFromLedgerRecord(record), delay);
 }
-function createRequeuedRecord(record, nextAttempt, nextRetryCount, reason) {
-  return {
-    operationId: record.operationId,
-    activityName: record.activityName,
-    input: record.input,
-    queue: record.queue,
-    attempt: nextAttempt,
-    visibilityTimeout: record.visibilityTimeout,
-    retryPolicy: record.retryPolicy,
-    queuedAt: Date.now(),
-    workflowId: record.workflowId,
-    firstQueuedAt: record.firstQueuedAt,
-    lastDispatchedAt: record.lastDispatchedAt,
-    startedAt: record.startedAt,
-    retryCount: nextRetryCount,
-    requeueCount: (record.requeueCount ?? 0) + 1,
-    lastRequeueReason: reason
-  };
-}
-function createRequeuedTaskDispatch(record, nextAttempt) {
+export function taskDispatchFromLedgerRecord(record) {
   const taskDispatch = {
     operationId: record.operationId,
     activityName: record.activityName,
+    workflowType: record.workflowType,
     input: record.input,
     queue: record.queue,
-    attempt: nextAttempt,
-    visibilityTimeout: record.visibilityTimeout,
-    workflowId: record.workflowId,
+    visibilityTimeout: record.visibilityTimeoutMilliseconds,
     workflowExecutionToken: record.workflowExecutionToken
   };
+  if (record.workflowId !== void 0)
+    taskDispatch.workflowId = record.workflowId;
   if (record.retryPolicy !== void 0)
     taskDispatch.retryPolicy = record.retryPolicy;
+  if (Object.keys(record.headers).length > 0)
+    taskDispatch.headers = record.headers;
+  if (record.priority !== void 0)
+    taskDispatch.priority = record.priority;
+  if (record.fairShareKey !== void 0)
+    taskDispatch.fairShareKey = record.fairShareKey;
+  if (record.stickyWorkflowId !== void 0)
+    taskDispatch.sticky = !0;
   return taskDispatch;
 }
-function scheduleTaskRedispatch(context, options, taskDispatch, policy) {
-  if (policy) {
-    const delay = calculateBackoff((taskDispatch.attempt ?? 1) - 1, policy);
-    scheduleDelayedDispatch(context, options, taskDispatch, delay);
-  } else
-    dispatchTaskImpl(context, options, taskDispatch).catch((err) => console.error(`[weft] Redispatch failed for "${taskDispatch.operationId}":`, err));
+function redispatchAvailableQueuedRecord(context, options, decoded) {
+  if (context.registry.isAssigned(decoded.operationId))
+    return;
+  if (context.taskQueue.isTracked(decoded.operationId))
+    return;
+  scheduleDelayedDispatch(context, options, taskDispatchFromLedgerRecord(decoded), 0);
+}
+async function reapRetainedTerminalRecord(options, decoded, now) {
+  if (options.taskRetentionWindowMs === void 0)
+    return;
+  if (!decoded.adopted)
+    return;
+  const retainedSince = decoded.adoptedAt ?? decoded.terminalAt;
+  if (now - retainedSince < options.taskRetentionWindowMs)
+    return;
+  const deleted = await commitTaskLedgerDelete(options.engine.storage, decoded.operationId, (current) => canDeleteRetainedTerminalTask(current, {
+    expectedRetentionGeneration: decoded.retentionGeneration
+  }), 1);
+  if (!deleted.ok)
+    console.error(`[weft] Failed to reap retained terminal task "${decoded.operationId}": ${deleted.reason}`);
 }
 export async function scanExpiredTasks(context, options, cleanupWorkflowIndex, now = Date.now()) {
   if (context.scanRunning)
@@ -119,17 +115,10 @@ export async function scanExpiredTasks(context, options, cleanupWorkflowIndex, n
       }
       context.processingOperations.add(operationId);
       try {
-        const inflightKey = KEYS.operationInflight(operationId), existing = await options.engine.storage.get(inflightKey);
-        if (!existing)
-          continue;
-        const decoded = decode(existing);
-        if (!isInflightRecord(decoded)) {
-          console.error(`[weft] Corrupt inflight record for task "${operationId}" \u2014 skipping`);
-          continue;
-        }
-        if (await isTaskDeadLettered(options.engine.storage, operationId))
+        const decoded = decodeRemoteTaskRecord(await options.engine.storage.get(taskLedgerKey(operationId)));
+        if (decoded === null || decoded.state !== "leased")
           continue;
-        if (restoreExtendedDeadlineIfStillActive(context.deadlineTracker, operationId, decoded.deadline, now))
+        if (restoreExtendedDeadlineIfStillActive(context.deadlineTracker, operationId, decoded.leaseDeadline, now))
           continue;
         context.registry.completeTask(decoded.operationId);
         cleanupWorkflowIndex(decoded.operationId);
@@ -154,22 +143,33 @@ export async function reconcileOrphanedRecords(context, options, cleanupWorkflow
   try {
     const now = Date.now();
     let staleHeartbeatCount = 0;
-    for await (const [, value] of options.engine.storage.scan("op:inflight:"))
+    for await (const [, value] of options.engine.storage.scan("task-ledger:")) {
+      if (context.stopping)
+        return;
       try {
-        const decoded = decode(value);
-        if (!isInflightRecord(decoded))
+        const decoded = decodeRemoteTaskRecord(value);
+        if (decoded === null)
+          continue;
+        if (decoded.state === "queued") {
+          if (decoded.availableAt <= now)
+            redispatchAvailableQueuedRecord(context, options, decoded);
+          continue;
+        }
+        if (decoded.state === "terminal") {
+          await reapRetainedTerminalRecord(options, decoded, now);
+          continue;
+        }
+        if (decoded.state !== "leased")
           continue;
         if (isTaskHeartbeatStaleForMetrics(decoded, now))
           staleHeartbeatCount += 1;
-        if (await isTaskDeadLettered(options.engine.storage, decoded.operationId))
-          continue;
-        if (decoded.deadline > now) {
+        if (decoded.leaseDeadline > now) {
           if (context.processingOperations.has(decoded.operationId))
             continue;
           context.deadlineTracker.remove(decoded.operationId);
           context.deadlineTracker.add({
             operationId: decoded.operationId,
-            deadline: decoded.deadline
+            deadline: decoded.leaseDeadline
           });
           continue;
         }
@@ -185,8 +185,9 @@ export async function reconcileOrphanedRecords(context, options, cleanupWorkflow
           context.processingOperations.delete(decoded.operationId);
         }
       } catch (error) {
-        console.error("[weft] Failed to reconcile inflight record \u2014 skipping:", error);
+        console.error("[weft] Failed to reconcile leased ledger record \u2014 skipping:", error);
       }
+    }
     recordTaskStaleHeartbeatMetric(context.metricsCollector, staleHeartbeatCount);
   } catch (error) {
     console.error("[weft] Reconciliation scanner error:", error);

package/dist/server/runtime/task-result-resolution.d.ts

@@ -1,15 +1,7 @@
 import { PayloadSizeExceededError } from '../../core/payload-size.ts';
-import type { ServeOptions } from '../index.ts';
-import { type InflightRecord, type TaskResolutionReason } from '../task-state.ts';
-import type { ServerContext } from './context.ts';
-export type TaskResultResolutionInput = {
-    readonly operationId: string;
+export type TaskResultPayloadSizeInput = {
     readonly status: 'completed' | 'failed';
-    readonly resolutionReason: TaskResolutionReason;
     readonly value?: unknown;
     readonly error?: string | undefined;
-    readonly inflightRecord?: InflightRecord | null | undefined;
-    readonly skipPayloadSizeCheck?: boolean | undefined;
 };
-export declare function taskResultPayloadSizeError(input: TaskResultResolutionInput, maxBytes: number | null): PayloadSizeExceededError | null;
-export declare function transitionTaskResultToResolvedWithRetry(context: ServerContext, options: ServeOptions, input: TaskResultResolutionInput): Promise<void>;
+export declare function taskResultPayloadSizeError(input: TaskResultPayloadSizeInput, maxBytes: number | null): PayloadSizeExceededError | null;

package/dist/server/runtime/task-result-resolution.js

@@ -1,13 +1,4 @@
-import { TaskResultDeadLetteredEvent } from "../../core/events.js";
 import { PayloadSizeExceededError, assertPayloadWithinLimit } from "../../core/payload-size.js";
-import {
-  readInflightRecord,
-  transitionInflightToResolved,
-  writeDeadLetteredTaskRecord
-} from "../task-state.js";
-import { withRetry } from "./retry.js";
-import { recordTaskExecutionLatencyMetric } from "./task-metrics.js";
-const TASK_RESULT_RESOLUTION_RETRY_ATTEMPTS = 2;
 function taskResultPayloadForSizeCheck(input) {
   return input.status === "completed" ? input.value : input.error ?? "";
 }
@@ -21,61 +12,3 @@ export function taskResultPayloadSizeError(input, maxBytes) {
     throw error;
   }
 }
-export async function transitionTaskResultToResolvedWithRetry(context, options, input) {
-  if (input.skipPayloadSizeCheck !== !0) {
-    const payloadError = taskResultPayloadSizeError(input, context.payloadSizeMaxBytes);
-    if (payloadError !== null)
-      throw payloadError;
-  }
-  const storage = options.engine.storage, resolvedAt = Date.now();
-  let latestInflightRecord = input.inflightRecord;
-  try {
-    await withRetry(async () => {
-      if (latestInflightRecord === void 0)
-        latestInflightRecord = await readInflightRecord(storage, input.operationId);
-      await transitionInflightToResolved(storage, input.operationId, input.status, {
-        ...latestInflightRecord === null ? {} : { record: latestInflightRecord },
-        resolvedAt,
-        resolutionReason: input.resolutionReason,
-        ...input.status === "completed" ? { value: input.value } : { error: input.error }
-      });
-    }, `transition task "${input.operationId}" to resolved`, TASK_RESULT_RESOLUTION_RETRY_ATTEMPTS);
-  } catch (error) {
-    const fallbackInflightRecord = latestInflightRecord ?? await readInflightRecord(storage, input.operationId).catch(() => null);
-    await withRetry(async () => {
-      await writeTaskResultDeadLetter(options, input, fallbackInflightRecord);
-    }, `dead-letter task "${input.operationId}" after result-resolution retries`, TASK_RESULT_RESOLUTION_RETRY_ATTEMPTS);
-    console.error(`[weft] Failed to transition task "${input.operationId}" to resolved after retries \u2014 dead-lettered:`, error);
-    return;
-  }
-  if (latestInflightRecord !== null && latestInflightRecord !== void 0)
-    recordTaskExecutionLatencyMetric(context.metricsCollector, latestInflightRecord, resolvedAt);
-}
-async function writeTaskResultDeadLetter(options, input, inflightRecord) {
-  const storageErrorCode = "result-resolution-storage-exhausted", record = {
-    operationId: input.operationId,
-    reason: storageErrorCode,
-    deadLetteredAt: Date.now(),
-    errorMessage: storageErrorCode,
-    retryAttempts: TASK_RESULT_RESOLUTION_RETRY_ATTEMPTS,
-    status: input.status,
-    ...inflightRecord?.activityName === void 0 ? {} : { activityName: inflightRecord.activityName },
-    ...inflightRecord?.queue === void 0 ? {} : { queue: inflightRecord.queue },
-    ...inflightRecord?.workerId === void 0 ? {} : { workerId: inflightRecord.workerId },
-    ...inflightRecord?.attempt === void 0 ? {} : { attempt: inflightRecord.attempt },
-    ...inflightRecord?.visibilityTimeout === void 0 ? {} : { visibilityTimeout: inflightRecord.visibilityTimeout },
-    ...inflightRecord?.workflowId === void 0 ? {} : { workflowId: inflightRecord.workflowId },
-    ...inflightRecord?.retryCount === void 0 ? {} : { retryCount: inflightRecord.retryCount },
-    ...inflightRecord?.requeueCount === void 0 ? {} : { requeueCount: inflightRecord.requeueCount },
-    ...inflightRecord?.lastRequeueReason === void 0 ? {} : { lastRequeueReason: inflightRecord.lastRequeueReason }
-  };
-  await writeDeadLetteredTaskRecord(options.engine.storage, record);
-  options.engine.dispatchEvent(new TaskResultDeadLetteredEvent({
-    operationId: record.operationId,
-    workflowId: record.workflowId,
-    activityName: record.activityName,
-    queue: record.queue,
-    workerId: record.workerId,
-    errorMessage: record.errorMessage
-  }));
-}

package/dist/server/runtime/task-result-view.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Public read/adopt surface over a single durable task-ledger record
+ * (WFT-24) — backs `WeftServer.getTaskResult` and `WeftServer.adoptTaskResult`.
+ *
+ * `TaskResultView` is a deliberately narrow projection of
+ * `RemoteTaskRecord`, not a re-export of it: the ledger types are
+ * server-internal (`task-ledger.ts`'s own doc comment — "not re-exported
+ * from `src/index.ts`") and carry fields with no business being public,
+ * such as `workerSessionId`, `attemptToken`, and `executionIdentity`. A
+ * resolved terminal record's actual result *value* is deliberately absent
+ * from this view for the same reason it is absent from the ledger itself:
+ * `RemoteTaskTerminalResolved` only ever stores `resultDigest` (a content
+ * hash), never the value — the durable ledger proves which attempt won,
+ * it does not re-deliver the payload. `resultDigest` exists so a caller
+ * that already has the value through whatever channel actually delivered
+ * it can verify it matches before adopting.
+ *
+ * "Adoption" (`adoptTaskResultImpl`) is an explicit caller assertion, not
+ * something this module infers: nothing in the engine today automatically
+ * links a workflow's own checkpoint to a remote task's terminal ledger
+ * record (that bridge is out of this project's scope — see the `blocks`
+ * relations on the WFT-24 Linear issue). A terminal record an adopter never
+ * calls this for is retained forever, by design; `reapRetainedTerminalRecord`
+ * (`task-reconciliation.ts`) only reaps *adopted* records.
+ *
+ * @module server/runtime/task-result-view
+ */
+import type { Storage } from '../../storage/interface.ts';
+/**
+ * Public, storage-agnostic view of a single task-ledger record.
+ *
+ * @example
+ * ```ts
+ * import { serve, type TaskResultView } from '@lostgradient/weft/server';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * await using server = serve({ engine, port: 0 });
+ *
+ * const view: TaskResultView | null = await server.getTaskResult('op-1');
+ * if (view?.status === 'terminal' && !view.adopted) {
+ *   await server.adoptTaskResult('op-1', view.resultDigest);
+ * }
+ * ```
+ */
+export type TaskResultView = Readonly<{
+    status: 'pending';
+    state: 'queued' | 'leased' | 'completing' | 'cancelling';
+}> | Readonly<{
+    status: 'terminal';
+    disposition: 'resolved' | 'cancelled' | 'retryExhausted';
+    resultDigest: string;
+    terminalAt: number;
+    adopted: boolean;
+    adoptedAt?: number;
+    /** Only present for `disposition: 'resolved'` — whether the worker reported success or failure. */
+    resultStatus?: 'completed' | 'failed';
+    error?: string;
+}> | Readonly<{
+    status: 'deadLettered';
+    persistenceFailureReason: string;
+    pendingStatus: 'completed' | 'failed';
+    deadLetteredAt: number;
+    error?: string;
+}>;
+/**
+ * Read the current public view of a task-ledger record. Returns `null` if
+ * no record exists for `operationId` — either it was never dispatched, or a
+ * retained terminal record has already been reaped.
+ */
+export declare function getTaskResultViewImpl(storage: Storage, operationId: string): Promise<TaskResultView | null>;
+/**
+ * Mark a terminal task's result as adopted by the caller — the durable
+ * assertion that "the workflow checkpoint (or whatever consumed this
+ * result) has incorporated it," per the project brief's adoption/retention
+ * split. Returns `true` once adopted, `false` if the record is not
+ * currently `terminal` or `resultDigest` does not match (including a
+ * record that no longer exists, e.g. already reaped). Idempotent: adopting
+ * an already-adopted record with the same digest succeeds again, refreshing
+ * `adoptedAt`.
+ */
+export declare function adoptTaskResultImpl(storage: Storage, operationId: string, resultDigest: string): Promise<boolean>;

package/dist/server/runtime/task-result-view.js

@@ -0,0 +1,48 @@
+import { markWorkflowResultAdopted } from "../task-ledger-transitions.js";
+import {
+  decodeRemoteTaskRecord,
+  taskLedgerKey
+} from "../task-ledger.js";
+import { commitTaskLedgerTransition } from "./task-ledger-runtime.js";
+function terminalTaskResultView(decoded) {
+  return {
+    status: "terminal",
+    disposition: decoded.disposition,
+    resultDigest: decoded.resultDigest,
+    terminalAt: decoded.terminalAt,
+    adopted: decoded.adopted,
+    ...decoded.adoptedAt !== void 0 ? { adoptedAt: decoded.adoptedAt } : {},
+    ...decoded.disposition === "resolved" ? { resultStatus: decoded.status } : {},
+    ..."error" in decoded && decoded.error !== void 0 ? { error: decoded.error } : {}
+  };
+}
+function deadLetteredTaskResultView(decoded) {
+  return {
+    status: "deadLettered",
+    persistenceFailureReason: decoded.persistenceFailureReason,
+    pendingStatus: decoded.pendingStatus,
+    deadLetteredAt: decoded.deadLetteredAt,
+    ...decoded.error !== void 0 ? { error: decoded.error } : {}
+  };
+}
+export async function getTaskResultViewImpl(storage, operationId) {
+  const decoded = decodeRemoteTaskRecord(await storage.get(taskLedgerKey(operationId)));
+  if (decoded === null)
+    return null;
+  switch (decoded.state) {
+    case "queued":
+    case "leased":
+    case "completing":
+    case "cancelling":
+      return { status: "pending", state: decoded.state };
+    case "terminal":
+      return terminalTaskResultView(decoded);
+    case "deadLettered":
+      return deadLetteredTaskResultView(decoded);
+    default:
+      return decoded;
+  }
+}
+export async function adoptTaskResultImpl(storage, operationId, resultDigest) {
+  return (await commitTaskLedgerTransition(storage, operationId, (current, now) => markWorkflowResultAdopted(current, { expectedResultDigest: resultDigest }, now), 1)).ok;
+}

package/dist/server/runtime/websocket-worker-messaging.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Low-level send/close primitives for the worker WebSocket protocol.
+ *
+ * Split out as a leaf module so both `websocket-worker.ts` (task/heartbeat
+ * handling) and `websocket-worker-registration.ts` (registration handling)
+ * can depend on it without forming an import cycle between those two.
+ *
+ * @module server/runtime/websocket-worker-messaging
+ */
+import type { ServerWebSocket } from 'bun';
+import { type ProtocolErrorMessage, type RegisterErrorMessage } from '../../worker/protocol.ts';
+import type { WebSocketData } from '../json-rpc-websocket-runtime.ts';
+export declare function sendWorkerProtocolMessage(ws: ServerWebSocket<WebSocketData>, message: ProtocolErrorMessage | RegisterErrorMessage | Record<string, unknown>): void;
+export declare function closeWorkerSocket(ws: ServerWebSocket<WebSocketData>, code: number, reason: string): void;
+export declare function rejectRegistration(ws: ServerWebSocket<WebSocketData>, code: RegisterErrorMessage['code'], message: string, requestedProtocolVersion?: number): void;
+export declare function rejectProtocolMessage(ws: ServerWebSocket<WebSocketData>, code: ProtocolErrorMessage['code'], message: string): void;

package/dist/server/runtime/websocket-worker-messaging.js

@@ -0,0 +1,32 @@
+import {
+  REMOTE_WORKER_SUPPORTED_PROTOCOL_VERSIONS
+} from "../../worker/protocol.js";
+const WORKER_PROTOCOL_CLOSE_CODE = 1002, WORKER_REGISTRATION_CLOSE_CODE = 1008;
+export function sendWorkerProtocolMessage(ws, message) {
+  ws.send(JSON.stringify(message));
+}
+export function closeWorkerSocket(ws, code, reason) {
+  try {
+    ws.unsubscribe(ws.data.pathname);
+  } catch {}
+  ws.close(code, reason);
+  setTimeout(() => {
+    try {
+      ws.terminate();
+    } catch {}
+  }, 10);
+}
+export function rejectRegistration(ws, code, message, requestedProtocolVersion) {
+  sendWorkerProtocolMessage(ws, {
+    type: "registerError",
+    code,
+    message,
+    supportedProtocolVersions: REMOTE_WORKER_SUPPORTED_PROTOCOL_VERSIONS,
+    ...requestedProtocolVersion !== void 0 ? { requestedProtocolVersion } : {}
+  });
+  closeWorkerSocket(ws, WORKER_REGISTRATION_CLOSE_CODE, code);
+}
+export function rejectProtocolMessage(ws, code, message) {
+  sendWorkerProtocolMessage(ws, { type: "protocolError", code, message });
+  closeWorkerSocket(ws, WORKER_PROTOCOL_CLOSE_CODE, code);
+}

package/dist/server/runtime/websocket-worker-registration.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Worker registration handling: manifest validation, deployment consistency,
+ * admission policy, and the workerId hijack/reconnect guard.
+ *
+ * Split out of `websocket-worker.ts` to keep that module under the
+ * repository's per-file line ceiling — this is the registration slice of the
+ * same WebSocket message handler.
+ *
+ * @module server/runtime/websocket-worker-registration
+ */
+import type { ServerWebSocket } from 'bun';
+import { type RegisterMessage } from '../../worker/protocol.ts';
+import type { ServeOptions } from '../index.ts';
+import type { WebSocketData } from '../json-rpc-websocket-runtime.ts';
+import type { ServerContext } from './context.ts';
+/**
+ * Validate, admit, and register a worker from its `register` message.
+ *
+ * Layering, in order: principal scope check, manifest parse
+ * (`parseWorkerManifest`), embedded/wire protocol-version agreement,
+ * admission policy, manifest digest, then — synchronously, with no further
+ * `await` between any of them — a live-socket check, a read-only deployment-
+ * consistency check, the workerId hijack/reconnect guard, and only once both
+ * of those gates have passed: the deployment-consistency digest record,
+ * registry insertion, and `registerAck`.
+ *
+ * That whole final block must commit atomically with respect to the event
+ * loop for three independent reasons: two concurrent registrations for the
+ * same not-yet-seen workerId could otherwise both pass the hijack guard
+ * before either commits; a peer that closes while the digest above is still
+ * pending leaves `ws.data.workerId` unset, so the close handler runs no
+ * cleanup, and completing registration afterward would create a ghost worker
+ * on a dead socket; and recording the deployment-consistency digest before
+ * every rejection gate — including the hijack guard, not just the admission
+ * policy — has passed would let a worker this function ultimately declines
+ * still permanently poison that deployment/build slot for future legitimate
+ * workers, since the guard never evicts. See {@link commitWorkerRegistration}
+ * for why the digest record specifically runs after, not alongside, the
+ * hijack guard.
+ */
+export declare function registerWorker(context: ServerContext, options: ServeOptions, ws: ServerWebSocket<WebSocketData>, message: RegisterMessage): Promise<void>;