@lostgradient/weft 0.18.0 → 0.20.0

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

@@ -0,0 +1,162 @@
+import { calculateBackoff } from "../core/scheduler.js";
+import {
+  pickAttemptFields,
+  pickBase,
+  pickLeaseHolderFields
+} from "./task-ledger-transition-helpers.js";
+export {
+  canDeleteRetainedTerminalTask,
+  commitCancellation,
+  markWorkflowResultAdopted,
+  recordCancellationIntent
+} from "./task-ledger-transitions-cancellation.js";
+export function createQueued(current, input, now) {
+  if (current !== null)
+    return {
+      ok: !1,
+      reason: `operation "${input.operationId}" already has a task record in state "${current.state}"`
+    };
+  return { ok: !0, nextRecord: {
+    ...pickBase({ ...input, generation: 0 }),
+    state: "queued",
+    attempt: 1,
+    availableAt: input.availableAt ?? now,
+    firstQueuedAt: now,
+    lastQueuedAt: now,
+    retryCount: 0,
+    requeueCount: 0
+  } };
+}
+export function claimQueued(current, input, now) {
+  if (current === null || current.state !== "queued")
+    return { ok: !1, reason: 'expected task state "queued"' };
+  if (current.generation !== input.expectedGeneration)
+    return { ok: !1, reason: "generation mismatch" };
+  if (current.availableAt > now)
+    return { ok: !1, reason: "task is not yet available" };
+  return { ok: !0, nextRecord: {
+    ...pickBase(current),
+    ...pickAttemptFields(current),
+    generation: current.generation + 1,
+    state: "leased",
+    attemptToken: input.attemptToken,
+    workerSessionId: input.workerSessionId,
+    ...input.executionIdentity !== void 0 ? { executionIdentity: input.executionIdentity } : {},
+    attempt: current.attempt,
+    leaseDeadline: now + input.leaseDurationMilliseconds,
+    firstQueuedAt: current.firstQueuedAt,
+    lastQueuedAt: current.lastQueuedAt,
+    startedAt: current.startedAt ?? now,
+    lastHeartbeatAt: now
+  } };
+}
+export function renewAttemptLease(current, input, now) {
+  if (current === null || current.state !== "leased")
+    return { ok: !1, reason: 'expected task state "leased"' };
+  if (current.attemptToken !== input.attemptToken || current.workerSessionId !== input.workerSessionId)
+    return { ok: !1, reason: "attempt token or worker session mismatch" };
+  return { ok: !0, nextRecord: {
+    ...current,
+    generation: current.generation + 1,
+    leaseDeadline: now + input.leaseDurationMilliseconds,
+    lastHeartbeatAt: now
+  } };
+}
+export function beginCompletion(current, input) {
+  if (current === null || current.state !== "leased")
+    return { ok: !1, reason: 'expected task state "leased"' };
+  if (current.attemptToken !== input.attemptToken)
+    return { ok: !1, reason: "attempt token mismatch" };
+  return { ok: !0, nextRecord: {
+    ...pickBase(current),
+    ...pickAttemptFields(current),
+    ...pickLeaseHolderFields(current),
+    generation: current.generation + 1,
+    state: "completing",
+    pendingStatus: input.pendingStatus,
+    pendingResultDigest: input.pendingResultDigest
+  } };
+}
+export function commitTerminalResult(current, input, now) {
+  if (current === null || current.state !== "completing")
+    return { ok: !1, reason: 'expected task state "completing"' };
+  if (current.attemptToken !== input.attemptToken || current.pendingResultDigest !== input.resultDigest)
+    return { ok: !1, reason: "attempt token or result digest mismatch" };
+  return { ok: !0, nextRecord: {
+    ...pickBase(current),
+    generation: current.generation + 1,
+    state: "terminal",
+    disposition: "resolved",
+    attempt: current.attempt,
+    attemptToken: current.attemptToken,
+    status: current.pendingStatus,
+    ...input.error !== void 0 ? { error: input.error } : {},
+    resultDigest: current.pendingResultDigest,
+    terminalAt: now,
+    adopted: !1,
+    retentionGeneration: 0
+  } };
+}
+export function requeueExpiredAttempt(current, input, now) {
+  if (current === null || current.state !== "leased")
+    return { ok: !1, reason: 'expected task state "leased"' };
+  if (current.attemptToken !== input.attemptToken)
+    return { ok: !1, reason: "attempt token mismatch" };
+  if (input.skipDeadlineCheck !== !0 && current.leaseDeadline > now)
+    return { ok: !1, reason: "lease has not expired" };
+  const nextAttempt = current.attempt + 1, policy = current.retryPolicy;
+  if (policy !== void 0 && nextAttempt > policy.maxAttempts)
+    return { ok: !0, nextRecord: {
+      ...pickBase(current),
+      generation: current.generation + 1,
+      state: "terminal",
+      disposition: "retryExhausted",
+      attempt: current.attempt,
+      attemptToken: current.attemptToken,
+      error: `Activity "${current.activityName}" exhausted all ${String(policy.maxAttempts)} retry attempts`,
+      resultDigest: `retry-exhausted:${current.operationId}:${current.attemptToken}`,
+      terminalAt: now,
+      adopted: !1,
+      retentionGeneration: 0
+    } };
+  const availableAt = policy === void 0 ? now : now + calculateBackoff(nextAttempt - 1, policy);
+  return { ok: !0, nextRecord: {
+    ...pickBase(current),
+    generation: current.generation + 1,
+    state: "queued",
+    attempt: nextAttempt,
+    availableAt,
+    firstQueuedAt: current.firstQueuedAt,
+    lastQueuedAt: now,
+    lastDispatchedAt: current.lastQueuedAt,
+    startedAt: current.startedAt,
+    retryCount: Math.max(current.retryCount, nextAttempt - 1),
+    requeueCount: current.requeueCount + 1,
+    lastRequeueReason: input.requeueReason
+  } };
+}
+export function commitDeadLetter(current, input, now) {
+  if (current === null || current.state !== "completing")
+    return { ok: !1, reason: 'expected task state "completing"' };
+  if (current.attemptToken !== input.attemptToken || current.pendingResultDigest !== input.resultDigest)
+    return { ok: !1, reason: "attempt token or result digest mismatch" };
+  return { ok: !0, nextRecord: {
+    ...pickBase(current),
+    ...pickAttemptFields(current),
+    generation: current.generation + 1,
+    state: "deadLettered",
+    attemptToken: current.attemptToken,
+    attempt: current.attempt,
+    pendingStatus: current.pendingStatus,
+    pendingResultDigest: current.pendingResultDigest,
+    ...input.value !== void 0 ? { value: input.value } : {},
+    ...input.error !== void 0 ? { error: input.error } : {},
+    deadLetteredAt: now,
+    persistenceFailureReason: input.persistenceFailureReason
+  } };
+}
+export function canClearDeadLetteredTask(current) {
+  if (current === null || current.state !== "deadLettered")
+    return { ok: !1, reason: 'expected task state "deadLettered"' };
+  return { ok: !0 };
+}

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

