@lostgradient/weft 0.2.0

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

@@ -0,0 +1,163 @@
+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 { transitionInflightToQueued, transitionInflightToResolved } from "../task-state.js";
+import { dispatchTaskImpl, scheduleDelayedDispatch } from "./task-dispatch.js";
+import {
+  isTaskHeartbeatStaleForMetrics,
+  recordTaskRequeueMetric,
+  recordTaskRetryMetric,
+  recordTaskStaleHeartbeatMetric,
+  recordWorkerCapacitySaturationMetric
+} from "./task-metrics.js";
+import { isInflightRecord } from "./websocket-worker.js";
+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);
+    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));
+}
+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) {
+  const taskDispatch = {
+    operationId: record.operationId,
+    activityName: record.activityName,
+    input: record.input,
+    queue: record.queue,
+    attempt: nextAttempt,
+    visibilityTimeout: record.visibilityTimeout,
+    workflowId: record.workflowId
+  };
+  if (record.retryPolicy !== void 0)
+    taskDispatch.retryPolicy = record.retryPolicy;
+  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));
+}
+export async function scanExpiredTasks(context, options, cleanupWorkflowIndex) {
+  if (context.scanRunning)
+    return;
+  context.scanRunning = !0;
+  try {
+    const now = Date.now(), expired = context.deadlineTracker.drainExpired(now);
+    for (const { operationId, deadline } of expired) {
+      if (context.processingOperations.has(operationId)) {
+        context.deadlineTracker.add({ operationId, deadline });
+        continue;
+      }
+      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 (restoreExtendedDeadlineIfStillActive(context.deadlineTracker, operationId, decoded.deadline, now))
+          continue;
+        context.registry.completeTask(decoded.operationId);
+        cleanupWorkflowIndex(decoded.operationId);
+        await reassignOrExpireTask(context, options, decoded.operationId, decoded);
+      } catch (error) {
+        context.deadlineTracker.add({ operationId, deadline });
+        console.error(`[weft] Failed to process expired task "${operationId}" \u2014 will retry:`, error);
+      } finally {
+        context.processingOperations.delete(operationId);
+      }
+    }
+  } catch (error) {
+    console.error("[weft] Visibility timeout scanner error:", error);
+  } finally {
+    context.scanRunning = !1;
+  }
+}
+export async function reconcileOrphanedRecords(context, options, cleanupWorkflowIndex) {
+  if (context.reconciliationRunning)
+    return;
+  context.reconciliationRunning = !0;
+  try {
+    const now = Date.now();
+    let staleHeartbeatCount = 0;
+    for await (const [, value] of options.engine.storage.scan("op:inflight:"))
+      try {
+        const decoded = decode(value);
+        if (!isInflightRecord(decoded))
+          continue;
+        if (isTaskHeartbeatStaleForMetrics(decoded, now))
+          staleHeartbeatCount += 1;
+        if (decoded.deadline > now) {
+          if (context.processingOperations.has(decoded.operationId))
+            continue;
+          context.deadlineTracker.remove(decoded.operationId);
+          context.deadlineTracker.add({
+            operationId: decoded.operationId,
+            deadline: decoded.deadline
+          });
+          continue;
+        }
+        if (context.processingOperations.has(decoded.operationId))
+          continue;
+        context.processingOperations.add(decoded.operationId);
+        try {
+          context.deadlineTracker.remove(decoded.operationId);
+          context.registry.completeTask(decoded.operationId);
+          cleanupWorkflowIndex(decoded.operationId);
+          await reassignOrExpireTask(context, options, decoded.operationId, decoded);
+        } finally {
+          context.processingOperations.delete(decoded.operationId);
+        }
+      } catch (error) {
+        console.error("[weft] Failed to reconcile inflight record \u2014 skipping:", error);
+      }
+    recordTaskStaleHeartbeatMetric(context.metricsCollector, staleHeartbeatCount);
+  } catch (error) {
+    console.error("[weft] Reconciliation scanner error:", error);
+  } finally {
+    context.reconciliationRunning = !1;
+  }
+}

