@lostgradient/weft 0.18.0 → 0.20.0

package/dist/server/operations/list-worker-registration-rejections.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { defineOperation } from "../operation-registry.js";
+const DEFAULT_LIMIT = 20, MAX_LIMIT = 100, registrationRejectionCodeSchema = z.enum([
+  "invalid_registration",
+  "unsupported_protocol_version",
+  "deployment_conflict",
+  "registration_rejected"
+]), registrationRejectionEntrySchema = z.object({
+  code: registrationRejectionCodeSchema,
+  workerId: z.string().optional(),
+  rejectedAt: z.number(),
+  queue: z.string().optional(),
+  deploymentName: z.string().optional(),
+  buildId: z.string().optional()
+}).strict(), listWorkerRegistrationRejectionsInput = z.object({
+  limit: z.number().int().min(1).max(MAX_LIMIT).default(DEFAULT_LIMIT)
+}), listWorkerRegistrationRejectionsOutput = z.object({
+  items: z.array(registrationRejectionEntrySchema),
+  limit: z.number().int().min(1).max(MAX_LIMIT)
+});
+export function createListWorkerRegistrationRejectionsOperation(options = {}) {
+  const registry = options.workerRegistry;
+  return defineOperation({
+    name: "weft.workers.rejections",
+    mcpExposable: !1,
+    summary: "List recently declined worker registration attempts",
+    description: "Bounded, most-recent-first log of declined `register` attempts: rejection code, attempted workerId when known, and whatever deployment/queue identity had already been parsed by the time the rejecting gate ran. No free-text message and no manifest content.",
+    destructive: !1,
+    tags: ["Observability"],
+    inputSchema: listWorkerRegistrationRejectionsInput,
+    outputSchema: listWorkerRegistrationRejectionsOutput,
+    access: { kind: "scoped", scopes: { kind: "anyOf", scopes: ["system:read"] } },
+    producibleFaults: [],
+    discoverable: !0,
+    transports: { http: !0, jsonRpcHttp: !0, jsonRpcWebSocket: !0, jsonRpcStdio: !0 },
+    unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+    invoke: async ({ input }) => {
+      if (registry === void 0)
+        throw Error("weft.workers.rejections invoked from a discovery-only operation registry; no WorkerRegistry was wired in");
+      return { items: registry.getRecentRejections(input.limit), limit: input.limit };
+    }
+  });
+}
+export const listWorkerRegistrationRejectionsOperation = createListWorkerRegistrationRejectionsOperation();
+export function createListWorkerRegistrationRejectionsRestBinding() {
+  return {
+    method: "GET",
+    path: "/v1/workers/registration-rejections",
+    pathParamNames: [],
+    operationName: "weft.workers.rejections",
+    inputSources: {
+      limit: { kind: "query", queryParam: "limit" }
+    },
+    extractInput: async (request) => {
+      const limit = new URL(request.url).searchParams.get("limit");
+      return { limit: limit === null || limit.length === 0 ? void 0 : Number(limit) };
+    },
+    success: { kind: "json", status: 200 }
+  };
+}

package/dist/server/operations/list-workers.js