@@ -0,0 +1,220 @@
+/**
+ * The canonical durable remote task ledger type union (WFT-25).
+ *
+ * Replaces the fragmented `op:queued:` / `op:inflight:` / `op:resolved:` /
+ * `op:dead-letter:` records in `task-state.ts` with one authoritative current
+ * state per operation. Every transition between these states proves the
+ * expected prior state and attempt identity through `storage.conditionalBatch`
+ * — see `task-ledger-transitions.ts` for the pure precondition functions that
+ * decide whether a transition is legal.
+ *
+ * This module defines the record shapes only. It does not read or write
+ * storage, and it is not wired into the live dispatch path — `TaskQueue`,
+ * `WorkerRegistry`, and the WebSocket/long-poll task handlers keep using
+ * `task-state.ts` until "Queue and Claim Coordinator" (WFT-22), the project
+ * slice that owns replacing that memory authority, lands.
+ *
+ * @module server/task-ledger-types
+ */
+import type { JSONValue } from '../core/json.ts';
+import type { RetryPolicy } from '../core/types.ts';
+import type { WorkerExecutionIdentity } from '../worker/manifest/types.ts';
+/**
+ * Fields common to every state a task record can occupy — the "complete
+ * dispatch envelope" the project brief requires to survive queueing, lease,
+ * retry, recovery, resolution, and dead letter.
+ *
+ * `workflowId` is optional, diverging from the project brief's literal
+ * `workflowId: string`. `TaskDispatch.workflowId` (`server/index.ts`) and
+ * every existing task record (`QueuedRecord`, `InflightRecord` in
+ * `task-state.ts`) already treat it as optional, and `serve-internals.ts`'s
+ * `rebuildWorkflowIndex` has a real, non-test code path that tolerates a
+ * restored in-flight record with no `workflowId`. Making it required here
+ * would silently break that existing, exercised behavior.
+ *
+ * `workflowExecutionToken` is optional for the same reason: the public
+ * `TaskDispatch.workflowExecutionToken` (`server/index.ts`) is already
+ * `string | undefined` for standalone remote-activity dispatch outside any
+ * durable workflow run, and every other declaration of this field in the
+ * codebase (`task-state.ts`, `task-queue-types.ts`, the core execution
+ * strategies) is optional too. Absence means "not workflow-bound" and must
+ * never be defaulted to an empty string — this field is documented
+ * elsewhere as an external write fence, so a shared `''` sentinel would let
+ * unrelated standalone tasks appear to hold the same fence.
+ */
+export type RemoteTaskBase = Readonly<{
+    recordVersion: 1;
+    operationId: string;
+    workflowId?: string;
+    workflowType: string;
+    workflowExecutionToken?: string;
+    activityName: string;
+    queue: string;
+    input: JSONValue;
+    headers: Readonly<Record<string, string>>;
+    priority?: number;
+    fairShareKey?: string;
+    /** Preferred worker-affinity routing hint, derived from `sticky ? workflowId : undefined` at dispatch time. */
+    stickyWorkflowId?: string;
+    visibilityTimeoutMilliseconds: number;
+    retryPolicy?: RetryPolicy;
+    scheduleToCloseDeadline?: number;
+    executionRequirement?: WorkerExecutionRequirementInput;
+    createdAt: number;
+    /** Monotonic counter incremented on every transition. Diagnostic/provenance surface — `conditionalBatch`'s whole-record byte equality is what actually enforces the CAS, but the precondition functions still check `generation` explicitly because it is the documented contract. */
+    generation: number;
+}>;
+/**
+ * Local alias for the manifest project's `WorkerExecutionRequirement` — kept
+ * as a named alias (rather than importing it directly into every downstream
+ * signature) so this module has one place documenting that the ledger reuses
+ * WFT-26's routing-input vocabulary rather than defining its own.
+ */
+export type WorkerExecutionRequirementInput = Readonly<{
+    deploymentName?: string;
+    buildId?: string;
+    artifactDigest?: string;
+    workflowRevision?: string;
+    activityContractHash?: string;
+}>;
+/**
+ * Retry/requeue provenance carried by every non-terminal state so it survives
+ * a lease → requeue → re-lease cycle intact — matching the existing
+ * `TaskLifecycleFields.retryCount` / `requeueCount` semantics in
+ * `task-state.ts` (`reassignOrExpireTask`'s `nextRetryCount` /
+ * `requeueCount + 1` computation), which this ledger's requeue transition
+ * reproduces.
+ */
+export type RemoteTaskAttemptFields = Readonly<{
+    retryCount: number;
+    requeueCount: number;
+    lastRequeueReason?: string;
+}>;
+export type RemoteTaskQueued = RemoteTaskBase & RemoteTaskAttemptFields & Readonly<{
+    state: 'queued';
+    attempt: number;
+    /** Delayed retries are represented here, not by a process timer — `Queued` includes work delayed until `availableAt`. */
+    availableAt: number;
+    firstQueuedAt: number;
+    lastQueuedAt: number;
+    lastDispatchedAt?: number;
+    /** First time any attempt of this operation began executing. Absent until the first claim; preserved across requeues. */
+    startedAt?: number;
+}>;
+export type RemoteTaskLeased = RemoteTaskBase & RemoteTaskAttemptFields & Readonly<{
+    state: 'leased';
+    attemptToken: string;
+    /**
+     * Identifies the live worker connection/session holding the lease,
+     * distinct from `executionIdentity.workerId` (the durable identity of
+     * the worker *process*). No durable session concept exists in the
+     * codebase today — `WorkerRegistry`'s grace-period reconnect logic
+     * deliberately preserves in-flight ownership across sockets under one
+     * `workerId`. This field exists so a later slice (WFT-22) can decide
+     * whether lease renewal survives reconnect; that policy is out of this
+     * slice's scope.
+     */
+    workerSessionId: string;
+    /**
+     * Complete observed identity of the worker holding the lease — see
+     * `WorkerExecutionIdentity` in `worker/manifest/types.ts`. Optional
+     * because `buildWorkerExecutionIdentity` returns `undefined` whenever the
+     * claiming worker has no registered manifest entry for this
+     * workflowType/activityName pair — which is the *only* case for every
+     * long-poll claim (long-poll workers never call `WorkerRegistry.register`,
+     * so they never have a manifest) and can also occur for a WebSocket
+     * worker whose manifest doesn't cover the dispatched activity. Absence
+     * here means "no verifiable provenance was available at claim time," not
+     * "provenance was skipped" — nothing fabricates a placeholder identity.
+     */
+    executionIdentity?: WorkerExecutionIdentity;
+    attempt: number;
+    leaseDeadline: number;
+    firstQueuedAt: number;
+    lastQueuedAt: number;
+    startedAt: number;
+    lastHeartbeatAt: number;
+}>;
+export type RemoteTaskCompleting = RemoteTaskBase & RemoteTaskAttemptFields & Readonly<{
+    state: 'completing';
+    attemptToken: string;
+    workerSessionId: string;
+    executionIdentity?: WorkerExecutionIdentity;
+    attempt: number;
+    leaseDeadline: number;
+    firstQueuedAt: number;
+    lastQueuedAt: number;
+    startedAt: number;
+    lastHeartbeatAt: number;
+    pendingStatus: 'completed' | 'failed';
+    /** Digest of the pending result, matched by "Commit terminal result" before it is applied. */
+    pendingResultDigest: string;
+}>;
+export type RemoteTaskCancelling = RemoteTaskBase & RemoteTaskAttemptFields & Readonly<{
+    state: 'cancelling';
+    /**
+     * Always present. Per the state diagram, `Cancelling` is reached only
+     * from `Leased` (`Leased --> Cancelling: cancellation intent`) — a
+     * cancellation recorded while a task is still `Queued` transitions
+     * directly to `Terminal` (disposition `cancelled`, no attempt ever
+     * existed) without passing through this state. The brief's transition
+     * table phrase "attempt token matches when one exists" describes that
+     * generic precondition-checking function across both origins; this
+     * type only represents the leased-origin case.
+     */
+    attemptToken: string;
+    workerSessionId: string;
+    executionIdentity?: WorkerExecutionIdentity;
+    attempt: number;
+    leaseDeadline: number;
+    firstQueuedAt: number;
+    lastQueuedAt: number;
+    startedAt: number;
+    lastHeartbeatAt: number;
+    cancellationReason: string;
+    cancellationRequestedAt: number;
+}>;
+/** Which lineage produced a terminal record. Every lineage carries `resultDigest` so "Mark workflow result adopted" can match uniformly regardless of disposition. */
+export type RemoteTaskTerminalDisposition = 'resolved' | 'cancelled' | 'retryExhausted';
+type RemoteTaskTerminalCommon = RemoteTaskBase & Readonly<{
+    state: 'terminal';
+    attempt: number;
+    resultDigest: string;
+    terminalAt: number;
+    adopted: boolean;
+    adoptedAt?: number;
+    /** Matched by "Delete retained terminal task"; incremented if a record is re-terminalized (e.g. adoption retried after a partial cleanup). */
+    retentionGeneration: number;
+}>;
+export type RemoteTaskTerminalResolved = RemoteTaskTerminalCommon & Readonly<{
+    disposition: 'resolved';
+    attemptToken: string;
+    status: 'completed' | 'failed';
+    error?: string;
+}>;
+export type RemoteTaskTerminalCancelled = RemoteTaskTerminalCommon & Readonly<{
+    disposition: 'cancelled';
+    /** Present when cancelled mid-attempt (via `Cancelling`); absent when cancelled directly from `Queued`. */
+    attemptToken?: string;
+    cancellationReason: string;
+}>;
+export type RemoteTaskTerminalRetryExhausted = RemoteTaskTerminalCommon & Readonly<{
+    disposition: 'retryExhausted';
+    attemptToken: string;
+    error: string;
+}>;
+export type RemoteTaskTerminal = RemoteTaskTerminalResolved | RemoteTaskTerminalCancelled | RemoteTaskTerminalRetryExhausted;
+export type RemoteTaskDeadLettered = RemoteTaskBase & RemoteTaskAttemptFields & Readonly<{
+    state: 'deadLettered';
+    attemptToken: string;
+    attempt: number;
+    pendingStatus: 'completed' | 'failed';
+    pendingResultDigest: string;
+    value?: JSONValue;
+    error?: string;
+    deadLetteredAt: number;
+    persistenceFailureReason: string;
+}>;
+export type RemoteTaskRecord = RemoteTaskQueued | RemoteTaskLeased | RemoteTaskCompleting | RemoteTaskCancelling | RemoteTaskTerminal | RemoteTaskDeadLettered;
+export declare const REMOTE_TASK_RECORD_VERSION = 1;
+export {};

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

