@lostgradient/weft 0.2.0

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

@@ -0,0 +1,95 @@
+import type { RetryPolicy } from '../core/types.ts';
+import type { TaskLifecycleFields } from './task-state.ts';
+/** A task waiting to be claimed by a long-poll worker. */
+export interface PendingTask extends TaskLifecycleFields {
+    operationId: string;
+    activityName: string;
+    input: unknown;
+    attempt?: number | undefined;
+    retryPolicy?: RetryPolicy | undefined;
+    visibilityTimeout?: number | undefined;
+    enqueuedAt?: number | undefined;
+    /** Propagated interceptor headers (e.g. W3C trace context, auth tokens). */
+    headers?: Record<string, string> | undefined;
+    /** Workflow that dispatched this activity. Present when the dispatch included a workflowId. */
+    workflowId?: string | undefined;
+    /**
+     * Task priority. Higher values are dequeued first. Tasks with equal priority
+     * maintain FIFO order. Default: 0. Agent workflow tasks use priority 10.
+     */
+    priority?: number | undefined;
+}
+/** Result reported by a long-poll worker after executing a task. */
+export interface TaskResult {
+    operationId: string;
+    status: 'completed' | 'failed';
+    value?: unknown;
+    error?: string | undefined;
+}
+/**
+ * Strategy used by `TaskQueue.enqueue` to place an incoming task in the
+ * per-queue pending list. In all strategies, `TaskQueue.poll` dequeues
+ * the first task whose activity matches the waiter — so the ordering imposed
+ * at enqueue time is what actually gets observed.
+ *
+ * - `'priority'` (default) inserts by descending `task.priority`. Tasks at the
+ *   same priority keep FIFO order. This is the historical behavior.
+ * - `'fifo'` ignores priority and appends to the end of the list. Oldest tasks
+ *   are dequeued first. Use this when fairness across producers matters more
+ *   than urgency.
+ * - `'lifo'` prepends to the start of the list. Newest tasks are dequeued
+ *   first. Use this for time-sensitive, short-lived work where fresh requests
+ *   are more valuable than stale ones (e.g. interactive UI refreshes).
+ *
+ *   **Starvation warning**: under sustained load, tasks at the bottom of the
+ *   LIFO stack may never be dequeued. They sit in the pending list while
+ *   newer arrivals jump in front of them, and when `TaskQueueOptions.pendingTaskTimeToLive`
+ *   is finite (the default is 5 minutes) they eventually expire and fail with
+ *   a generic timeout error — the producer gets no signal that LIFO ordering
+ *   was responsible. Only choose `'lifo'` for workloads where you actively
+ *   want bursty arrivals to displace older work, and consider setting
+ *   `pendingTaskTimeToLive` to `Infinity` (or aggressively low) to make the
+ *   trade-off explicit.
+ */
+export type SchedulingPolicy = 'priority' | 'fifo' | 'lifo';
+/**
+ * Per-queue snapshot reported by `TaskQueue.getQueueSummaries`.
+ * Wall-clock-free: `oldestEnqueuedAt` is the raw `enqueuedAt` of the oldest
+ * pending task (or `null` when the queue has no pending tasks). Age in
+ * milliseconds is derived by the caller against a single per-request `now`.
+ */
+export type TaskQueueSummary = {
+    /** Queue name. */
+    queue: string;
+    /** Pending (unclaimed) task count. */
+    backlog: number;
+    /**
+     * Epoch milliseconds when the oldest pending task was enqueued, or `null`
+     * when the queue has no pending tasks (or — defensively — when no pending
+     * task carries an `enqueuedAt`, which should not happen after enqueue
+     * defaults it).
+     */
+    oldestEnqueuedAt: number | null;
+    /** Active long-poll waiters parked on this queue. */
+    waitingPollers: number;
+    /** Scheduling policy in effect for the queue. */
+    schedulingPolicy: SchedulingPolicy;
+};
+/** Configuration options for `TaskQueue`. */
+export type TaskQueueOptions = {
+    /**
+     * Maximum time (in milliseconds) a task can sit in the pending queue before
+     * it expires. When a task expires its completion callback is invoked with a
+     * `'failed'` result carrying a timeout error, and all associated state is
+     * cleaned up. Set to `0` or `Infinity` to disable expiration.
+     *
+     * @default 300_000 (5 minutes)
+     */
+    pendingTaskTimeToLive?: number;
+    /**
+     * How tasks are ordered within a queue at enqueue time.
+     *
+     * @default 'priority'
+     */
+    schedulingPolicy?: SchedulingPolicy;
+};

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