package/dist/server/runtime/websocket-stream.d.ts

@@ -0,0 +1,15 @@
+import type { ServerWebSocket } from 'bun';
+import type { Engine } from '../../core/engine.ts';
+import type { WebSocketData } from '../json-rpc-websocket-runtime.ts';
+import type { ServerContext } from './context.ts';
+export declare function sendStreamMessage(ws: ServerWebSocket<WebSocketData>, sequence: number, message: string): void;
+export declare function getHighestStoredStreamSequence(engine: Engine, workflowId: string, key: string): Promise<number>;
+export declare function addStreamSocket(context: ServerContext, workflowId: string, ws: ServerWebSocket<WebSocketData>): void;
+export declare function removeStreamSocket(context: ServerContext, ws: ServerWebSocket<WebSocketData>): void;
+export declare function flushPendingStreamMessages(_context: ServerContext, ws: ServerWebSocket<WebSocketData>): void;
+export declare function publishTokenMessage(context: ServerContext, workflowId: string, sequence: number, message: string): void;
+/**
+ * Send existing token chunks from storage to a newly connected stream client,
+ * so it can catch up on tokens emitted before the connection was established.
+ */
+export declare function replayTokenStream(context: ServerContext, engine: Engine, ws: ServerWebSocket<WebSocketData>, workflowId: string): Promise<void>;

package/dist/server/runtime/websocket-stream.js

@@ -0,0 +1,79 @@
+import { KEYS } from "../../storage/interface.js";
+const TOKEN_EVENT_TYPE = "stream:token";
+export function sendStreamMessage(ws, sequence, message) {
+  if (sequence <= (ws.data.lastDeliveredSequence ?? -1))
+    return;
+  ws.send(message);
+  ws.data.lastDeliveredSequence = sequence;
+}
+export async function getHighestStoredStreamSequence(engine, workflowId, key) {
+  const prefix = KEYS.streamChunkPrefix(workflowId, key);
+  for await (const [storageKey] of engine.storage.scan(prefix, { reverse: !0, limit: 1 })) {
+    const sequenceText = storageKey.slice(prefix.length), sequence = Number.parseInt(sequenceText, 10);
+    if (Number.isSafeInteger(sequence) && sequence >= 0)
+      return sequence;
+  }
+  return -1;
+}
+export function addStreamSocket(context, workflowId, ws) {
+  let sockets = context.streamSockets.get(workflowId);
+  if (!sockets) {
+    sockets = new Set;
+    context.streamSockets.set(workflowId, sockets);
+  }
+  sockets.add(ws);
+}
+export function removeStreamSocket(context, ws) {
+  const workflowId = ws.data.workflowId;
+  if (!workflowId)
+    return;
+  const sockets = context.streamSockets.get(workflowId);
+  if (!sockets)
+    return;
+  sockets.delete(ws);
+  if (sockets.size === 0)
+    context.streamSockets.delete(workflowId);
+}
+export function flushPendingStreamMessages(_context, ws) {
+  const pendingMessages = ws.data.pendingStreamMessages ?? [];
+  pendingMessages.sort((left, right) => left.sequence - right.sequence);
+  for (const pending of pendingMessages)
+    sendStreamMessage(ws, pending.sequence, pending.message);
+  ws.data.pendingStreamMessages = [];
+}
+export function publishTokenMessage(context, workflowId, sequence, message) {
+  const sockets = context.streamSockets.get(workflowId);
+  if (!sockets)
+    return;
+  for (const ws of sockets) {
+    if (ws.data.replayInProgress) {
+      ws.data.pendingStreamMessages ??= [];
+      ws.data.pendingStreamMessages.push({ sequence, message });
+      continue;
+    }
+    sendStreamMessage(ws, sequence, message);
+  }
+}
+export async function replayTokenStream(context, engine, ws, workflowId) {
+  ws.data.lastDeliveredSequence = -1;
+  try {
+    const requestedResumeFrom = ws.data.resumeFrom, after = requestedResumeFrom === void 0 ? -1 : Math.min(requestedResumeFrom, await getHighestStoredStreamSequence(engine, workflowId, "tokens"));
+    ws.data.lastDeliveredSequence = after;
+    const chunks = after >= 0 ? await engine.getStreamChunks(workflowId, "tokens", { after }) : await engine.getStreamChunks(workflowId, "tokens");
+    for (const chunk of chunks) {
+      if (typeof chunk.value !== "object" || chunk.value === null)
+        continue;
+      sendStreamMessage(ws, chunk.sequence, JSON.stringify({
+        type: TOKEN_EVENT_TYPE,
+        timestamp: Date.now(),
+        sequence: chunk.sequence,
+        data: chunk.value
+      }));
+    }
+  } catch (error) {
+    console.error(`[weft] Failed to replay token stream for workflow "${workflowId}":`, error);
+  } finally {
+    ws.data.replayInProgress = !1;
+    flushPendingStreamMessages(context, ws);
+  }
+}

