@lostgradient/weft 0.17.0 → 0.19.0

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

@@ -0,0 +1,64 @@
+/**
+ * Shared commit loop for the durable remote task ledger's live dispatch path
+ * (WFT-22) — claim, heartbeat, completion, and requeue all attempt a single
+ * pure transition against the current ledger record through
+ * `storage.conditionalBatch`, retrying only when the compare-and-swap itself
+ * is lost (a concurrent writer changed the record between read and write),
+ * never when the transition's own precondition rejects the freshly re-read
+ * record. A precondition rejection means the requested transition genuinely
+ * does not apply — for example the task is already terminal — and retrying
+ * the same rejected transition would just reject again.
+ *
+ * `commitTaskLedgerDelete` (WFT-24) is the delete counterpart, used by
+ * terminal-task retention: a conditional delete gated on a precondition
+ * function rather than a transition function, since deletion has no next
+ * record to write.
+ *
+ * @module server/runtime/task-ledger-runtime
+ */
+import { type Storage } from '../../storage/interface.ts';
+import type { TaskLedgerPreconditionResult, TaskLedgerTransitionResult } from '../task-ledger-transitions.ts';
+import { type RemoteTaskRecord } from '../task-ledger.ts';
+export type TaskLedgerCommitResult<T extends RemoteTaskRecord> = Readonly<{
+    ok: true;
+    record: T;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+export type TaskLedgerDeleteResult = Readonly<{
+    ok: true;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Read the current ledger record, apply `transitionFn`, and commit the
+ * result with `expectedValue` set to the exact bytes just read — CAS by raw
+ * byte equality, not `encode(decode(bytes))` re-serialization (see
+ * `task-ledger-transitions.ts`'s module doc comment).
+ *
+ * Retries only a lost CAS (up to `maxAttempts`), re-reading and
+ * re-evaluating `transitionFn` against the fresh record each time — a
+ * concurrent heartbeat renewal, for instance, is a benign generation bump
+ * worth retrying past. A `transitionFn` precondition rejection returns
+ * immediately without consuming a retry, since the fresh record already
+ * reflects reality and re-attempting the identical transition cannot change
+ * the outcome.
+ */
+export declare function commitTaskLedgerTransition<T extends RemoteTaskRecord>(storage: Storage, operationId: string, transitionFn: (current: RemoteTaskRecord | null, now: number) => TaskLedgerTransitionResult<T>, maxAttempts?: number): Promise<TaskLedgerCommitResult<T>>;
+/**
+ * Read the current ledger record, check a delete-only precondition (WFT-24
+ * retention: {@link canDeleteRetainedTerminalTask}), and conditionally delete
+ * with `expectedValue` set to the exact bytes just read — the delete
+ * counterpart to {@link commitTaskLedgerTransition}, needed because
+ * `canDeleteRetainedTerminalTask` has no next record to write, only a
+ * precondition to satisfy before issuing a delete.
+ *
+ * Retries only a lost CAS, same as `commitTaskLedgerTransition` — a
+ * concurrent writer that changed the record between read and delete (for
+ * example a later adoption call bumping `retentionGeneration`) means the
+ * fresh record deserves a fresh precondition check, not a delete of state
+ * the caller never actually observed.
+ */
+export declare function commitTaskLedgerDelete(storage: Storage, operationId: string, preconditionFn: (current: RemoteTaskRecord | null) => TaskLedgerPreconditionResult, maxAttempts?: number): Promise<TaskLedgerDeleteResult>;

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

@@ -0,0 +1,34 @@
+import { storageConditionalBatch } from "../../storage/interface.js";
+import {
+  decodeRemoteTaskRecord,
+  encodeRemoteTaskRecord,
+  taskLedgerKey
+} from "../task-ledger.js";
+export async function commitTaskLedgerTransition(storage, operationId, transitionFn, maxAttempts = 1) {
+  const key = taskLedgerKey(operationId);
+  for (let attempt = 1;attempt <= maxAttempts; attempt++) {
+    const rawExisting = await storage.get(key), current = decodeRemoteTaskRecord(rawExisting), result = transitionFn(current, Date.now());
+    if (!result.ok)
+      return result;
+    if (await storageConditionalBatch(storage, [{ key, expectedValue: rawExisting }], [{ type: "put", key, value: encodeRemoteTaskRecord(result.nextRecord) }]))
+      return { ok: !0, record: result.nextRecord };
+  }
+  return {
+    ok: !1,
+    reason: `lost the compare-and-swap race on operation "${operationId}" after ${String(maxAttempts)} attempt(s)`
+  };
+}
+export async function commitTaskLedgerDelete(storage, operationId, preconditionFn, maxAttempts = 1) {
+  const key = taskLedgerKey(operationId);
+  for (let attempt = 1;attempt <= maxAttempts; attempt++) {
+    const rawExisting = await storage.get(key), current = decodeRemoteTaskRecord(rawExisting), result = preconditionFn(current);
+    if (!result.ok)
+      return result;
+    if (await storageConditionalBatch(storage, [{ key, expectedValue: rawExisting }], [{ type: "delete", key }]))
+      return { ok: !0 };
+  }
+  return {
+    ok: !1,
+    reason: `lost the compare-and-swap race deleting operation "${operationId}" after ${String(maxAttempts)} attempt(s)`
+  };
+}

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

@@ -1,12 +1,14 @@
 import { type MetricsCollector } from '../../observability/metrics.ts';
 import type { WorkerRegistry } from '../../worker/registry.ts';
 import type { TaskQueue } from '../task-queue.ts';
-import { type InflightRecord, type ResolvedRecord } from '../task-state.ts';
+import { type TaskTimingFields } from '../task-state.ts';
 export declare function recordTaskBacklogMetric(metricsCollector: MetricsCollector | undefined, taskQueue: TaskQueue): void;
-export declare function recordTaskQueueLatencyMetric(metricsCollector: MetricsCollector | undefined, record: InflightRecord | ResolvedRecord): void;
-export declare function recordTaskExecutionLatencyMetric(metricsCollector: MetricsCollector | undefined, record: InflightRecord | ResolvedRecord, completedAt: number): void;
+export declare function recordTaskQueueLatencyMetric(metricsCollector: MetricsCollector | undefined, record: TaskTimingFields): void;
+export declare function recordTaskExecutionLatencyMetric(metricsCollector: MetricsCollector | undefined, record: TaskTimingFields, completedAt: number): void;
 export declare function recordTaskRetryMetric(metricsCollector: MetricsCollector | undefined, count?: number): void;
 export declare function recordTaskRequeueMetric(metricsCollector: MetricsCollector | undefined, count?: number): void;
-export declare function isTaskHeartbeatStaleForMetrics(record: InflightRecord, currentTime: number, staleAfterMs?: number): boolean;
+export declare function isTaskHeartbeatStaleForMetrics(record: TaskTimingFields & {
+    deadline?: number | undefined;
+}, currentTime: number, staleAfterMs?: number): boolean;
 export declare function recordTaskStaleHeartbeatMetric(metricsCollector: MetricsCollector | undefined, count: number): void;
 export declare function recordWorkerCapacitySaturationMetric(metricsCollector: MetricsCollector | undefined, registry: WorkerRegistry): void;

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

@@ -1,23 +1,25 @@
 import type { ServeOptions } from '../index.ts';
 import { type Principal } from '../principal.ts';
 import type { PendingTask } from '../task-queue-types.ts';
-import type { InflightRecord } from '../task-state.ts';
 import type { ServerContext } from './context.ts';
-/**
- * A freshly created long-poll inflight record always carries an `attemptToken`.
- * The intersection makes that invariant a compile-time fact so the claim can read
- * the token directly without an unreachable empty-string fallback.
- */
-type TokenedInflightRecord = InflightRecord & {
-    attemptToken: string;
-};
-export declare function createLongPollInflightRecord(queue: string, task: PendingTask): TokenedInflightRecord;
 /** The worker-facing identity of a long-poll claim: the synthetic worker id and its per-claim token. */
 export interface LongPollClaim {
     workerId: string;
     attemptToken: string;
 }
-export declare function markTaskClaimedByLongPollWorker(context: ServerContext, options: ServeOptions, queue: string, task: PendingTask): Promise<LongPollClaim>;
+/**
+ * Conditionally claim the durable `queued` ledger record for a task the
+ * in-memory `TaskQueue` matched to a long-poll waiter. Returns `null` when
+ * the claim loses — the ledger disagrees with the in-memory match hint,
+ * meaning another actor already claimed or cancelled this operationId — in
+ * which case the caller treats the poll as if nothing matched, per "index
+ * disagreement never authorizes a state transition".
+ *
+ * Long-poll workers never call `WorkerRegistry.register()`, so there is no
+ * manifest to build a `WorkerExecutionIdentity` from; the claim always omits
+ * `executionIdentity` (see `RemoteTaskLeased.executionIdentity`'s doc
+ * comment) rather than fabricate one.
+ */
+export declare function markTaskClaimedByLongPollWorker(context: ServerContext, options: ServeOptions, task: PendingTask): Promise<LongPollClaim | null>;
 export declare function handleTaskPollRequest(context: ServerContext, options: ServeOptions, request: Request, url: URL, principal?: Principal): Promise<Response | null>;
 export declare function handleTaskResultRequest(context: ServerContext, options: ServeOptions, request: Request, url: URL, principal?: Principal): Promise<Response | null>;
-export {};

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

@@ -1,11 +1,18 @@
 import { isAuthenticated } from "../principal.js";
 import { readRestJsonBody } from "../rest-body.js";
-import { readInflightRecord, transitionQueuedToInflight } from "../task-state.js";
-import { recordTaskBacklogMetric, recordTaskQueueLatencyMetric } from "./task-metrics.js";
+import { claimQueued } from "../task-ledger-transitions.js";
+import { decodeRemoteTaskRecord, taskLedgerKey } from "../task-ledger.js";
 import {
-  taskResultPayloadSizeError,
-  transitionTaskResultToResolvedWithRetry
-} from "./task-result-resolution.js";
+  commitTaskLedgerCompletion,
+  dispatchTaskDeadLetteredEvent
+} from "./task-ledger-completion.js";
+import { commitTaskLedgerTransition } from "./task-ledger-runtime.js";
+import {
+  recordTaskBacklogMetric,
+  recordTaskExecutionLatencyMetric,
+  recordTaskQueueLatencyMetric
+} from "./task-metrics.js";
+import { taskResultPayloadSizeError } from "./task-result-resolution.js";
 const TASK_POLL_RE = /^\/v1\/tasks\/([\w-]+)$/, TASK_RESULT_RE = /^\/v1\/tasks\/([\w-]+)\/result$/, TASK_DIAGNOSTICS_PATH = "/v1/tasks/diagnostics", MAX_POLL_TIMEOUT = 60000, DEFAULT_POLL_TIMEOUT = 30000, DEFAULT_VISIBILITY_TIMEOUT = 30000;
 async function parseTaskResultBody(request, options) {
   try {
@@ -26,6 +33,16 @@ function authorizeWorkerPrincipal(principal) {
     return null;
   return Response.json({ error: "Forbidden" }, { status: 403 });
 }
+async function awaitTaskLedgerRecovery(context) {
+  try {
+    await context.taskLedgerRecovery.ready;
+    return null;
+  } catch (error) {
+    return Response.json({
+      error: `Startup task-ledger recovery failed \u2014 cannot admit new task claims: ${error instanceof Error ? error.message : String(error)}`
+    }, { status: 503 });
+  }
+}
 function validateTaskResultBody(body) {
   const { operationId, status } = body;
   if (typeof operationId !== "string" || typeof status !== "string")
@@ -44,37 +61,35 @@ function validateTaskResultBody(body) {
     attemptToken: rawAttemptToken
   };
 }
-async function applyTaskResult(context, options, result, inflightRecord) {
-  const { operationId, status, value, error } = result, resolvedStatus = status === "failed" ? "failed" : "completed";
-  try {
-    context.taskQueue.complete({ operationId, status, value, error });
-    context.deadlineTracker.remove(operationId);
-    await transitionTaskResultToResolvedWithRetry(context, options, {
-      operationId,
-      status: resolvedStatus,
-      resolutionReason: resolvedStatus,
-      inflightRecord,
-      ...status === "completed" ? { value } : { error }
-    });
-  } catch (storageError) {
-    console.error(`[weft] Failed to transition task "${operationId}" to resolved \u2014 inflight record may leak:`, storageError);
-  }
+function isLongPollCompletionAuthorized(record, validated) {
+  if (record === null)
+    return !1;
+  if (record.state !== "leased" && record.state !== "completing")
+    return !1;
+  if (validated.workerId === void 0 || record.workerSessionId !== validated.workerId)
+    return !1;
+  return validated.attemptToken === record.attemptToken;
 }
-async function applyPayloadRejectedTaskResult(context, options, result, inflightRecord, error) {
-  context.taskQueue.complete({
-    operationId: result.operationId,
-    status: "failed",
-    error: error.message
-  });
-  context.deadlineTracker.remove(result.operationId);
-  await transitionTaskResultToResolvedWithRetry(context, options, {
-    operationId: result.operationId,
-    status: "failed",
-    resolutionReason: "failed",
-    inflightRecord,
-    error: error.message,
-    skipPayloadSizeCheck: !0
+async function applyTaskResult(context, options, result) {
+  const { operationId, status, value, error } = result, committed = await commitTaskLedgerCompletion(options.engine.storage, {
+    operationId,
+    attemptToken: result.attemptToken,
+    status,
+    ...status === "completed" ? { value } : {},
+    ...status === "failed" && error !== void 0 ? { error } : {}
   });
+  if (!committed.ok) {
+    if (committed.deadLettered !== void 0) {
+      context.deadlineTracker.remove(operationId);
+      dispatchTaskDeadLetteredEvent(options, operationId, committed.deadLettered, result.workerId);
+    }
+    return { ok: !1, reason: committed.reason };
+  }
+  recordTaskExecutionLatencyMetric(context.metricsCollector, { startedAt: committed.completing.startedAt }, Date.now());
+  context.taskQueue.complete({ operationId, status, value, error });
+  context.deadlineTracker.remove(operationId);
+  recordTaskBacklogMetric(context.metricsCollector, context.taskQueue);
+  return { ok: !0 };
 }
 function payloadSizeExceededResponse(error) {
   return Response.json({
@@ -85,43 +100,32 @@ function payloadSizeExceededResponse(error) {
     payloadKind: error.payloadKind
   }, { status: 413 });
 }
-export function createLongPollInflightRecord(queue, task) {
-  const now = Date.now(), visibilityTimeout = task.visibilityTimeout ?? DEFAULT_VISIBILITY_TIMEOUT, deadline = now + visibilityTimeout;
-  return {
-    operationId: task.operationId,
-    workerId: `longpoll-${crypto.randomUUID().slice(0, 8)}`,
-    deadline,
-    activityName: task.activityName,
-    queue,
-    input: task.input,
-    attempt: task.attempt ?? 1,
-    visibilityTimeout,
-    retryPolicy: task.retryPolicy,
-    workflowId: task.workflowId,
-    workflowExecutionToken: task.workflowExecutionToken,
-    attemptToken: crypto.randomUUID(),
-    firstQueuedAt: task.firstQueuedAt ?? task.enqueuedAt ?? now,
-    lastQueuedAt: task.lastQueuedAt ?? task.enqueuedAt ?? now,
-    lastDispatchedAt: now,
-    startedAt: now,
-    retryCount: task.retryCount ?? Math.max(0, (task.attempt ?? 1) - 1),
-    requeueCount: task.requeueCount ?? 0,
-    lastRequeueReason: task.lastRequeueReason
-  };
-}
-export async function markTaskClaimedByLongPollWorker(context, options, queue, task) {
-  const inflightRecord = createLongPollInflightRecord(queue, task);
+export async function markTaskClaimedByLongPollWorker(context, options, task) {
+  const workerSessionId = `longpoll-${crypto.randomUUID().slice(0, 8)}`, attemptToken = crypto.randomUUID(), visibilityTimeout = task.visibilityTimeout ?? DEFAULT_VISIBILITY_TIMEOUT, result = await commitTaskLedgerTransition(options.engine.storage, task.operationId, (current, now) => {
+    if (current === null || current.state !== "queued")
+      return {
+        ok: !1,
+        reason: `operation "${task.operationId}" is not claimable from its current ledger state`
+      };
+    return claimQueued(current, {
+      expectedGeneration: current.generation,
+      attemptToken,
+      workerSessionId,
+      leaseDurationMilliseconds: visibilityTimeout
+    }, now);
+  }, 1);
+  if (!result.ok)
+    return null;
   context.deadlineTracker.add({
     operationId: task.operationId,
-    deadline: inflightRecord.deadline
+    deadline: result.record.leaseDeadline
+  });
+  recordTaskQueueLatencyMetric(context.metricsCollector, {
+    lastQueuedAt: result.record.lastQueuedAt,
+    lastDispatchedAt: Date.now()
   });
-  const normalizedInflightRecord = await transitionQueuedToInflight(options.engine.storage, task.operationId, inflightRecord);
-  recordTaskQueueLatencyMetric(context.metricsCollector, normalizedInflightRecord);
   recordTaskBacklogMetric(context.metricsCollector, context.taskQueue);
-  return {
-    workerId: normalizedInflightRecord.workerId,
-    attemptToken: inflightRecord.attemptToken
-  };
+  return { workerId: workerSessionId, attemptToken };
 }
 export async function handleTaskPollRequest(context, options, request, url, principal) {
   if (request.method !== "GET")
@@ -134,12 +138,17 @@ export async function handleTaskPollRequest(context, options, request, url, prin
   const authorizationResponse = authorizeWorkerPrincipal(principal);
   if (authorizationResponse !== null)
     return authorizationResponse;
+  const recoveryResponse = await awaitTaskLedgerRecovery(context);
+  if (recoveryResponse !== null)
+    return recoveryResponse;
   const queue = decodeURIComponent(pollMatch[1]), activities = url.searchParams.getAll("activity");
   if (activities.length === 0)
     return Response.json({ error: 'At least one "activity" query parameter is required' }, { status: 400 });
   const rawTimeout = url.searchParams.get("timeout"), timeout = rawTimeout !== null ? Math.min(Math.max(0, Number(rawTimeout)), MAX_POLL_TIMEOUT) : DEFAULT_POLL_TIMEOUT, task = await context.taskQueue.poll(queue, activities, timeout, request.signal);
   if (task !== null) {
-    const claim = await markTaskClaimedByLongPollWorker(context, options, queue, task);
+    const claim = await markTaskClaimedByLongPollWorker(context, options, task);
+    if (claim === null)
+      return new Response(null, { status: 204 });
     return Response.json({
       ...task,
       workerId: claim.workerId,
@@ -159,6 +168,9 @@ export async function handleTaskResultRequest(context, options, request, url, pr
   const authorizationResponse = authorizeWorkerPrincipal(principal);
   if (authorizationResponse !== null)
     return authorizationResponse;
+  const recoveryResponse = await awaitTaskLedgerRecovery(context);
+  if (recoveryResponse !== null)
+    return recoveryResponse;
   const body = await parseTaskResultBody(request, options.maxRequestBodyBytes !== void 0 ? { maxBodyBytes: options.maxRequestBodyBytes } : {});
   if (body instanceof Response)
     return body;
@@ -167,28 +179,40 @@ export async function handleTaskResultRequest(context, options, request, url, pr
   const validated = validateTaskResultBody(body);
   if (validated instanceof Response)
     return validated;
-  const inflightRecord = await readInflightRecord(options.engine.storage, validated.operationId);
-  if (inflightRecord !== null && !isLongPollCompletionAuthorized(inflightRecord, validated))
+  const record = decodeRemoteTaskRecord(await options.engine.storage.get(taskLedgerKey(validated.operationId)));
+  if (!isLongPollCompletionAuthorized(record, validated))
     return Response.json({ error: "Forbidden" }, { status: 403 });
   const payloadError = taskResultPayloadSizeError({
-    operationId: validated.operationId,
     status: validated.status,
-    resolutionReason: validated.status,
     ...validated.status === "completed" ? { value: validated.value } : { error: validated.error }
   }, context.payloadSizeMaxBytes);
   if (payloadError !== null) {
-    try {
-      await applyPayloadRejectedTaskResult(context, options, validated, inflightRecord, payloadError);
-    } catch (error) {
-      console.error(`[weft] Failed to persist oversized task result rejection for task "${validated.operationId}":`, error);
+    const rejected = await commitTaskLedgerCompletion(options.engine.storage, {
+      operationId: validated.operationId,
+      attemptToken: validated.attemptToken,
+      status: "failed",
+      error: payloadError.message
+    });
+    if (rejected.ok) {
+      recordTaskExecutionLatencyMetric(context.metricsCollector, { startedAt: rejected.completing.startedAt }, Date.now());
+      context.taskQueue.complete({
+        operationId: validated.operationId,
+        status: "failed",
+        error: payloadError.message
+      });
+      context.deadlineTracker.remove(validated.operationId);
+      recordTaskBacklogMetric(context.metricsCollector, context.taskQueue);
+    } else {
+      console.error(`[weft] Failed to persist oversized task result rejection for task "${validated.operationId}":`, rejected.reason);
+      if (rejected.deadLettered !== void 0)
+        dispatchTaskDeadLetteredEvent(options, validated.operationId, rejected.deadLettered, validated.workerId);
     }
     return payloadSizeExceededResponse(payloadError);
   }
-  await applyTaskResult(context, options, validated, inflightRecord);
+  const applied = await applyTaskResult(context, options, validated);
+  if (!applied.ok) {
+    console.error(`[weft] Failed to commit task result for "${validated.operationId}" through the durable ledger:`, applied.reason);
+    return Response.json({ error: "Forbidden" }, { status: 403 });
+  }
   return Response.json({ ok: !0 });
 }
-function isLongPollCompletionAuthorized(inflightRecord, validated) {
-  if (validated.workerId === void 0 || inflightRecord.workerId !== validated.workerId)
-    return !1;
-  return validated.attemptToken === inflightRecord.attemptToken;
-}

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

@@ -1,5 +1,5 @@
-import type { ServeOptions } from '../index.ts';
-import type { InflightRecord, TaskRequeueReason } from '../task-state.ts';
+import type { ServeOptions, TaskDispatch } from '../index.ts';
+import { type RemoteTaskBase, type RemoteTaskLeased } from '../task-ledger.ts';
 import type { ServerContext } from './context.ts';
 interface ManualTaskReconciliationForTesting {
     readonly options: ServeOptions;
@@ -10,17 +10,44 @@ export declare function useManualTaskReconciliationForTesting(options: ServeOpti
 /** @internal Installs the narrow one-shot test controller before a server starts. */
 export declare function consumeManualTaskReconciliationForTesting(options: ServeOptions, context: ServerContext, cleanupWorkflowIndex: (operationId: string) => void): boolean;
 /**
- * Given a persisted inflight record, either permanently fail the task (if
- * retry attempts are exhausted) or transition it back to queued and
- * re-dispatch with backoff. Both the worker-disconnect handler and the
- * visibility-timeout scanner share this logic.
+ * Given a leased ledger record whose visibility deadline has passed, either
+ * permanently fail the task (retry attempts exhausted) or requeue it with
+ * backoff for redispatch. Both the worker-disconnect handler and the
+ * visibility-timeout scanner share this logic. A single attempt, no retry —
+ * a lost compare-and-swap here means a concurrent heartbeat renewed the
+ * lease or another actor already resolved this attempt, and retrying the
+ * identical transition cannot change that outcome.
  */
-export declare function reassignOrExpireTask(context: ServerContext, options: ServeOptions, operationId: string, record: InflightRecord, reason?: TaskRequeueReason): Promise<void>;
+export declare function reassignOrExpireTask(context: ServerContext, options: ServeOptions, operationId: string, record: RemoteTaskLeased, reason?: string): Promise<void>;
+/**
+ * Reconstruct the `TaskDispatch` a fresh dispatch of this operation would
+ * have used, from the durable envelope alone. Shared by expired-lease
+ * redispatch ({@link reassignOrExpireTask}) and startup recovery's
+ * `queued`-record redispatch (`task-ledger-recovery.ts`) — both cases hand a
+ * record back to `dispatchTaskImpl` with no original caller-supplied
+ * `TaskDispatch` still in memory. Every `RemoteTaskBase` field
+ * `buildRoutingOptions`/`resolveTaskPriority` read at dispatch time
+ * (`priority`, `fairShareKey`, sticky affinity) must round-trip here too, or
+ * a requeued or recovered task silently loses its original routing intent.
+ */
+export declare function taskDispatchFromLedgerRecord(record: RemoteTaskBase): TaskDispatch;
 /**
  * Drain expired entries from the in-memory deadline heap and reassign
  * their tasks. Only touches storage for the specific operations whose
- * deadlines have actually passed — no full `op:inflight:*` scan.
+ * deadlines have actually passed — no full ledger scan.
  */
 export declare function scanExpiredTasks(context: ServerContext, options: ServeOptions, cleanupWorkflowIndex: (operationId: string) => void, now?: number): Promise<void>;
+/**
+ * Periodic full-ledger safety net (WFT-23), independent of the in-memory
+ * deadline heap `scanExpiredTasks` drains: catches `leased` records whose
+ * expiry was never tracked in the heap (written by a peer, or lost to a
+ * restart), `queued` records whose durable `availableAt` has elapsed but
+ * whose `scheduleDelayedDispatch` timer never fired (same causes), and
+ * (WFT-24) adopted `terminal` records old enough to reap under
+ * {@link ServeOptions.taskRetentionWindowMs}. `completing`, `cancelling`,
+ * and `deadLettered` are left untouched — resolving those is either the
+ * worker's redelivered result (`completing`) or explicitly out of this
+ * slice's scope.
+ */
 export declare function reconcileOrphanedRecords(context: ServerContext, options: ServeOptions, cleanupWorkflowIndex: (operationId: string) => void): Promise<void>;
 export {};