@@ -0,0 +1,90 @@
+import type { TaskQueueSnapshot } from './task-queue-summary.ts';
+import type { PendingTask, SchedulingPolicy, TaskQueueOptions, TaskQueueSummary, TaskResult } from './task-queue-types.ts';
+/** Callback invoked when a task completes, fails, or expires. Implementation-private. */
+type CompletionCallback = (result: TaskResult) => void;
+/**
+ * Reset the one-shot LIFO starvation warning. Test-only: production code
+ * should never need to call this.
+ */
+export declare function resetLifoStarvationWarningForTesting(): void;
+/**
+ * Manages pending tasks and waiting long-poll requests. When a task is
+ * enqueued and a matching waiter exists, the task is dispatched immediately.
+ * When a poll request arrives and no task is available, the request blocks
+ * until a task arrives or the timeout expires.
+ *
+ * `serve()` owns the live instance and exposes it as
+ * {@link WeftServer.taskQueue} for inspection. Prefer the `WeftServer` methods
+ * (`dispatchTask`, `shutdownWorker`, etc.) over mutating the queue directly —
+ * the type is re-exported so callers can name `server.taskQueue`, not as a
+ * stable mutation surface.
+ *
+ * @example
+ * ```ts
+ * import { serve, type TaskQueue } from '@lostgradient/weft/server';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * await using server = serve({ engine });
+ *
+ * const taskQueue: TaskQueue = server.taskQueue;
+ * void taskQueue;
+ * ```
+ */
+export declare class TaskQueue implements Disposable {
+    #private;
+    constructor(options?: TaskQueueOptions);
+    /** The scheduling policy this queue was configured with. */
+    get schedulingPolicy(): SchedulingPolicy;
+    /**
+     * Enqueue a task. If a matching waiter exists, dispatch immediately.
+     * Returns true if the task was dispatched to a waiter or queued.
+     */
+    enqueue(queue: string, task: PendingTask, onComplete?: CompletionCallback): boolean;
+    /**
+     * Long-poll for a task. Returns immediately if a matching task is queued,
+     * otherwise blocks until a task arrives or `timeout` milliseconds elapse.
+     */
+    poll(queue: string, activities: string[], timeout: number, signal?: AbortSignal): Promise<PendingTask | null>;
+    /**
+     * Report a task completion. Invokes the completion callback registered
+     * during enqueue (if any). Returns true if a callback was found.
+     */
+    complete(result: TaskResult): boolean;
+    /**
+     * Release all queue state on shutdown. Resolves every parked long-poll
+     * waiter with `null` (so no poll promise is left unsettled), clears every
+     * pending-task expiration timer, and drops all pending tasks, completion
+     * callbacks, and dispatch tracking.
+     *
+     * Completion callbacks are intentionally NOT invoked: this is teardown, not
+     * per-task expiration, and firing failure callbacks would push work into an
+     * already-disposed engine/storage. Idempotent — safe to call more than once.
+     */
+    [Symbol.dispose](): void;
+    /** Check whether an operationId is currently tracked (pending or dispatched). */
+    isTracked(operationId: string): boolean;
+    /** Check if any waiter in the queue can handle the given activity. */
+    hasWaiter(queue: string, activityName: string): boolean;
+    /** Number of pending (unclaimed) tasks in a queue. */
+    pendingCount(queue: string): number;
+    /** Total number of pending tasks across every queue. */
+    totalPendingCount(): number;
+    /** Peek the ordered pending tasks for a queue without dequeuing. Test helper. */
+    peekPending(queue: string): PendingTask[];
+    /**
+     * Synchronously reads internal state into a plain snapshot object for use by
+     * {@link buildQueueSummaries}. Single-turn event-loop reads are consistent
+     * without explicit locking.
+     */
+    captureSnapshot(): TaskQueueSnapshot;
+    /**
+     * Per-queue summary used by `weft.task.queues.list`. Returns one entry per
+     * queue appearing in `#pending` or `#waiters`, sorted ascending by name.
+     * See {@link buildQueueSummaries} for field semantics.
+     */
+    getQueueSummaries(): TaskQueueSummary[];
+    /** Remove and return pending tasks older than `maxAge` milliseconds. */
+    removeStale(maxAge: number): PendingTask[];
+}
+export {};

package/dist/server/task-queue.js