package/dist/server/runtime/websocket-upgrade.d.ts

@@ -0,0 +1,8 @@
+import type { AuthContext } from '../authentication.ts';
+import type { ServeOptions } from '../index.ts';
+import type { WebSocketData } from '../json-rpc-websocket-runtime.ts';
+import type { ServerContext } from './context.ts';
+export declare const WORKER_STREAM_RE: RegExp;
+/** Classify a WebSocket request URL and extract relevant parameters. */
+export declare function classifyConnection(url: URL): Pick<WebSocketData, 'connectionType' | 'workflowId' | 'queue'> | null;
+export declare function handleWebSocketUpgrade(server: ReturnType<typeof Bun.serve>, context: ServerContext, options: ServeOptions, request: Request, url: URL, authContext?: AuthContext): Response | undefined | null;

package/dist/server/runtime/websocket-upgrade.js

@@ -0,0 +1,76 @@
+import { authContextToPrincipal } from "../handler.js";
+import { finalizeWebSocketUpgrade } from "../json-rpc-transport-helpers.js";
+import { isAuthenticated } from "../principal.js";
+import { parseOptionalSequenceCursor } from "../sequence-cursor.js";
+import { isOriginAllowed } from "./cors.js";
+export const WORKER_STREAM_RE = /^\/v1\/tasks\/([\w-]+)\/stream$/;
+const WORKFLOW_STREAM_RE = /^\/v1\/workflows\/([^/]+)\/stream$/, WORKFLOW_WATCH_RE = /^\/v1\/workflows\/([^/]+)\/watch$/;
+function tryDecodePathComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+}
+function matchUpgradePath(pathname, pattern) {
+  const match = pattern.exec(pathname);
+  if (!match?.[1])
+    return;
+  return tryDecodePathComponent(match[1]);
+}
+export function classifyConnection(url) {
+  const { pathname } = url, workflowStreamId = matchUpgradePath(pathname, WORKFLOW_STREAM_RE);
+  if (workflowStreamId !== void 0)
+    return workflowStreamId === null ? null : { connectionType: "stream", workflowId: workflowStreamId };
+  const workflowWatchId = matchUpgradePath(pathname, WORKFLOW_WATCH_RE);
+  if (workflowWatchId !== void 0)
+    return workflowWatchId === null ? null : { connectionType: "watch", workflowId: workflowWatchId };
+  const queue = matchUpgradePath(pathname, WORKER_STREAM_RE);
+  if (queue !== void 0)
+    return queue === null ? null : { connectionType: "worker", queue };
+  if (pathname === "/jsonrpc")
+    return { connectionType: "jsonrpc" };
+  return { connectionType: "generic" };
+}
+function rejectsCrossOriginUpgrade(context, request) {
+  const origin = request.headers.get("origin");
+  return context.corsPolicy !== null && origin !== null && !isOriginAllowed(context.corsPolicy, origin);
+}
+function resolvePrincipalForUpgrade(connectionType, authContext) {
+  if (connectionType !== "jsonrpc" && connectionType !== "worker")
+    return { ok: !0, principal: void 0 };
+  if (authContext === void 0)
+    return { ok: !0, principal: void 0 };
+  let principal;
+  try {
+    principal = authContextToPrincipal(authContext);
+  } catch (error) {
+    console.error("[weft] WebSocket upgrade principal resolution failed", error);
+    return { ok: !1, response: new Response("Authentication context invalid", { status: 401 }) };
+  }
+  if (connectionType === "worker" && isAuthenticated(principal) && !principal.hasScope("workers:write"))
+    return { ok: !1, response: new Response("Insufficient scope", { status: 403 }) };
+  return { ok: !0, principal };
+}
+export function handleWebSocketUpgrade(server, context, options, request, url, authContext) {
+  if (request.headers.get("upgrade") !== "websocket")
+    return null;
+  if (rejectsCrossOriginUpgrade(context, request))
+    return new Response("Cross-origin WebSocket upgrade not allowed", { status: 403 });
+  const classification = classifyConnection(url);
+  if (classification === null)
+    return new Response("Invalid encoded WebSocket path", { status: 400 });
+  const resolution = resolvePrincipalForUpgrade(classification.connectionType, authContext);
+  if (!resolution.ok)
+    return resolution.response;
+  const { principal } = resolution, resumeFromParam = url.searchParams.get("resumeFrom"), resumeFromResult = parseOptionalSequenceCursor(resumeFromParam, "resumeFrom query parameter");
+  if (resumeFromResult.error)
+    return new Response(resumeFromResult.error, { status: 400 });
+  const resumeFrom = resumeFromResult.value;
+  return finalizeWebSocketUpgrade(server, request, {
+    pathname: url.pathname,
+    ...classification,
+    ...principal ? { principal } : {},
+    ...resumeFrom !== void 0 ? { resumeFrom } : {}
+  });
+}

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