@@ -0,0 +1 @@
+export const REMOTE_TASK_RECORD_VERSION = 1;

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

@@ -0,0 +1,17 @@
+/**
+ * Durable remote task ledger — public surface for this subsystem (WFT-25).
+ *
+ * Barrel re-exporting the record types, storage key, and codec split across
+ * `task-ledger-types.ts`, `task-ledger-limits.ts`, `task-ledger-keys.ts`, and
+ * `task-ledger-codec.ts` so callers (and `task-ledger.test.ts`, named by the
+ * project's verification gate) import from one module. Server-internal only
+ * — not re-exported from `src/index.ts`. See `task-ledger-transitions.ts`
+ * for the pure conditional-transition precondition functions.
+ *
+ * @module server/task-ledger
+ */
+export { decodeRemoteTaskRecord, encodeRemoteTaskRecord, isRemoteTaskCancelling, isRemoteTaskCompleting, isRemoteTaskDeadLettered, isRemoteTaskLeased, isRemoteTaskQueued, isRemoteTaskRecord, isRemoteTaskTerminal, isRemoteTaskTerminalCancelled, isRemoteTaskTerminalResolved, isRemoteTaskTerminalRetryExhausted, isValidTaskHeaders, } from './task-ledger-codec.ts';
+export { taskLedgerKey } from './task-ledger-keys.ts';
+export { MAX_TASK_HEADER_COUNT, MAX_TASK_HEADER_VALUE_BYTES, MAX_TASK_IDENTIFIER_BYTES, MAX_TASK_REASON_BYTES, utf8ByteLength, } from './task-ledger-limits.ts';
+export { REMOTE_TASK_RECORD_VERSION } from './task-ledger-types.ts';
+export type { RemoteTaskAttemptFields, RemoteTaskBase, RemoteTaskCancelling, RemoteTaskCompleting, RemoteTaskDeadLettered, RemoteTaskLeased, RemoteTaskQueued, RemoteTaskRecord, RemoteTaskTerminal, RemoteTaskTerminalCancelled, RemoteTaskTerminalDisposition, RemoteTaskTerminalResolved, RemoteTaskTerminalRetryExhausted, WorkerExecutionRequirementInput, } from './task-ledger-types.ts';