@@ -0,0 +1,247 @@
+import { buildQueueSummaries } from "./task-queue-summary.js";
+const DEFAULT_PENDING_TASK_TTL = 300000;
+let lifoStarvationWarningEmitted = !1;
+export function resetLifoStarvationWarningForTesting() {
+  lifoStarvationWarningEmitted = !1;
+}
+
+export class TaskQueue {
+  #pending = new Map;
+  #waiters = new Map;
+  #completionCallbacks = new Map;
+  #dispatched = new Set;
+  #expirationTimers = new Map;
+  #pendingTaskTimeToLive;
+  #schedulingPolicy;
+  constructor(options) {
+    const ttl = options?.pendingTaskTimeToLive ?? DEFAULT_PENDING_TASK_TTL;
+    this.#pendingTaskTimeToLive = ttl;
+    this.#schedulingPolicy = options?.schedulingPolicy ?? "priority";
+    if (this.#schedulingPolicy === "lifo" && this.#pendingTaskTimeToLive > 0 && Number.isFinite(this.#pendingTaskTimeToLive) && !lifoStarvationWarningEmitted) {
+      lifoStarvationWarningEmitted = !0;
+      console.warn(`[weft] TaskQueue configured with schedulingPolicy='lifo' and a finite pendingTaskTimeToLive (${this.#pendingTaskTimeToLive}ms). Under sustained load, tasks at the bottom of the LIFO stack can sit unclaimed until they expire and fail with a generic timeout error. Set pendingTaskTimeToLive to Infinity to disable expiration, or use 'fifo'/'priority' if fairness matters.`);
+    }
+  }
+  get schedulingPolicy() {
+    return this.#schedulingPolicy;
+  }
+  enqueue(queue, task, onComplete) {
+    if (this.#dispatched.has(task.operationId))
+      return !1;
+    this.#dispatched.add(task.operationId);
+    task.enqueuedAt ??= Date.now();
+    if (onComplete)
+      this.#completionCallbacks.set(task.operationId, onComplete);
+    const waiters = this.#waiters.get(queue);
+    if (waiters && waiters.length > 0) {
+      const index = waiters.findIndex((w) => w.activities.includes(task.activityName));
+      if (index !== -1) {
+        const waiter = waiters[index];
+        clearTimeout(waiter.timer);
+        waiters.splice(index, 1);
+        if (waiters.length === 0)
+          this.#waiters.delete(queue);
+        waiter.resolve(task);
+        return !0;
+      }
+    }
+    const tasks = this.#pending.get(queue) ?? [];
+    insertByPolicy(tasks, task, this.#schedulingPolicy);
+    this.#pending.set(queue, tasks);
+    this.#scheduleExpiration(queue, task.operationId);
+    return !0;
+  }
+  poll(queue, activities, timeout, signal) {
+    if (signal?.aborted)
+      return Promise.resolve(null);
+    const tasks = this.#pending.get(queue);
+    if (tasks) {
+      const index = tasks.findIndex((t) => activities.includes(t.activityName));
+      if (index !== -1) {
+        const task = tasks.splice(index, 1)[0];
+        if (tasks.length === 0)
+          this.#pending.delete(queue);
+        this.#cancelExpiration(task.operationId);
+        return Promise.resolve(task);
+      }
+    }
+    return new Promise((_resolve) => {
+      let settled = !1;
+      const resolve = (value) => {
+        if (settled)
+          return;
+        settled = !0;
+        _resolve(value);
+      }, waiters = this.#waiters.get(queue) ?? [];
+      this.#waiters.set(queue, waiters);
+      const cleanup = () => {
+        const idx = waiters.indexOf(waiter);
+        if (idx !== -1)
+          waiters.splice(idx, 1);
+        if (waiters.length === 0)
+          this.#waiters.delete(queue);
+      }, settle = (value) => {
+        clearTimeout(timer);
+        if (signal)
+          signal.removeEventListener("abort", onAbort);
+        cleanup();
+        resolve(value);
+      }, onAbort = () => settle(null), timer = setTimeout(() => settle(null), timeout), waiter = {
+        activities,
+        resolve: settle,
+        timer
+      };
+      waiters.push(waiter);
+      if (signal)
+        signal.addEventListener("abort", onAbort, { once: !0 });
+    });
+  }
+  complete(result) {
+    this.#cancelExpiration(result.operationId);
+    this.#dispatched.delete(result.operationId);
+    const callback = this.#completionCallbacks.get(result.operationId);
+    if (callback) {
+      this.#completionCallbacks.delete(result.operationId);
+      callback(result);
+      return !0;
+    }
+    return !1;
+  }
+  [Symbol.dispose]() {
+    for (const timer of this.#expirationTimers.values())
+      clearTimeout(timer);
+    this.#expirationTimers.clear();
+    const parked = [];
+    for (const waiters of this.#waiters.values())
+      parked.push(...waiters);
+    this.#waiters.clear();
+    for (const waiter of parked) {
+      clearTimeout(waiter.timer);
+      waiter.resolve(null);
+    }
+    this.#pending.clear();
+    this.#completionCallbacks.clear();
+    this.#dispatched.clear();
+  }
+  isTracked(operationId) {
+    return this.#dispatched.has(operationId);
+  }
+  hasWaiter(queue, activityName) {
+    const waiters = this.#waiters.get(queue);
+    if (!waiters)
+      return !1;
+    return waiters.some((w) => w.activities.includes(activityName));
+  }
+  pendingCount(queue) {
+    return this.#pending.get(queue)?.length ?? 0;
+  }
+  totalPendingCount() {
+    let count = 0;
+    for (const tasks of this.#pending.values())
+      count += tasks.length;
+    return count;
+  }
+  #scheduleExpiration(queue, operationId) {
+    const ttl = this.#pendingTaskTimeToLive;
+    if (ttl <= 0 || !Number.isFinite(ttl))
+      return;
+    const timer = setTimeout(() => this.#expireTask(queue, operationId), ttl);
+    this.#expirationTimers.set(operationId, timer);
+  }
+  #cancelExpiration(operationId) {
+    const timer = this.#expirationTimers.get(operationId);
+    if (timer !== void 0) {
+      clearTimeout(timer);
+      this.#expirationTimers.delete(operationId);
+    }
+  }
+  #expireTask(queue, operationId) {
+    this.#expirationTimers.delete(operationId);
+    const tasks = this.#pending.get(queue);
+    if (tasks) {
+      const index = tasks.findIndex((t) => t.operationId === operationId);
+      if (index !== -1) {
+        tasks.splice(index, 1);
+        if (tasks.length === 0)
+          this.#pending.delete(queue);
+      }
+    }
+    this.#dispatched.delete(operationId);
+    const callback = this.#completionCallbacks.get(operationId);
+    if (callback) {
+      this.#completionCallbacks.delete(operationId);
+      callback({
+        operationId,
+        status: "failed",
+        error: `Task expired after ${this.#pendingTaskTimeToLive}ms without being claimed by a worker`
+      });
+    }
+  }
+  peekPending(queue) {
+    return [...this.#pending.get(queue) ?? []];
+  }
+  captureSnapshot() {
+    return {
+      pending: new Map([...this.#pending.entries()].map(([q, tasks]) => [
+        q,
+        tasks.map((t) => ({ enqueuedAt: t.enqueuedAt }))
+      ])),
+      waiters: new Map([...this.#waiters.entries()].map(([q, ws]) => [q, ws.slice()])),
+      schedulingPolicy: this.#schedulingPolicy
+    };
+  }
+  getQueueSummaries() {
+    return buildQueueSummaries(this.captureSnapshot());
+  }
+  removeStale(maxAge) {
+    if (!Number.isFinite(maxAge) || maxAge < 0)
+      throw RangeError(`maxAge must be a finite, non-negative number, got: ${maxAge}`);
+    const cutoff = Date.now() - maxAge, stale = [];
+    for (const [queue, tasks] of this.#pending) {
+      const remaining = [];
+      for (const task of tasks)
+        if ((task.enqueuedAt ?? 0) < cutoff) {
+          stale.push(task);
+          this.#cancelExpiration(task.operationId);
+          this.#dispatched.delete(task.operationId);
+          const callback = this.#completionCallbacks.get(task.operationId);
+          if (callback) {
+            this.#completionCallbacks.delete(task.operationId);
+            callback({
+              operationId: task.operationId,
+              status: "failed",
+              error: `Task expired after ${maxAge}ms without being claimed`
+            });
+          }
+        } else
+          remaining.push(task);
+      if (remaining.length === 0)
+        this.#pending.delete(queue);
+      else
+        this.#pending.set(queue, remaining);
+    }
+    return stale;
+  }
+}
+function insertByPolicy(tasks, task, policy) {
+  if (tasks.length === 0) {
+    tasks.push(task);
+    return;
+  }
+  switch (policy) {
+    case "fifo":
+      tasks.push(task);
+      return;
+    case "lifo":
+      tasks.unshift(task);
+      return;
+    case "priority": {
+      const taskPriority = task.priority ?? 0, insertAt = tasks.findIndex((existing) => (existing.priority ?? 0) < taskPriority);
+      if (insertAt === -1)
+        tasks.push(task);
+      else
+        tasks.splice(insertAt, 0, task);
+      return;
+    }
+  }
+}

package/dist/server/task-resolved-record.d.ts

@@ -0,0 +1,12 @@
+import type { InflightRecord, ResolvedRecord, TaskResolutionReason } from './task-state.ts';
+export declare function buildResolvedRecord(parameters: {
+    operationId: string;
+    status: 'completed' | 'failed';
+    resolvedAt: number;
+    normalizedRecord: InflightRecord | null;
+    resolutionReason: TaskResolutionReason;
+    value?: unknown;
+    error?: string | undefined;
+    queueLatencyMs?: number | undefined;
+    executionLatencyMs?: number | undefined;
+}): ResolvedRecord;

package/dist/server/task-resolved-record.js

@@ -0,0 +1,35 @@
+export function buildResolvedRecord(parameters) {
+  const resolvedRecord = {
+    operationId: parameters.operationId,
+    status: parameters.status,
+    resolvedAt: parameters.resolvedAt
+  };
+  if (parameters.value !== void 0)
+    resolvedRecord.value = parameters.value;
+  if (parameters.error !== void 0)
+    resolvedRecord.error = parameters.error;
+  const { normalizedRecord } = parameters;
+  if (normalizedRecord === null)
+    return resolvedRecord;
+  return {
+    ...resolvedRecord,
+    activityName: normalizedRecord.activityName,
+    queue: normalizedRecord.queue,
+    workerId: normalizedRecord.workerId,
+    attempt: normalizedRecord.attempt,
+    visibilityTimeout: normalizedRecord.visibilityTimeout,
+    ...normalizedRecord.workflowId === void 0 ? {} : { workflowId: normalizedRecord.workflowId },
+    firstQueuedAt: normalizedRecord.firstQueuedAt,
+    lastQueuedAt: normalizedRecord.lastQueuedAt,
+    lastDispatchedAt: normalizedRecord.lastDispatchedAt,
+    startedAt: normalizedRecord.startedAt,
+    completedAt: parameters.resolvedAt,
+    lastHeartbeatAt: normalizedRecord.lastHeartbeatAt,
+    retryCount: normalizedRecord.retryCount,
+    requeueCount: normalizedRecord.requeueCount,
+    lastRequeueReason: normalizedRecord.lastRequeueReason,
+    resolutionReason: parameters.resolutionReason,
+    queueLatencyMs: parameters.queueLatencyMs,
+    executionLatencyMs: parameters.executionLatencyMs
+  };
+}

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

@@ -0,0 +1,152 @@
+/**
+ * Task state tracking for the remote worker dispatch system.
+ *
+ * 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.
+ *
+ * @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';
+/** Lifecycle evidence persisted with task records for diagnostics. */
+export interface TaskLifecycleFields {
+    /** First time this operation entered a task queue. */
+    firstQueuedAt?: number | undefined;
+    /** Most recent time this operation entered a task queue. */
+    lastQueuedAt?: number | undefined;
+    /** Most recent time this operation was dispatched to a worker. */
+    lastDispatchedAt?: number | undefined;
+    /** Time this operation started executing on a worker when knowable. */
+    startedAt?: number | undefined;
+    /** Time this operation reached a terminal task state. */
+    completedAt?: number | undefined;
+    /** Most recent worker heartbeat observed for this operation. */
+    lastHeartbeatAt?: number | undefined;
+    /** Number of retry attempts after the original attempt. */
+    retryCount?: number | undefined;
+    /** Number of times visibility/disconnect handling moved this task back to queued. */
+    requeueCount?: number | undefined;
+    /** 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;
+}
+/** 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;
+}
+/** 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;
+    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;
+}
+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;
+/** 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>;
+export declare function calculateQueueLatencyMs(record: TaskLifecycleFields): number | undefined;
+export declare function calculateExecutionLatencyMs(record: TaskLifecycleFields, completedAt: number): number | undefined;
+export declare function calculateHeartbeatAgeMs(record: TaskLifecycleFields & {
+    deadline?: number | undefined;
+}, currentTime: number): number | undefined;
+export declare function isHeartbeatStale(record: TaskLifecycleFields & {
+    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 {};