@@ -0,0 +1,7 @@
+import type { ServerWebSocket } from 'bun';
+import type { ServeOptions } from '../index.ts';
+import type { WebSocketData } from '../json-rpc-websocket-runtime.ts';
+import type { ServerContext } from './context.ts';
+export { isInflightRecord } from '../task-state.ts';
+export declare function withRetry<T>(operation: () => Promise<T>, label: string, maxAttempts?: number): Promise<T>;
+export declare function handleWorkerWebSocketMessage(context: ServerContext, options: ServeOptions, ws: ServerWebSocket<WebSocketData>, rawMessage: string | Buffer, cleanupWorkflowIndex: (operationId: string) => void): void;

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

@@ -0,0 +1,224 @@
+import { decode, encode } from "../../core/codec.js";
+import { KEYS } from "../../storage/interface.js";
+import {
+  REMOTE_WORKER_PROTOCOL_VERSION,
+  REMOTE_WORKER_SUPPORTED_PROTOCOL_VERSIONS,
+  parseWorkerToServerMessage
+} from "../../worker/protocol.js";
+import { workerProtocolIncompatibleMessage } from "../../worker/worker-protocol-incompatible-error.js";
+import { isAuthenticated } from "../principal.js";
+import {
+  isInflightRecord,
+  readInflightRecord,
+  transitionInflightToResolved
+} from "../task-state.js";
+import {
+  recordTaskExecutionLatencyMetric,
+  recordWorkerCapacitySaturationMetric
+} from "./task-metrics.js";
+import { WORKER_STREAM_RE } from "./websocket-upgrade.js";
+const MAX_WORKER_CONCURRENCY = 1000, DEFAULT_WORKER_CONCURRENCY = 10, WORKER_PROTOCOL_CLOSE_CODE = 1002, WORKER_REGISTRATION_CLOSE_CODE = 1008;
+function isWorkerConnection(pathname) {
+  return WORKER_STREAM_RE.test(pathname);
+}
+export { isInflightRecord } from "../task-state.js";
+export async function withRetry(operation, label, maxAttempts = 2) {
+  let lastError;
+  for (let attempt = 1;attempt <= maxAttempts; attempt++)
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      if (attempt < maxAttempts) {
+        console.warn(`[weft] Retrying "${label}" (attempt ${attempt + 1}/${maxAttempts})`);
+        await Bun.sleep(100 * attempt);
+      }
+    }
+  throw lastError;
+}
+function sendWorkerProtocolMessage(ws, message) {
+  ws.send(JSON.stringify(message));
+}
+function closeWorkerSocket(ws, code, reason) {
+  try {
+    ws.unsubscribe(ws.data.pathname);
+  } catch {}
+  ws.close(code, reason);
+  setTimeout(() => {
+    try {
+      ws.terminate();
+    } catch {}
+  }, 10);
+}
+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);
+}
+function rejectProtocolMessage(ws, code, message) {
+  sendWorkerProtocolMessage(ws, { type: "protocolError", code, message });
+  closeWorkerSocket(ws, WORKER_PROTOCOL_CLOSE_CODE, code);
+}
+function principalMayRegisterWorker(principal) {
+  if (principal === void 0)
+    return !0;
+  return isAuthenticated(principal) && principal.hasScope("workers:write");
+}
+function buildWorkerRegistrationInfo(message, queue, concurrency) {
+  return {
+    id: message.workerId,
+    queue,
+    activities: [...message.activities],
+    concurrency,
+    ...message.deploymentName !== void 0 ? { deploymentName: message.deploymentName } : {},
+    ...message.buildId !== void 0 ? { buildId: message.buildId } : {},
+    ...message.runtimeVersion !== void 0 ? { runtimeVersion: message.runtimeVersion } : {},
+    ...message.gitSha !== void 0 ? { gitSha: message.gitSha } : {},
+    ...message.startedAt !== void 0 ? { startedAt: message.startedAt } : {},
+    ...message.capabilities !== void 0 ? { capabilities: message.capabilities } : {}
+  };
+}
+function registerWorker(context, ws, message) {
+  if (!principalMayRegisterWorker(ws.data.principal)) {
+    rejectRegistration(ws, "invalid_registration", "Worker registration requires the workers:write scope", message.protocolVersion);
+    return;
+  }
+  const rawConcurrency = message.concurrency ?? DEFAULT_WORKER_CONCURRENCY, clampedConcurrency = Math.min(Math.max(1, Math.floor(rawConcurrency)), MAX_WORKER_CONCURRENCY), queue = ws.data.queue ?? "default", pendingRequeue = context.pendingWorkerRequeues.get(message.workerId);
+  if (pendingRequeue !== void 0) {
+    clearTimeout(pendingRequeue);
+    context.pendingWorkerRequeues.delete(message.workerId);
+  }
+  ws.data.workerId = message.workerId;
+  ws.data.workerRegistered = !0;
+  ws.data.workerProtocolVersion = message.protocolVersion;
+  context.registry.register(buildWorkerRegistrationInfo(message, queue, clampedConcurrency));
+  context.workerSockets.set(message.workerId, ws);
+  sendWorkerProtocolMessage(ws, {
+    type: "registerAck",
+    protocolVersion: REMOTE_WORKER_PROTOCOL_VERSION,
+    workerId: message.workerId,
+    queue,
+    activities: [...message.activities],
+    concurrency: clampedConcurrency
+  });
+}
+function resolveTaskResultStatus(message) {
+  return message.status === "completed" ? "completed" : "failed";
+}
+function onTaskResultMessage(context, options, ws, message, cleanupWorkflowIndex) {
+  const operationId = message.operationId, workerId = ws.data.workerId;
+  if (workerId === void 0 || !context.registry.isAssignedToWorker(operationId, workerId)) {
+    sendWorkerProtocolMessage(ws, {
+      type: "protocolError",
+      code: "invalid_message",
+      message: `taskResult for operation "${operationId}" rejected \u2014 task not assigned to worker "${workerId ?? ""}"`
+    });
+    return;
+  }
+  context.registry.completeTask(operationId);
+  context.deadlineTracker.remove(operationId);
+  cleanupWorkflowIndex(operationId);
+  recordWorkerCapacitySaturationMetric(context.metricsCollector, context.registry);
+  (async () => {
+    const inflightRecord = await readInflightRecord(options.engine.storage, operationId), resolvedAt = Date.now(), resolvedStatus = resolveTaskResultStatus(message);
+    await transitionInflightToResolved(options.engine.storage, operationId, resolvedStatus, {
+      ...inflightRecord === null ? {} : { record: inflightRecord },
+      resolvedAt,
+      resolutionReason: resolvedStatus,
+      ...message.status === "completed" ? { value: message.value } : { error: message.error }
+    });
+    if (inflightRecord !== null)
+      recordTaskExecutionLatencyMetric(context.metricsCollector, inflightRecord, resolvedAt);
+  })().catch((error) => {
+    console.error(`[weft] Failed to transition task "${operationId}" to resolved \u2014 inflight record may leak:`, error);
+  });
+}
+function onHeartbeatMessage(context, options, ws, _message) {
+  const workerId = ws.data.workerId;
+  if (!workerId)
+    return;
+  context.registry.heartbeat(workerId);
+  for (const task of context.registry.getWorkerTasks(workerId)) {
+    const newDeadline = context.registry.extendVisibility(task.operationId, task.visibilityTimeout);
+    if (newDeadline !== void 0) {
+      context.deadlineTracker.remove(task.operationId);
+      context.deadlineTracker.add({ operationId: task.operationId, deadline: newDeadline });
+      const opId = task.operationId, heartbeatWorkerId = ws.data.workerId;
+      withRetry(async () => {
+        if (!context.registry.isAssigned(opId))
+          return;
+        if (!context.registry.getWorkerTasks(heartbeatWorkerId ?? "").find((trackedTask) => trackedTask.operationId === opId))
+          return;
+        const inflightKey = KEYS.operationInflight(opId), existing = await options.engine.storage.get(inflightKey);
+        if (existing) {
+          const decoded = decode(existing);
+          if (!isInflightRecord(decoded)) {
+            console.error(`[weft] Corrupt inflight record for task "${opId}" during heartbeat \u2014 skipping visibility extension`);
+            return;
+          }
+          const updated = { ...decoded, deadline: newDeadline, lastHeartbeatAt: Date.now() };
+          await options.engine.storage.put(inflightKey, encode(updated));
+        }
+      }, `extend visibility for task "${opId}"`).catch((error) => {
+        console.error(`[weft] Failed to extend visibility for task "${opId}":`, error);
+      });
+    }
+  }
+}
+function parseAndValidateWorkerFrame(ws, rawMessage) {
+  const text = typeof rawMessage === "string" ? rawMessage : new TextDecoder().decode(rawMessage);
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    rejectProtocolMessage(ws, "invalid_json", "Worker protocol messages must be valid JSON");
+    return { ok: !1 };
+  }
+  const result = parseWorkerToServerMessage(parsed);
+  if (!result.ok) {
+    if (result.error.code === "invalid_registration" || result.error.code === "unsupported_protocol_version") {
+      const message = result.error.code === "unsupported_protocol_version" ? workerProtocolIncompatibleMessage({
+        expected: REMOTE_WORKER_PROTOCOL_VERSION,
+        received: result.error.requestedProtocolVersion
+      }) : result.error.message;
+      rejectRegistration(ws, result.error.code, message, result.error.requestedProtocolVersion);
+      return { ok: !1 };
+    }
+    rejectProtocolMessage(ws, result.error.code, result.error.message);
+    return { ok: !1 };
+  }
+  return { ok: !0, message: result.message };
+}
+export function handleWorkerWebSocketMessage(context, options, ws, rawMessage, cleanupWorkflowIndex) {
+  if (!isWorkerConnection(ws.data.pathname))
+    return;
+  const parsed = parseAndValidateWorkerFrame(ws, rawMessage);
+  if (!parsed.ok)
+    return;
+  const { message } = parsed;
+  if (message.type !== "register" && ws.data.workerRegistered !== !0) {
+    rejectProtocolMessage(ws, "registration_required", "Worker must register before sending heartbeat or taskResult messages");
+    return;
+  }
+  switch (message.type) {
+    case "register": {
+      registerWorker(context, ws, message);
+      break;
+    }
+    case "taskResult": {
+      onTaskResultMessage(context, options, ws, message, cleanupWorkflowIndex);
+      break;
+    }
+    case "heartbeat": {
+      onHeartbeatMessage(context, options, ws, message);
+      break;
+    }
+    default:
+      return message;
+  }
+}