package/dist/server/task-ledger.js

@@ -0,0 +1,24 @@
+export {
+  decodeRemoteTaskRecord,
+  encodeRemoteTaskRecord,
+  isRemoteTaskCancelling,
+  isRemoteTaskCompleting,
+  isRemoteTaskDeadLettered,
+  isRemoteTaskLeased,
+  isRemoteTaskQueued,
+  isRemoteTaskRecord,
+  isRemoteTaskTerminal,
+  isRemoteTaskTerminalCancelled,
+  isRemoteTaskTerminalResolved,
+  isRemoteTaskTerminalRetryExhausted,
+  isValidTaskHeaders
+} from "./task-ledger-codec.js";
+export { taskLedgerKey } from "./task-ledger-keys.js";
+export {
+  MAX_TASK_HEADER_COUNT,
+  MAX_TASK_HEADER_VALUE_BYTES,
+  MAX_TASK_IDENTIFIER_BYTES,
+  MAX_TASK_REASON_BYTES,
+  utf8ByteLength
+} from "./task-ledger-limits.js";
+export { REMOTE_TASK_RECORD_VERSION } from "./task-ledger-types.js";

package/dist/server/task-state.d.ts

@@ -1,27 +1,21 @@
 /**
- * Task state tracking for the remote worker dispatch system.
+ * Lifecycle vocabulary and timing calculators shared by the durable task
+ * ledger and its diagnostics/metrics consumers.
  *
- * Every dispatched task exists in exactly one of three durable states:
- * - **queued**: Waiting in storage for a worker to claim it.
- * - **inflight**: Assigned to a worker with a visibility deadline.
- * - **resolved**: Completed or permanently failed.
- *
- * State transitions use `storage.batch()` to atomically delete the old
- * key and write the new key, preventing any window where a task is in
- * zero or two states simultaneously.
+ * The `op:queued:`/`op:inflight:`/`op:resolved:`/`op:dead-letter:` record
+ * shapes and type guards this module once exported alongside these
+ * calculators are gone: WFT-22 replaced the key scheme with the durable
+ * task ledger (`task-ledger.ts`), and WFT-24 migrated `get-task-diagnostics.ts`
+ * (the last production reader of those legacy shapes) onto the ledger.
+ * What remains is still load-bearing: `TaskLifecycleFields` and
+ * `TaskRequeueReason` back the ledger's own record types, and the
+ * queue-latency, execution-latency, and heartbeat-staleness calculators
+ * back `task-metrics.ts` and the ledger diagnostics.
  *
  * @module task-state
  */