@@ -27,13 +27,11 @@ const listWorkersInput = z.object({}), routingPolicySchema = z.enum([
   health: workerHealthSchema,
   deploymentName: z.string().optional(),
   buildId: z.string().optional(),
-  runtimeVersion: z.string().optional(),
-  gitSha: z.string().optional()
+  runtimeVersion: z.string().optional()
 }), workerDeploymentSummarySchema = z.object({
   deploymentName: z.string().nullable(),
   buildId: z.string().nullable(),
   runtimeVersion: z.string().nullable(),
-  gitSha: z.string().nullable(),
   health: workerHealthSchema,
   workers: z.number(),
   activeWorkers: z.number(),

package/dist/server/operations/static-registrations.js

@@ -1,7 +1,4 @@
-import {
-  addWorkflowTagsOperation,
-  addWorkflowTagsRestBinding
-} from "./add-workflow-tags.js";
+import { addWorkflowTagsOperation, addWorkflowTagsRestBinding } from "./add-workflow-tags.js";
 import {
   aggregateWorkflowsOperation,
   aggregateWorkflowsRestBinding
@@ -44,6 +41,7 @@ import { getReviewOperation, getReviewRestBinding } from "./get-review.js";
 import { getScheduleOperation, getScheduleRestBinding } from "./get-schedule.js";
 import { getStreamChunksOperation, getStreamChunksRestBinding } from "./get-stream-chunks.js";
 import { getSystemLeaseOperation, getSystemLeaseRestBinding } from "./get-system-lease.js";
+import { getTaskDetailOperation, getTaskDetailRestBinding } from "./get-task-detail.js";
 import {
   clearTaskDeadLetterOperation,
   clearTaskDeadLetterRestBinding,
@@ -54,15 +52,9 @@ import {
   getWorkflowAttributesOperation,
   getWorkflowAttributesRestBinding
 } from "./get-workflow-attributes.js";
-import {
-  getWorkflowEventsOperation,
-  getWorkflowEventsRestBinding
-} from "./get-workflow-events.js";
+import { getWorkflowEventsOperation, getWorkflowEventsRestBinding } from "./get-workflow-events.js";
 import * as workflowObservability from "./get-workflow-observability.js";
-import {
-  getWorkflowResultOperation,
-  getWorkflowResultRestBinding
-} from "./get-workflow-result.js";
+import { getWorkflowResultOperation, getWorkflowResultRestBinding } from "./get-workflow-result.js";
 import {
   getWorkflowTimelineOperation,
   getWorkflowTimelineRestBinding
@@ -113,10 +105,7 @@ import {
   storageScanOperation,
   storageScanRestBinding
 } from "./storage.js";
-import {
-  streamWorkflowSseOperation,
-  streamWorkflowSseRestBinding
-} from "./stream-workflow-sse.js";
+import { streamWorkflowSseOperation, streamWorkflowSseRestBinding } from "./stream-workflow-sse.js";
 import {
   submitReviewDecisionOperation,
   submitReviewDecisionRestBinding
@@ -125,10 +114,7 @@ import { suspendWorkflowOperation, suspendWorkflowRestBinding } from "./suspend-
 import { timeoutWorkflowOperation, timeoutWorkflowRestBinding } from "./timeout-workflow.js";
 import { updateScheduleOperation, updateScheduleRestBinding } from "./update-schedule.js";
 import { updateWorkflowOperation, updateWorkflowRestBinding } from "./update-workflow.js";
-import {
-  workflowEventsSseOperation,
-  workflowEventsSseRestBinding
-} from "./workflow-events-sse.js";
+import { workflowEventsSseOperation, workflowEventsSseRestBinding } from "./workflow-events-sse.js";
 import { workflowEventsSubscriptionOperation } from "./workflow-events-subscription.js";
 export const STATIC_REST_BINDINGS = [
   listAlertsRestBinding,
@@ -185,6 +171,7 @@ export const STATIC_REST_BINDINGS = [
   fleetEventsSseRestBinding,
   getTaskDiagnosticsRestBinding,
   clearTaskDeadLetterRestBinding,
+  getTaskDetailRestBinding,
   listSchedulesRestBinding,
   getScheduleRestBinding,
   replayWorkflowRestBinding,
@@ -248,6 +235,7 @@ export const STATIC_REST_BINDINGS = [
   workflowEventsSubscriptionOperation,
   fleetEventsSubscriptionOperation,
   clearTaskDeadLetterOperation,
+  getTaskDetailOperation,
   listSchedulesOperation,
   listAlertsOperation,
   getPrincipalOperation,

package/dist/server/rest-bindings.js

@@ -7,11 +7,21 @@ import {
   createGetTaskDiagnosticsOperation,
   getTaskDiagnosticsOperation
 } from "./operations/get-task-diagnostics.js";
+import {
+  createGetWorkerDiagnosticsOperation,
+  createGetWorkerDiagnosticsRestBinding,
+  getWorkerDiagnosticsOperation
+} from "./operations/get-worker-diagnostics.js";
 import {
   createListTaskQueuesOperation,
   createListTaskQueuesRestBinding,
   listTaskQueuesOperation
 } from "./operations/list-task-queues.js";
+import {
+  createListWorkerRegistrationRejectionsOperation,
+  createListWorkerRegistrationRejectionsRestBinding,
+  listWorkerRegistrationRejectionsOperation
+} from "./operations/list-worker-registration-rejections.js";
 import {
   createListWorkersOperation,
   createListWorkersRestBinding,
@@ -42,7 +52,9 @@ export function createLiveRestBindings() {
     createClearWorkerDrainRestBinding(),
     createDrainDeploymentRestBinding(),
     createClearDeploymentDrainRestBinding(),
-    createListTaskQueuesRestBinding()
+    createListTaskQueuesRestBinding(),
+    createGetWorkerDiagnosticsRestBinding(),
+    createListWorkerRegistrationRejectionsRestBinding()
   ];
 }
 function buildSystemMetricsOperation(options) {
@@ -100,6 +112,21 @@ function buildTaskDiagnosticsOperationForRegistry(options) {
     ...options.clock !== void 0 ? { now: options.clock } : {}
   });
 }
+function buildWorkerDiagnosticsOperationForRegistry(options) {
+  if (options.workerRegistry === void 0)
+    return getWorkerDiagnosticsOperation;
+  return createGetWorkerDiagnosticsOperation({
+    workerRegistry: options.workerRegistry,
+    ...options.clock !== void 0 ? { clock: options.clock } : {}
+  });
+}
+function buildWorkerRegistrationRejectionsOperationForRegistry(options) {
+  if (options.workerRegistry === void 0)
+    return listWorkerRegistrationRejectionsOperation;
+  return createListWorkerRegistrationRejectionsOperation({
+    workerRegistry: options.workerRegistry
+  });
+}
 export function createLiveOperationRegistry(options) {
   const resolved = options ?? {};
   return createOperationRegistry([
@@ -111,6 +138,8 @@ export function createLiveOperationRegistry(options) {
     buildClearWorkerDrainOperationForRegistry(resolved),
     buildDrainDeploymentOperationForRegistry(resolved),
     buildClearDeploymentDrainOperationForRegistry(resolved),
-    buildListTaskQueuesOperationForRegistry(resolved)
+    buildListTaskQueuesOperationForRegistry(resolved),
+    buildWorkerDiagnosticsOperationForRegistry(resolved),
+    buildWorkerRegistrationRejectionsOperationForRegistry(resolved)
   ]);
 }

package/dist/server/runtime/authentication-bridge.js

@@ -1,7 +1,5 @@
-import { decode } from "../../core/codec.js";
 import { WorkerDisconnectedEvent } from "../../core/events.js";
 import { handleMcpHttpRequest } from "../../mcp/http.js";
-import { KEYS } from "../../storage/interface.js";
 import { authContextToPrincipal, handleRequest } from "../handler.js";
 import { handleJsonRpcHttpRequestSafely } from "../json-rpc-transport-helpers.js";
 import {
@@ -10,6 +8,7 @@ import {
   openJsonRpcWebSocketSession
 } from "../json-rpc-websocket-runtime.js";
 import { API_PREFIX } from "../route-model.js";
+import { decodeRemoteTaskRecord, taskLedgerKey } from "../task-ledger.js";
 import { buildPreflightResponse, decorateResponseWithCors, isPreflightRequest } from "./cors.js";
 import { gateRequest } from "./request-gate.js";
 import { handleTaskPollRequest, handleTaskResultRequest } from "./task-polling.js";
@@ -25,7 +24,7 @@ import {
   replayWatchEvents
 } from "./websocket-stream.js";
 import { handleWebSocketUpgrade } from "./websocket-upgrade.js";
-import { handleWorkerWebSocketMessage, isInflightRecord } from "./websocket-worker.js";
+import { handleWorkerWebSocketMessage } from "./websocket-worker.js";
 export function deriveSupportedOpenApiSecuritySchemes(auth) {
   const schemes = new Set;
   if (auth?.jwt !== void 0)
@@ -206,18 +205,11 @@ function runWorkerDisconnectRequeue(context, options, workerId, _ws, cleanupWork
   for (const task of inFlightTasks)
     (async () => {
       try {
-        const inflightKey = KEYS.operationInflight(task.operationId), existing = await options.engine.storage.get(inflightKey);
-        if (existing) {
-          const record = decode(existing);
-          if (!isInflightRecord(record)) {
-            console.error(`[weft] Corrupt inflight record for task "${task.operationId}" \u2014 skipping reassignment`);
-            return;
-          }
+        const record = decodeRemoteTaskRecord(await options.engine.storage.get(taskLedgerKey(task.operationId)));
+        if (record !== null && record.state === "leased")
           await reassignOrExpireTask(context, options, task.operationId, record, "worker-disconnect");
-        } else {
-          console.warn(`[weft] No inflight record found in storage for task "${task.operationId}" \u2014 skipping reassignment`);
-          await options.engine.storage.delete(inflightKey);
-        }
+        else
+          console.warn(`[weft] No leased ledger record found for task "${task.operationId}" \u2014 skipping reassignment`);
       } catch (error) {
         console.error(`[weft] Failed to reassign task "${task.operationId}" from worker "${workerId}":`, error);
       }

package/dist/server/runtime/context.d.ts

@@ -13,6 +13,19 @@ import type { createLiveOperationRegistry, createLiveRestBindings } from '../res
 import type { TaskQueue } from '../task-queue.ts';
 import type { WorkflowEventFeed } from '../workflow-event-feed.ts';
 import type { ResolvedCorsPolicy } from './cors.ts';
+/**
+ * Startup task-ledger recovery gate (WFT-23). `ready` resolves once every
+ * non-terminal ledger record has been reconstructed into the in-memory
+ * registry, deadline tracker, and task queue indexes; it rejects
+ * (permanently — a settled promise replays the same outcome to every future
+ * awaiter) if the recovery scan itself failed. Task-plane entry points
+ * (`dispatchTaskImpl`, long-poll claim/result, and worker registration) await
+ * this before touching the ledger, so a scan failure blocks new claims with
+ * an actionable error instead of silently continuing with partial indexes.
+ */
+export type TaskLedgerRecoveryGate = Readonly<{
+    ready: Promise<void>;
+}>;
 /**
  * Internal closure state for a single `serve()` invocation.
  *
@@ -77,4 +90,14 @@ export interface ServerContext {
     readonly processingOperations: Set<string>;
     /** Mutex: prevents concurrent reconciliation scans from running simultaneously. */
     reconciliationRunning: boolean;
+    /** Startup task-ledger recovery gate — see {@link TaskLedgerRecoveryGate}. */
+    readonly taskLedgerRecovery: TaskLedgerRecoveryGate;
+    /**
+     * Set once `server.stop()`'s timer-clearing disposer has run. Startup
+     * recovery's scan loop and `scheduleDelayedDispatch` both check this before
+     * doing further work so a still-running recovery scan (or a reconciliation
+     * pass racing shutdown) cannot arm a new timer or issue a durable write
+     * after `pendingTimers` has already been cleared.
+     */
+    stopping: boolean;
 }

package/dist/server/runtime/task-dispatch.d.ts

@@ -1,6 +1,12 @@
 import type { ServeOptions, TaskDispatch } from '../index.ts';
 import type { ServerContext } from './context.ts';
-/** Schedule a delayed dispatch, tracking the timer for cleanup on shutdown. */
+/**
+ * Schedule a delayed dispatch, tracking the timer for cleanup on shutdown.
+ *
+ * No-ops once `context.stopping` is set — `server.stop()`'s timer-clearing
+ * disposer has already run by then, so arming a new timer here would leak a
+ * callback that fires against a stopped server instead of being cleared.
+ */
 export declare function scheduleDelayedDispatch(context: ServerContext, options: ServeOptions, task: TaskDispatch, delay: number): void;
 export declare function resolveTaskPriority(_context: ServerContext, _options: ServeOptions, task: TaskDispatch): number | undefined;
 export declare function dispatchTaskImpl(context: ServerContext, options: ServeOptions, task: TaskDispatch): Promise<boolean>;

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

@@ -1,5 +1,16 @@
+import { isJSONValue } from "../../core/json.js";
+import { buildWorkerExecutionIdentity } from "../../worker/manifest/execution-identity.js";
 import { evictOldestAffinityEntries } from "../runtime-helpers.js";
-import { markQueued, readQueuedRecord, transitionQueuedToInflight } from "../task-state.js";
+import {
+  claimQueued,
+  createQueued
+} from "../task-ledger-transitions.js";
+import {
+  decodeRemoteTaskRecord,
+  REMOTE_TASK_RECORD_VERSION,
+  taskLedgerKey
+} from "../task-ledger.js";
+import { commitTaskLedgerTransition } from "./task-ledger-runtime.js";
 import {
   recordTaskBacklogMetric,
   recordTaskQueueLatencyMetric,
@@ -12,6 +23,8 @@ function clampVisibilityTimeout(value) {
   return Math.min(Math.max(value, MIN_VISIBILITY_TIMEOUT), MAX_VISIBILITY_TIMEOUT);
 }
 export function scheduleDelayedDispatch(context, options, task, delay) {
+  if (context.stopping)
+    return;
   const timer = setTimeout(() => {
     context.pendingTimers.delete(timer);
     dispatchTaskImpl(context, options, task).catch((err) => console.error(`[weft] Delayed redispatch failed for "${task.operationId}":`, err));
@@ -52,6 +65,55 @@ function recordDispatchOutcome(context, task, workerId) {
   operationIds.add(task.operationId);
   context.operationToWorkflow.set(task.operationId, task.workflowId);
 }
+function buildOptionalCreateQueuedFields(task) {
+  return {
+    ...task.workflowId !== void 0 ? { workflowId: task.workflowId } : {},
+    ...task.workflowExecutionToken !== void 0 ? { workflowExecutionToken: task.workflowExecutionToken } : {},
+    ...task.priority !== void 0 ? { priority: task.priority } : {},
+    ...task.fairShareKey !== void 0 ? { fairShareKey: task.fairShareKey } : {},
+    ...task.sticky && task.workflowId !== void 0 ? { stickyWorkflowId: task.workflowId } : {},
+    ...task.retryPolicy !== void 0 ? { retryPolicy: task.retryPolicy } : {}
+  };
+}
+function buildCreateQueuedInput(task, queue, visibilityTimeout) {
+  const input = task.input === void 0 ? null : task.input;
+  if (!isJSONValue(input))
+    throw Error(`TaskDispatch for operation "${task.operationId}" has a non-JSON-serializable "input" \u2014 the durable task ledger requires JSON-safe input.`);
+  return {
+    recordVersion: REMOTE_TASK_RECORD_VERSION,
+    operationId: task.operationId,
+    workflowType: task.workflowType,
+    activityName: task.activityName,
+    queue,
+    input,
+    headers: task.headers ?? {},
+    visibilityTimeoutMilliseconds: visibilityTimeout,
+    createdAt: Date.now(),
+    ...buildOptionalCreateQueuedFields(task)
+  };
+}
+function buildCreateThenClaimTransition(createInput, claimInput) {
+  return (current, now) => {
+    let queuedRecord;
+    if (current === null) {
+      const created = createQueued(null, createInput, now);
+      if (!created.ok)
+        return created;
+      queuedRecord = created.nextRecord;
+    } else if (current.state === "queued")
+      queuedRecord = current;
+    else
+      return {
+        ok: !1,
+        reason: `operation "${createInput.operationId}" is not claimable from state "${current.state}"`
+      };
+    return claimQueued(queuedRecord, { ...claimInput, expectedGeneration: queuedRecord.generation }, now);
+  };
+}
+function bareActivityName(qualifiedActivityName) {
+  const dotIndex = qualifiedActivityName.indexOf(".");
+  return dotIndex === -1 ? qualifiedActivityName : qualifiedActivityName.slice(dotIndex + 1);
+}
 async function selectAndReserveWorker(context, options, task, queue, visibilityTimeout) {
   const routingOptions = buildRoutingOptions(context, task, queue), worker = context.registry.findWorker(task.activityName, routingOptions);
   if (!worker)
@@ -59,86 +121,85 @@ async function selectAndReserveWorker(context, options, task, queue, visibilityT
   const ws = context.workerSockets.get(worker.id);
   if (!ws)
     return !1;
-  const now = Date.now(), existingQueuedRecord = await readQueuedRecord(options.engine.storage, task.operationId), attemptToken = crypto.randomUUID();
+  const createInput = buildCreateQueuedInput(task, queue, visibilityTimeout), attemptToken = crypto.randomUUID(), executionIdentity = buildWorkerExecutionIdentity({
+    manifest: worker.manifest,
+    manifestDigest: worker.acceptedManifestDigest,
+    workerId: worker.id,
+    workflowType: task.workflowType,
+    activityName: bareActivityName(task.activityName)
+  });
   context.registry.assignTask(worker.id, task.operationId, visibilityTimeout, task.fairShareKey, attemptToken);
-  const deadline = now + visibilityTimeout;
-  context.deadlineTracker.add({ operationId: task.operationId, deadline });
-  const inflightRecord = {
+  let result;
+  try {
+    result = await commitTaskLedgerTransition(options.engine.storage, task.operationId, buildCreateThenClaimTransition(createInput, {
+      attemptToken,
+      workerSessionId: worker.id,
+      ...executionIdentity !== void 0 ? { executionIdentity } : {},
+      leaseDurationMilliseconds: visibilityTimeout
+    }), 1);
+  } catch (error) {
+    context.registry.releaseReservation(task.operationId);
+    throw error;
+  }
+  if (!result.ok) {
+    context.registry.releaseReservation(task.operationId);
+    return !1;
+  }
+  context.deadlineTracker.add({
     operationId: task.operationId,
-    workerId: worker.id,
-    deadline,
-    activityName: task.activityName,
-    queue,
-    input: task.input,
-    attempt: task.attempt ?? 1,
-    visibilityTimeout,
-    retryPolicy: task.retryPolicy,
-    workflowId: task.workflowId,
-    workflowExecutionToken: task.workflowExecutionToken,
-    attemptToken
-  }, normalizedInflightRecord = await transitionQueuedToInflight(options.engine.storage, task.operationId, inflightRecord, {
-    queuedRecord: existingQueuedRecord,
-    now
+    deadline: result.record.leaseDeadline
   });
   ws.send(JSON.stringify({
     type: "task",
     operationId: task.operationId,
     activityName: task.activityName,
     input: task.input === void 0 ? null : task.input,
-    attempt: task.attempt ?? 1,
+    attempt: result.record.attempt,
     attemptToken,
     ...task.workflowExecutionToken !== void 0 && {
       workflowExecutionToken: task.workflowExecutionToken
     },
     ...task.headers ? { headers: task.headers } : {}
   }));
-  recordTaskQueueLatencyMetric(context.metricsCollector, normalizedInflightRecord);
+  recordTaskQueueLatencyMetric(context.metricsCollector, {
+    lastQueuedAt: result.record.lastQueuedAt,
+    lastDispatchedAt: Date.now()
+  });
   recordWorkerCapacitySaturationMetric(context.metricsCollector, context.registry);
   recordDispatchOutcome(context, task, worker.id);
   return !0;
 }
-function mergeQueuedRecordLifecycle(fresh, existing) {
-  return {
-    ...fresh,
-    firstQueuedAt: existing?.firstQueuedAt ?? fresh.queuedAt,
-    lastQueuedAt: fresh.queuedAt,
-    lastDispatchedAt: existing?.lastDispatchedAt,
-    startedAt: existing?.startedAt,
-    retryCount: existing?.retryCount ?? fresh.retryCount,
-    requeueCount: existing?.requeueCount ?? fresh.requeueCount,
-    lastRequeueReason: existing?.lastRequeueReason
-  };
-}
 async function enqueueTaskForLongPoll(context, options, task, queue, visibilityTimeout, resolvedPriority) {
-  const attempt = task.attempt ?? 1, freshRecord = {
-    operationId: task.operationId,
-    activityName: task.activityName,
-    input: task.input,
-    queue,
-    attempt,
-    visibilityTimeout,
-    retryPolicy: task.retryPolicy,
-    queuedAt: Date.now(),
-    workflowId: task.workflowId,
-    workflowExecutionToken: task.workflowExecutionToken,
-    retryCount: Math.max(0, attempt - 1),
-    requeueCount: 0
-  }, existingQueuedRecord = await readQueuedRecord(options.engine.storage, task.operationId), normalizedQueuedRecord = await markQueued(options.engine.storage, mergeQueuedRecordLifecycle(freshRecord, existingQueuedRecord)), enqueued = context.taskQueue.enqueue(queue, {
+  const storage = options.engine.storage, createInput = buildCreateQueuedInput(task, queue, visibilityTimeout), rawExisting = await storage.get(taskLedgerKey(task.operationId)), current = decodeRemoteTaskRecord(rawExisting);
+  let queuedRecord;
+  if (current === null) {
+    const result = await commitTaskLedgerTransition(storage, task.operationId, (freshCurrent, now) => createQueued(freshCurrent, createInput, now), 1);
+    if (!result.ok) {
+      const raced = decodeRemoteTaskRecord(await storage.get(taskLedgerKey(task.operationId)));
+      if (raced === null || raced.state !== "queued")
+        return !1;
+      queuedRecord = raced;
+    } else
+      queuedRecord = result.record;
+  } else if (current.state === "queued")
+    queuedRecord = current;
+  else
+    return !1;
+  const enqueued = context.taskQueue.enqueue(queue, {
     operationId: task.operationId,
     activityName: task.activityName,
     input: task.input,
-    attempt,
+    attempt: queuedRecord.attempt,
     retryPolicy: task.retryPolicy,
     visibilityTimeout,
     workflowId: task.workflowId,
     workflowExecutionToken: task.workflowExecutionToken,
-    firstQueuedAt: normalizedQueuedRecord.firstQueuedAt,
-    lastQueuedAt: normalizedQueuedRecord.lastQueuedAt,
-    lastDispatchedAt: normalizedQueuedRecord.lastDispatchedAt,
-    startedAt: normalizedQueuedRecord.startedAt,
-    retryCount: normalizedQueuedRecord.retryCount,
-    requeueCount: normalizedQueuedRecord.requeueCount,
-    lastRequeueReason: normalizedQueuedRecord.lastRequeueReason,
+    firstQueuedAt: queuedRecord.firstQueuedAt,
+    lastQueuedAt: queuedRecord.lastQueuedAt,
+    lastDispatchedAt: queuedRecord.lastDispatchedAt,
+    startedAt: queuedRecord.startedAt,
+    retryCount: queuedRecord.retryCount,
+    requeueCount: queuedRecord.requeueCount,
     ...task.headers ? { headers: task.headers } : {},
     ...resolvedPriority !== void 0 ? { priority: resolvedPriority } : {}
   });
@@ -146,6 +207,16 @@ async function enqueueTaskForLongPoll(context, options, task, queue, visibilityT
   return enqueued;
 }
 export async function dispatchTaskImpl(context, options, task) {
+  try {
+    await context.taskLedgerRecovery.ready;
+  } catch (error) {
+    throw Error(`Cannot dispatch task "${task.operationId}" \u2014 startup task-ledger recovery failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  if (!task.workflowType)
+    throw Error(`TaskDispatch for operation "${task.operationId}" is missing required field "workflowType".`);
+  const dotIndex = task.activityName.indexOf(".");
+  if (dotIndex !== -1 && task.activityName.slice(0, dotIndex) !== task.workflowType)
+    throw Error(`TaskDispatch for operation "${task.operationId}" has activityName "${task.activityName}" whose qualifier does not match workflowType "${task.workflowType}".`);
   const queue = task.queue ?? "default", visibilityTimeout = clampVisibilityTimeout(task.visibilityTimeout), resolvedPriority = resolveTaskPriority(context, options, task);
   if (!validateTaskEnvelope(context, task))
     return !1;

package/dist/server/runtime/task-ledger-completion.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared two-step commit for applying a worker's task result to the durable
+ * remote task ledger (WFT-22) — used by both the WebSocket (`onTaskResultMessage`)
+ * and long-poll (`handleTaskResultRequest`) completion paths.
+ *
+ * `Leased --> Completing --> Terminal` is committed as two separate durable
+ * writes, not one, even though the caller already holds the full result: the
+ * project brief models `Completing` as an observable intermediate state
+ * specifically so a crash between the two writes leaves a durable, recoverable
+ * marker ("Completing prevents visibility scanning or disconnect handling from
+ * requeueing an attempt while its terminal result is being applied") that
+ * WFT-23's recovery is designed to resume. Collapsing the two transitions into
+ * one write would make that state unobservable and defeat the point of having
+ * it.
+ *
+ * A submitter can itself resume that crash window: if the record is already
+ * `completing` with the same `attemptToken` AND the same `pendingResultDigest`
+ * — the worker retrying the identical result after a server crash between the
+ * two writes, or a benign duplicate submission — this skips straight to
+ * `commitTerminalResult` instead of rejecting a legitimate resubmission with
+ * "expected task state leased". A `completing` record whose digest or token
+ * differs is a genuinely different result and is rejected normally.
+ *
+ * On exhausted retries — specifically when the *second* write
+ * (`commitTerminalFromCompleting`) exhausts its CAS retry budget after the
+ * record is already durably `completing` — this attempts one best-effort
+ * `Completing --> DeadLettered` write (WFT-24's `commitDeadLetter`,
+ * `../task-ledger-transitions.ts`) so a sustained, operation-specific
+ * storage write failure becomes an operator-visible dead letter instead of a
+ * silently stuck record. If the *first* write (`beginCompletion`) exhausts
+ * instead, the record never left `leased` and no dead letter is attempted —
+ * the visibility scanner's ordinary expiry path already covers that case.
+ * If the dead-letter write itself also fails, this falls back to the plain
+ * `ok: false` result exactly as before WFT-24: the record stays `completing`,
+ * a worker resubmitting the identical result can still resume through the
+ * `resuming` branch above, and no data is lost.
+ *
+ * @module server/runtime/task-ledger-completion
+ */
+import type { Storage } from '../../storage/interface.ts';
+import type { ServeOptions } from '../index.ts';
+import { type RemoteTaskCompleting, type RemoteTaskDeadLettered, type RemoteTaskTerminal } from '../task-ledger.ts';
+export type TaskLedgerCompletionInput = Readonly<{
+    operationId: string;
+    attemptToken: string;
+    status: 'completed' | 'failed';
+    value?: unknown;
+    error?: string;
+}>;
+export type TaskLedgerCompletionResult = Readonly<{
+    ok: true;
+    completing: RemoteTaskCompleting;
+    terminal: RemoteTaskTerminal;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+    deadLettered?: RemoteTaskDeadLettered;
+}>;
+/**
+ * Dispatch {@link TaskResultDeadLetteredEvent} for a record `commitTaskLedgerCompletion`
+ * dead-lettered. Shared by the WebSocket and long-poll completion paths so
+ * both build the event from the same fields — `workflowId`/`activityName`/`queue`
+ * come from the dead-lettered record itself (present on every `RemoteTaskBase`),
+ * not from the caller's original request, so the event is accurate even if the
+ * caller only had partial information.
+ */
+export declare function dispatchTaskDeadLetteredEvent(options: ServeOptions, operationId: string, deadLettered: RemoteTaskDeadLettered, workerId: string | undefined): void;
+export declare function commitTaskLedgerCompletion(storage: Storage, input: TaskLedgerCompletionInput): Promise<TaskLedgerCompletionResult>;