package/dist/server/runtime-helpers.d.ts

@@ -0,0 +1,18 @@
+/** Claim the next event sequence number for a workflow. */
+export declare function claimNextSequence(sequenceCounters: Map<string, number>, workflowId: string): number;
+/** Evict the oldest workflow affinity entry when the cache grows beyond its cap. */
+export declare function evictOldestAffinityEntries(workerAffinity: Map<string, string>, maxEntries: number): void;
+/** Restore an extended deadline back into the tracker when a stale heap entry expires. */
+export declare function restoreExtendedDeadline(deadlineTracker: {
+    add(entry: {
+        operationId: string;
+        deadline: number;
+    }): void;
+}, operationId: string, deadline: number): void;
+/** Restore a stale heap entry when the recorded deadline is still in the future. */
+export declare function restoreExtendedDeadlineIfStillActive(deadlineTracker: {
+    add(entry: {
+        operationId: string;
+        deadline: number;
+    }): void;
+}, operationId: string, deadline: number, now: number): boolean;

package/dist/server/runtime-helpers.js

@@ -0,0 +1,23 @@
+export function claimNextSequence(sequenceCounters, workflowId) {
+  const current = sequenceCounters.get(workflowId);
+  if (current === void 0)
+    throw Error(`Sequence counter for workflow "${workflowId}" accessed before initialization`);
+  sequenceCounters.set(workflowId, current + 1);
+  return current;
+}
+export function evictOldestAffinityEntries(workerAffinity, maxEntries) {
+  if (workerAffinity.size > maxEntries) {
+    const firstKey = workerAffinity.keys().next().value;
+    if (firstKey !== void 0)
+      workerAffinity.delete(firstKey);
+  }
+}
+export function restoreExtendedDeadline(deadlineTracker, operationId, deadline) {
+  deadlineTracker.add({ operationId, deadline });
+}
+export function restoreExtendedDeadlineIfStillActive(deadlineTracker, operationId, deadline, now) {
+  if (deadline <= now)
+    return !1;
+  restoreExtendedDeadline(deadlineTracker, operationId, deadline);
+  return !0;
+}

package/dist/server/sequence-cursor.d.ts

@@ -0,0 +1,5 @@
+export interface ParsedSequenceCursor {
+    error?: string;
+    value?: number;
+}
+export declare function parseOptionalSequenceCursor(rawValue: string | null | undefined, parameterName: string): ParsedSequenceCursor;

package/dist/server/sequence-cursor.js

@@ -0,0 +1,19 @@
+const DECIMAL_INTEGER_PATTERN = /^-?\d+$/;
+export function parseOptionalSequenceCursor(rawValue, parameterName) {
+  if (rawValue === null || rawValue === void 0)
+    return {};
+  if (rawValue.trim().length === 0)
+    return {
+      error: `Invalid ${parameterName}: ${rawValue}`
+    };
+  if (!DECIMAL_INTEGER_PATTERN.test(rawValue))
+    return {
+      error: `Invalid ${parameterName}: ${rawValue}`
+    };
+  const value = Number(rawValue);
+  if (!Number.isSafeInteger(value) || value < -1)
+    return {
+      error: `Invalid ${parameterName}: ${rawValue}`
+    };
+  return { value };
+}