-import type { RetryPolicy } from '../core/types.ts';
-import type { Storage } from '../storage/interface.ts';
-/** The three exclusive states a dispatched task can occupy. */
-export type TaskState = 'queued' | 'inflight' | 'resolved';
 /** Why a task was requeued before another dispatch attempt. */
 export type TaskRequeueReason = 'visibility-timeout' | 'worker-disconnect';
-/** Final reason captured when a task reaches the resolved state. */
-export type TaskResolutionReason = 'completed' | 'failed' | 'cancelled' | 'max-attempts-exceeded';
-/** Why a task-result transition was moved to the operator dead-letter guard. */
-export type TaskDeadLetterReason = 'result-resolution-storage-exhausted';
 /** Lifecycle evidence persisted with task records for diagnostics. */
 export interface TaskLifecycleFields {
     /** First time this operation entered a task queue. */
@@ -43,146 +37,25 @@ export interface TaskLifecycleFields {
     /** Most recent reason this task moved back to queued. */
     lastRequeueReason?: TaskRequeueReason | undefined;
 }
-/** Persisted record for a task in the queued state. */
-export interface QueuedRecord extends TaskLifecycleFields {
-    operationId: string;
-    activityName: string;
-    input: unknown;
-    queue: string;
-    attempt: number;
-    visibilityTimeout: number;
-    retryPolicy?: RetryPolicy | undefined;
-    queuedAt: number;
-    /** Workflow that dispatched this activity. Present when the dispatch included a workflowId. */
-    workflowId?: string | undefined;
-    /** Durable token for the workflow run that dispatched this activity, when known. */
-    workflowExecutionToken?: string | undefined;
-}
-/** Persisted record for a task in the inflight state. */
-export interface InflightRecord extends TaskLifecycleFields {
-    operationId: string;
-    workerId: string;
-    deadline: number;
-    activityName: string;
-    queue: string;
-    input: unknown;
-    attempt: number;
-    visibilityTimeout: number;
-    retryPolicy?: RetryPolicy | undefined;
-    /** Workflow that dispatched this activity. Present when the dispatch included a workflowId. */
-    workflowId?: string | undefined;
-    /** Durable token for the workflow run that dispatched this activity, when known. */
-    workflowExecutionToken?: string | undefined;
-    /** Unique, unguessable token identifying this dispatch attempt. */
-    attemptToken: string;
-}
-/** Persisted record for a task in the resolved state. */
-export interface ResolvedRecord {
-    operationId: string;
-    status: 'completed' | 'failed';
-    resolvedAt: number;
-    value?: unknown;
-    error?: string | undefined;
-    activityName?: string | undefined;
-    queue?: string | undefined;
-    workerId?: string | undefined;
-    attempt?: number | undefined;
-    visibilityTimeout?: number | undefined;
-    /** Workflow that dispatched this activity. Present when the dispatch included a workflowId. */
-    workflowId?: string | undefined;
-    firstQueuedAt?: number | undefined;
+/**
+ * The subset of {@link TaskLifecycleFields} the queue-latency, execution-latency,
+ * and heartbeat-staleness calculations actually read. Deliberately narrower
+ * than `TaskLifecycleFields` so these calculations also accept the durable
+ * remote task ledger's records (`RemoteTaskLeased`, `RemoteTaskQueued` —
+ * WFT-22), which carry the same timing fields but a free-text
+ * `lastRequeueReason` rather than the fixed {@link TaskRequeueReason} enum.
+ */
+export type TaskTimingFields = Readonly<{
     lastQueuedAt?: number | undefined;
     lastDispatchedAt?: number | undefined;
     startedAt?: number | undefined;
-    completedAt?: number | undefined;
     lastHeartbeatAt?: number | undefined;
-    retryCount?: number | undefined;
-    requeueCount?: number | undefined;
-    lastRequeueReason?: TaskRequeueReason | undefined;
-    resolutionReason?: TaskResolutionReason | undefined;
-    queueLatencyMs?: number | undefined;
-    executionLatencyMs?: number | undefined;
-}
-/** Durable operator guard for a task result whose resolved write exhausted retries. */
-export interface DeadLetteredTaskRecord {
-    operationId: string;
-    reason: TaskDeadLetterReason;
-    deadLetteredAt: number;
-    errorMessage: string;
-    retryAttempts: number;
-    status: 'completed' | 'failed';
-    activityName?: string | undefined;
-    queue?: string | undefined;
-    workerId?: string | undefined;
-    attempt?: number | undefined;
-    visibilityTimeout?: number | undefined;
-    workflowId?: string | undefined;
-    retryCount?: number | undefined;
-    requeueCount?: number | undefined;
-    lastRequeueReason?: TaskRequeueReason | undefined;
-}
-export interface TransitionInflightToResolvedOptions {
-    resolutionReason?: TaskResolutionReason;
-    resolvedAt?: number;
-    record?: InflightRecord;
-    value?: unknown;
-    error?: string | undefined;
-}
-/**
- * Look up the current durable state of a task.
- *
- * Returns the state name if the task is found in any of the three
- * states, or `null` if no record exists (the task was never dispatched
- * or its resolved record has been garbage-collected).
- */
-export declare function getTaskState(storage: Storage, operationId: string): Promise<TaskState | null>;
-/**
- * Return the task state and verify it occupies exactly one state.
- *
- * Throws if the task is found in multiple states simultaneously —
- * this indicates a bug in the state machine.
- */
-export declare function getExclusiveTaskState(storage: Storage, operationId: string): Promise<TaskState | null>;
-/** Type guard for decoded storage records in the queued state. */
-export declare function isQueuedRecord(value: unknown): value is QueuedRecord;
-/** Type guard for decoded storage records in the inflight state. */
-export declare function isInflightRecord(value: unknown): value is InflightRecord;
-/** Type guard for decoded storage records in the resolved state. */
-export declare function isResolvedRecord(value: unknown): value is ResolvedRecord;
-/** Type guard for decoded task-result dead-letter records. */
-export declare function isDeadLetteredTaskRecord(value: unknown): value is DeadLetteredTaskRecord;
-/** Decode the queued record for an operation, returning null when absent or malformed. */
-export declare function readQueuedRecord(storage: Storage, operationId: string): Promise<QueuedRecord | null>;
-/** Decode the inflight record for an operation, returning null when absent or malformed. */
-export declare function readInflightRecord(storage: Storage, operationId: string): Promise<InflightRecord | null>;
-/** Decode the task-result dead-letter record for an operation. */
-export declare function readDeadLetteredTaskRecord(storage: Storage, operationId: string): Promise<DeadLetteredTaskRecord | null>;
-/** True when reconciliation should not re-dispatch the operation. */
-export declare function isTaskDeadLettered(storage: Storage, operationId: string): Promise<boolean>;
-/** Persist a task-result dead-letter guard. */
-export declare function writeDeadLetteredTaskRecord(storage: Storage, record: DeadLetteredTaskRecord): Promise<void>;
-/** Clear a task-result dead-letter guard so reconciliation may handle the inflight record again. */
-export declare function clearDeadLetteredTaskRecord(storage: Storage, operationId: string): Promise<void>;
-export declare function calculateQueueLatencyMs(record: TaskLifecycleFields): number | undefined;
-export declare function calculateExecutionLatencyMs(record: TaskLifecycleFields, completedAt: number): number | undefined;
-export declare function calculateHeartbeatAgeMs(record: TaskLifecycleFields & {
+}>;
+export declare function calculateQueueLatencyMs(record: TaskTimingFields): number | undefined;
+export declare function calculateExecutionLatencyMs(record: TaskTimingFields, completedAt: number): number | undefined;
+export declare function calculateHeartbeatAgeMs(record: TaskTimingFields & {
     deadline?: number | undefined;
 }, currentTime: number): number | undefined;
-export declare function isHeartbeatStale(record: TaskLifecycleFields & {
+export declare function isHeartbeatStale(record: TaskTimingFields & {
     deadline?: number | undefined;
 }, currentTime: number, staleAfterMs: number): boolean;
-/** Write the initial queued record for a newly dispatched task. */
-export declare function markQueued(storage: Storage, record: QueuedRecord): Promise<QueuedRecord>;
-type TransitionQueuedToInflightOptions = {
-    readonly queuedRecord?: QueuedRecord | null;
-    readonly now?: number | undefined;
-};
-/** Atomically transition a task from queued → inflight. */
-export declare function transitionQueuedToInflight(storage: Storage, operationId: string, inflightRecord: InflightRecord, options?: TransitionQueuedToInflightOptions): Promise<InflightRecord>;
-/** Write the initial inflight record (for tasks dispatched directly to a WS worker). */
-export declare function markInflight(storage: Storage, record: InflightRecord): Promise<void>;
-/** Atomically transition a task from inflight → resolved. */
-export declare function transitionInflightToResolved(storage: Storage, operationId: string, status: 'completed' | 'failed', options?: TransitionInflightToResolvedOptions): Promise<void>;
-/** Atomically transition a task from inflight → queued (requeue on disconnect/timeout). */
-export declare function transitionInflightToQueued(storage: Storage, operationId: string, queuedRecord: QueuedRecord): Promise<void>;
-export {};