@zucker-framework/task 1.0.0 → 1.0.5

package/README.md

@@ -0,0 +1,11 @@
+# Single-process supervisor
+
+`SingleProcessTaskSupervisor` receives `initialize`, `loadPending`, `run`, `abort`, concurrency and scan interval. It deduplicates pending/running keys and marks startup or manually submitted recovery keys for `run(id, true)`. Register the configured instance once at the composition root. Initialization and scanning failures preserve their separate failure paths; shutdown clears queued work and aborts running work without a drain wait.
+
+The consumer owns persistent states, startup state transitions, retry eligibility, progress, billing and checkpoints. This primitive has no database schema, lease, fencing or multi-executor guarantee. It must not be used to justify overlapping executors.
+
+## Execution heartbeat
+
+`runWithExecutionHeartbeat({ signal, heartbeat, intervalMs, failureThreshold }, work)` scopes serial heartbeat attempts to one callback. A successful heartbeat resets the consecutive failure count. At the configured threshold the work signal aborts with `ExecutionHeartbeatError`; the parent signal is unaffected, and the failure remains an error even when work swallows its abort. Caller cancellation forwards its original reason. Work must honor cancellation; the scope does not detach or duplicate it.
+
+The scope clears its timer/listener and awaits an already-running heartbeat before returning. The consumer owns all database writes and decides how heartbeat failure differs from user cancellation or process shutdown. No state table, lease, retry, worker or execution topology is introduced.

package/dist/index.d.mts

@@ -601,4 +601,58 @@ declare class TaskOutboxDispatcher<TPayload = unknown> {
     runOnce(): Promise<TaskOutboxDispatchResult>;
 }
 
-export { type AppendTaskOutboxInput, type ClaimTaskInput, type ClaimTaskOutboxInput, type CreateTaskInput, type CreateTaskResult, type DurableTaskAttemptContext, type DurableTaskHandler, DurableTaskLeaseLostError, DurableTaskNotClaimableError, DurableTaskNotFoundError, DurableTaskRetryScheduledError, type DurableWorkerHeartbeatScheduler, type DurableWorkerRunResult, DurableWorkerRuntime, type DurableWorkerRuntimeLogger, type DurableWorkerRuntimeOptions, ExponentialTaskRetryPolicy, type ExponentialTaskRetryPolicyOptions, type FindExpiredTaskLeasesInput, type FindReadyQueuedTasksInput, type HeartbeatTaskInput, InMemoryTaskOutboxRepository, InMemoryTaskRepository, InvalidTaskTransitionError, type ListOwnedTaskSummariesInput, type OwnedTaskTimelineEvent, type PostgresQueryResult, type PostgresTaskClient, PostgresTaskOutboxRepository, PostgresTaskRedriver, PostgresTaskRepository, PostgresTaskSubmitter, PostgresTaskSummaryReader, PostgresTaskTimelineReader, type PostgresTaskTransactionRunner, type ReadyTaskPublisher, type RecoverExpiredTaskLeaseInput, type RedriveFailedTaskInput, type ReportTaskProgressInput, type SubmitTaskBatchOptions, type SubmitTaskInput, type SubmitTaskOptions, type SubmitTaskOutboxInput, type SubmitTaskResult, TASK_STATUSES, TASK_TIMELINE_EVENT_TYPES, type TaskErrorSummary, type TaskFailureCategory, TaskIdempotencyConflictError, type TaskLeaseReconcileResult, TaskLeaseReconciler, type TaskLeaseReconcilerOptions, TaskOutboxConflictError, type TaskOutboxDispatchResult, TaskOutboxDispatcher, type TaskOutboxDispatcherOptions, type TaskOutboxRecord, type TaskOutboxRepository, type TaskOutboxStatus, type TaskQueuePublisher, type TaskQueueReconcileResult, TaskQueueReconciler, type TaskQueueReconcilerOptions, type TaskRecord, type TaskRedriveResult, type TaskRepository, type TaskResourceRef, type TaskRetryContext, type TaskRetryDecision, type TaskRetryPolicy, type TaskStatus, type TaskSummary, type TaskSummaryError, type TaskTimelineEvent, type TaskTimelineEventType, type TransitionTaskInput, UnsupportedDurableTaskKindError, assertTaskTransition, canTransitionTask, createTaskFingerprint, isTerminalTaskStatus, requiresTaskLease };
+interface SingleProcessTaskSupervisorOptions {
+    concurrency: number;
+    scanIntervalMs: number;
+    /** Perform consumer-owned startup recovery and return keys that require resumption. */
+    initialize?: () => Promise<readonly string[]>;
+    loadPending: () => Promise<readonly string[]>;
+    run: (id: string, recovery: boolean) => Promise<void>;
+    abort: (id: string) => void;
+    onScanError?: (error: unknown) => void;
+    onExecutionError?: (id: string, error: unknown) => void | Promise<void>;
+}
+/**
+ * One-process FIFO scheduling, deduplication and recovery polling. Persistent
+ * state belongs to the consumer. This provides no lease, fencing or multi-executor safety.
+ * Shutdown aborts active callbacks immediately and deliberately does not drain them.
+ */
+declare class SingleProcessTaskSupervisor {
+    private readonly options;
+    private readonly queued;
+    private readonly running;
+    private readonly interrupted;
+    private queue;
+    private scanTimer?;
+    private stopped;
+    private started;
+    constructor(options: SingleProcessTaskSupervisorOptions);
+    onApplicationBootstrap(): Promise<void>;
+    submit(id: string): void;
+    submitRecovery(id: string): void;
+    waitForIdle(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+    private drain;
+    private scanPending;
+    private scheduleScan;
+}
+
+declare class ExecutionHeartbeatError extends Error {
+    readonly consecutiveFailures: number;
+    constructor(consecutiveFailures: number, options?: ErrorOptions);
+}
+interface ExecutionHeartbeatOptions {
+    signal?: AbortSignal;
+    intervalMs: number;
+    failureThreshold: number;
+    heartbeat: () => Promise<void>;
+}
+/**
+ * A single execution's heartbeat and cancellation scope. No lease, persistent
+ * state transition or retry policy is implied. Heartbeats never overlap; the
+ * final in-flight heartbeat settles before this scope returns. Work must honor
+ * its signal, and a heartbeat abort cannot be reported as successful work.
+ */
+declare function runWithExecutionHeartbeat<T>(options: ExecutionHeartbeatOptions, work: (signal: AbortSignal) => Promise<T>): Promise<T>;
+
+export { type AppendTaskOutboxInput, type ClaimTaskInput, type ClaimTaskOutboxInput, type CreateTaskInput, type CreateTaskResult, type DurableTaskAttemptContext, type DurableTaskHandler, DurableTaskLeaseLostError, DurableTaskNotClaimableError, DurableTaskNotFoundError, DurableTaskRetryScheduledError, type DurableWorkerHeartbeatScheduler, type DurableWorkerRunResult, DurableWorkerRuntime, type DurableWorkerRuntimeLogger, type DurableWorkerRuntimeOptions, ExecutionHeartbeatError, type ExecutionHeartbeatOptions, ExponentialTaskRetryPolicy, type ExponentialTaskRetryPolicyOptions, type FindExpiredTaskLeasesInput, type FindReadyQueuedTasksInput, type HeartbeatTaskInput, InMemoryTaskOutboxRepository, InMemoryTaskRepository, InvalidTaskTransitionError, type ListOwnedTaskSummariesInput, type OwnedTaskTimelineEvent, type PostgresQueryResult, type PostgresTaskClient, PostgresTaskOutboxRepository, PostgresTaskRedriver, PostgresTaskRepository, PostgresTaskSubmitter, PostgresTaskSummaryReader, PostgresTaskTimelineReader, type PostgresTaskTransactionRunner, type ReadyTaskPublisher, type RecoverExpiredTaskLeaseInput, type RedriveFailedTaskInput, type ReportTaskProgressInput, SingleProcessTaskSupervisor, type SingleProcessTaskSupervisorOptions, type SubmitTaskBatchOptions, type SubmitTaskInput, type SubmitTaskOptions, type SubmitTaskOutboxInput, type SubmitTaskResult, TASK_STATUSES, TASK_TIMELINE_EVENT_TYPES, type TaskErrorSummary, type TaskFailureCategory, TaskIdempotencyConflictError, type TaskLeaseReconcileResult, TaskLeaseReconciler, type TaskLeaseReconcilerOptions, TaskOutboxConflictError, type TaskOutboxDispatchResult, TaskOutboxDispatcher, type TaskOutboxDispatcherOptions, type TaskOutboxRecord, type TaskOutboxRepository, type TaskOutboxStatus, type TaskQueuePublisher, type TaskQueueReconcileResult, TaskQueueReconciler, type TaskQueueReconcilerOptions, type TaskRecord, type TaskRedriveResult, type TaskRepository, type TaskResourceRef, type TaskRetryContext, type TaskRetryDecision, type TaskRetryPolicy, type TaskStatus, type TaskSummary, type TaskSummaryError, type TaskTimelineEvent, type TaskTimelineEventType, type TransitionTaskInput, UnsupportedDurableTaskKindError, assertTaskTransition, canTransitionTask, createTaskFingerprint, isTerminalTaskStatus, requiresTaskLease, runWithExecutionHeartbeat };

package/dist/index.d.ts

@@ -601,4 +601,58 @@ declare class TaskOutboxDispatcher<TPayload = unknown> {
     runOnce(): Promise<TaskOutboxDispatchResult>;
 }
 
-export { type AppendTaskOutboxInput, type ClaimTaskInput, type ClaimTaskOutboxInput, type CreateTaskInput, type CreateTaskResult, type DurableTaskAttemptContext, type DurableTaskHandler, DurableTaskLeaseLostError, DurableTaskNotClaimableError, DurableTaskNotFoundError, DurableTaskRetryScheduledError, type DurableWorkerHeartbeatScheduler, type DurableWorkerRunResult, DurableWorkerRuntime, type DurableWorkerRuntimeLogger, type DurableWorkerRuntimeOptions, ExponentialTaskRetryPolicy, type ExponentialTaskRetryPolicyOptions, type FindExpiredTaskLeasesInput, type FindReadyQueuedTasksInput, type HeartbeatTaskInput, InMemoryTaskOutboxRepository, InMemoryTaskRepository, InvalidTaskTransitionError, type ListOwnedTaskSummariesInput, type OwnedTaskTimelineEvent, type PostgresQueryResult, type PostgresTaskClient, PostgresTaskOutboxRepository, PostgresTaskRedriver, PostgresTaskRepository, PostgresTaskSubmitter, PostgresTaskSummaryReader, PostgresTaskTimelineReader, type PostgresTaskTransactionRunner, type ReadyTaskPublisher, type RecoverExpiredTaskLeaseInput, type RedriveFailedTaskInput, type ReportTaskProgressInput, type SubmitTaskBatchOptions, type SubmitTaskInput, type SubmitTaskOptions, type SubmitTaskOutboxInput, type SubmitTaskResult, TASK_STATUSES, TASK_TIMELINE_EVENT_TYPES, type TaskErrorSummary, type TaskFailureCategory, TaskIdempotencyConflictError, type TaskLeaseReconcileResult, TaskLeaseReconciler, type TaskLeaseReconcilerOptions, TaskOutboxConflictError, type TaskOutboxDispatchResult, TaskOutboxDispatcher, type TaskOutboxDispatcherOptions, type TaskOutboxRecord, type TaskOutboxRepository, type TaskOutboxStatus, type TaskQueuePublisher, type TaskQueueReconcileResult, TaskQueueReconciler, type TaskQueueReconcilerOptions, type TaskRecord, type TaskRedriveResult, type TaskRepository, type TaskResourceRef, type TaskRetryContext, type TaskRetryDecision, type TaskRetryPolicy, type TaskStatus, type TaskSummary, type TaskSummaryError, type TaskTimelineEvent, type TaskTimelineEventType, type TransitionTaskInput, UnsupportedDurableTaskKindError, assertTaskTransition, canTransitionTask, createTaskFingerprint, isTerminalTaskStatus, requiresTaskLease };
+interface SingleProcessTaskSupervisorOptions {
+    concurrency: number;
+    scanIntervalMs: number;
+    /** Perform consumer-owned startup recovery and return keys that require resumption. */
+    initialize?: () => Promise<readonly string[]>;
+    loadPending: () => Promise<readonly string[]>;
+    run: (id: string, recovery: boolean) => Promise<void>;
+    abort: (id: string) => void;
+    onScanError?: (error: unknown) => void;
+    onExecutionError?: (id: string, error: unknown) => void | Promise<void>;
+}
+/**
+ * One-process FIFO scheduling, deduplication and recovery polling. Persistent
+ * state belongs to the consumer. This provides no lease, fencing or multi-executor safety.
+ * Shutdown aborts active callbacks immediately and deliberately does not drain them.
+ */
+declare class SingleProcessTaskSupervisor {
+    private readonly options;
+    private readonly queued;
+    private readonly running;
+    private readonly interrupted;
+    private queue;
+    private scanTimer?;
+    private stopped;
+    private started;
+    constructor(options: SingleProcessTaskSupervisorOptions);
+    onApplicationBootstrap(): Promise<void>;
+    submit(id: string): void;
+    submitRecovery(id: string): void;
+    waitForIdle(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+    private drain;
+    private scanPending;
+    private scheduleScan;
+}
+
+declare class ExecutionHeartbeatError extends Error {
+    readonly consecutiveFailures: number;
+    constructor(consecutiveFailures: number, options?: ErrorOptions);
+}
+interface ExecutionHeartbeatOptions {
+    signal?: AbortSignal;
+    intervalMs: number;
+    failureThreshold: number;
+    heartbeat: () => Promise<void>;
+}
+/**
+ * A single execution's heartbeat and cancellation scope. No lease, persistent
+ * state transition or retry policy is implied. Heartbeats never overlap; the
+ * final in-flight heartbeat settles before this scope returns. Work must honor
+ * its signal, and a heartbeat abort cannot be reported as successful work.
+ */
+declare function runWithExecutionHeartbeat<T>(options: ExecutionHeartbeatOptions, work: (signal: AbortSignal) => Promise<T>): Promise<T>;
+
+export { type AppendTaskOutboxInput, type ClaimTaskInput, type ClaimTaskOutboxInput, type CreateTaskInput, type CreateTaskResult, type DurableTaskAttemptContext, type DurableTaskHandler, DurableTaskLeaseLostError, DurableTaskNotClaimableError, DurableTaskNotFoundError, DurableTaskRetryScheduledError, type DurableWorkerHeartbeatScheduler, type DurableWorkerRunResult, DurableWorkerRuntime, type DurableWorkerRuntimeLogger, type DurableWorkerRuntimeOptions, ExecutionHeartbeatError, type ExecutionHeartbeatOptions, ExponentialTaskRetryPolicy, type ExponentialTaskRetryPolicyOptions, type FindExpiredTaskLeasesInput, type FindReadyQueuedTasksInput, type HeartbeatTaskInput, InMemoryTaskOutboxRepository, InMemoryTaskRepository, InvalidTaskTransitionError, type ListOwnedTaskSummariesInput, type OwnedTaskTimelineEvent, type PostgresQueryResult, type PostgresTaskClient, PostgresTaskOutboxRepository, PostgresTaskRedriver, PostgresTaskRepository, PostgresTaskSubmitter, PostgresTaskSummaryReader, PostgresTaskTimelineReader, type PostgresTaskTransactionRunner, type ReadyTaskPublisher, type RecoverExpiredTaskLeaseInput, type RedriveFailedTaskInput, type ReportTaskProgressInput, SingleProcessTaskSupervisor, type SingleProcessTaskSupervisorOptions, type SubmitTaskBatchOptions, type SubmitTaskInput, type SubmitTaskOptions, type SubmitTaskOutboxInput, type SubmitTaskResult, TASK_STATUSES, TASK_TIMELINE_EVENT_TYPES, type TaskErrorSummary, type TaskFailureCategory, TaskIdempotencyConflictError, type TaskLeaseReconcileResult, TaskLeaseReconciler, type TaskLeaseReconcilerOptions, TaskOutboxConflictError, type TaskOutboxDispatchResult, TaskOutboxDispatcher, type TaskOutboxDispatcherOptions, type TaskOutboxRecord, type TaskOutboxRepository, type TaskOutboxStatus, type TaskQueuePublisher, type TaskQueueReconcileResult, TaskQueueReconciler, type TaskQueueReconcilerOptions, type TaskRecord, type TaskRedriveResult, type TaskRepository, type TaskResourceRef, type TaskRetryContext, type TaskRetryDecision, type TaskRetryPolicy, type TaskStatus, type TaskSummary, type TaskSummaryError, type TaskTimelineEvent, type TaskTimelineEventType, type TransitionTaskInput, UnsupportedDurableTaskKindError, assertTaskTransition, canTransitionTask, createTaskFingerprint, isTerminalTaskStatus, requiresTaskLease, runWithExecutionHeartbeat };

package/dist/index.js

@@ -26,6 +26,7 @@ __export(index_exports, {
   DurableTaskNotFoundError: () => DurableTaskNotFoundError,
   DurableTaskRetryScheduledError: () => DurableTaskRetryScheduledError,
   DurableWorkerRuntime: () => DurableWorkerRuntime,
+  ExecutionHeartbeatError: () => ExecutionHeartbeatError,
   ExponentialTaskRetryPolicy: () => ExponentialTaskRetryPolicy,
   InMemoryTaskOutboxRepository: () => InMemoryTaskOutboxRepository,
   InMemoryTaskRepository: () => InMemoryTaskRepository,
@@ -36,6 +37,7 @@ __export(index_exports, {
   PostgresTaskSubmitter: () => PostgresTaskSubmitter,
   PostgresTaskSummaryReader: () => PostgresTaskSummaryReader,
   PostgresTaskTimelineReader: () => PostgresTaskTimelineReader,
+  SingleProcessTaskSupervisor: () => SingleProcessTaskSupervisor,
   TASK_STATUSES: () => TASK_STATUSES,
   TASK_TIMELINE_EVENT_TYPES: () => TASK_TIMELINE_EVENT_TYPES,
   TaskIdempotencyConflictError: () => TaskIdempotencyConflictError,
@@ -48,7 +50,8 @@ __export(index_exports, {
   canTransitionTask: () => canTransitionTask,
   createTaskFingerprint: () => createTaskFingerprint,
   isTerminalTaskStatus: () => isTerminalTaskStatus,
-  requiresTaskLease: () => requiresTaskLease
+  requiresTaskLease: () => requiresTaskLease,
+  runWithExecutionHeartbeat: () => runWithExecutionHeartbeat
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1900,6 +1903,159 @@ var TaskOutboxDispatcher = class {
     return result;
   }
 };
+
+// src/single-process-task-supervisor.ts
+var SingleProcessTaskSupervisor = class {
+  static {
+    __name(this, "SingleProcessTaskSupervisor");
+  }
+  options;
+  queued = /* @__PURE__ */ new Set();
+  running = /* @__PURE__ */ new Map();
+  interrupted = /* @__PURE__ */ new Set();
+  queue = [];
+  scanTimer;
+  stopped = false;
+  started = false;
+  constructor(options) {
+    this.options = options;
+  }
+  async onApplicationBootstrap() {
+    if (this.started || this.stopped) return;
+    this.started = true;
+    const interrupted = await this.options.initialize?.() ?? [];
+    interrupted.forEach((id) => this.interrupted.add(id));
+    await this.scanPending();
+    this.scheduleScan();
+  }
+  submit(id) {
+    if (this.stopped || this.queued.has(id) || this.running.has(id)) return;
+    this.queued.add(id);
+    this.queue.push(id);
+    this.drain();
+  }
+  submitRecovery(id) {
+    if (this.stopped || this.queued.has(id) || this.running.has(id)) return;
+    this.interrupted.add(id);
+    this.submit(id);
+  }
+  async waitForIdle() {
+    while (this.queue.length > 0 || this.running.size > 0) {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+  }
+  async onApplicationShutdown() {
+    this.stopped = true;
+    if (this.scanTimer) clearTimeout(this.scanTimer);
+    this.queue = [];
+    this.queued.clear();
+    this.interrupted.clear();
+    for (const id of this.running.keys()) this.options.abort(id);
+  }
+  drain() {
+    while (!this.stopped && this.running.size < this.options.concurrency && this.queue.length > 0) {
+      const id = this.queue.shift();
+      if (id === void 0) return;
+      this.queued.delete(id);
+      const recovery = this.interrupted.delete(id);
+      const execution = Promise.resolve().then(() => this.options.run(id, recovery)).catch((error) => this.options.onExecutionError?.(id, error)).catch(() => {
+      }).finally(() => {
+        this.running.delete(id);
+        this.drain();
+      });
+      this.running.set(id, execution);
+    }
+  }
+  async scanPending() {
+    if (this.stopped) return;
+    const pending = await this.options.loadPending();
+    pending.forEach((id) => this.submit(id));
+  }
+  scheduleScan() {
+    if (this.stopped) return;
+    this.scanTimer = setTimeout(() => {
+      void this.scanPending().catch((error) => this.options.onScanError?.(error)).catch(() => {
+      }).finally(() => this.scheduleScan());
+    }, this.options.scanIntervalMs);
+    this.scanTimer.unref?.();
+  }
+};
+
+// src/execution-heartbeat.ts
+var ExecutionHeartbeatError = class extends Error {
+  static {
+    __name(this, "ExecutionHeartbeatError");
+  }
+  consecutiveFailures;
+  constructor(consecutiveFailures, options) {
+    super(`Execution heartbeat failed ${consecutiveFailures} consecutive times`, options), this.consecutiveFailures = consecutiveFailures;
+    this.name = "ExecutionHeartbeatError";
+  }
+};
+async function runWithExecutionHeartbeat(options, work) {
+  if (!Number.isFinite(options.intervalMs) || options.intervalMs <= 0 || !Number.isSafeInteger(options.failureThreshold) || options.failureThreshold < 1) {
+    throw new RangeError("Heartbeat interval and failure threshold must be positive");
+  }
+  const controller = new AbortController();
+  let stopped = false;
+  let failures = 0;
+  let heartbeatFailure;
+  let timer;
+  let inFlight;
+  const cancel = /* @__PURE__ */ __name(() => {
+    if (timer) clearTimeout(timer);
+    controller.abort(options.signal?.reason);
+  }, "cancel");
+  options.signal?.addEventListener("abort", cancel, {
+    once: true
+  });
+  if (options.signal?.aborted) cancel();
+  const schedule = /* @__PURE__ */ __name(() => {
+    if (stopped || controller.signal.aborted) return;
+    timer = setTimeout(() => {
+      inFlight = tick();
+    }, options.intervalMs);
+    timer.unref?.();
+  }, "schedule");
+  const tick = /* @__PURE__ */ __name(async () => {
+    if (stopped || controller.signal.aborted) return;
+    try {
+      await options.heartbeat();
+      failures = 0;
+    } catch (error) {
+      if (!stopped && !controller.signal.aborted) {
+        failures++;
+        if (failures >= options.failureThreshold) {
+          heartbeatFailure = new ExecutionHeartbeatError(failures, {
+            cause: error
+          });
+          controller.abort(heartbeatFailure);
+        }
+      }
+    } finally {
+      schedule();
+    }
+  }, "tick");
+  try {
+    controller.signal.throwIfAborted();
+    schedule();
+    let result;
+    try {
+      result = await work(controller.signal);
+    } catch (error) {
+      throw heartbeatFailure ?? error;
+    }
+    if (heartbeatFailure) throw heartbeatFailure;
+    controller.signal.throwIfAborted();
+    return result;
+  } finally {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    options.signal?.removeEventListener("abort", cancel);
+    await inFlight;
+  }
+}
+__name(runWithExecutionHeartbeat, "runWithExecutionHeartbeat");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DurableTaskLeaseLostError,
@@ -1907,6 +2063,7 @@ var TaskOutboxDispatcher = class {
   DurableTaskNotFoundError,
   DurableTaskRetryScheduledError,
   DurableWorkerRuntime,
+  ExecutionHeartbeatError,
   ExponentialTaskRetryPolicy,
   InMemoryTaskOutboxRepository,
   InMemoryTaskRepository,
@@ -1917,6 +2074,7 @@ var TaskOutboxDispatcher = class {
   PostgresTaskSubmitter,
   PostgresTaskSummaryReader,
   PostgresTaskTimelineReader,
+  SingleProcessTaskSupervisor,
   TASK_STATUSES,
   TASK_TIMELINE_EVENT_TYPES,
   TaskIdempotencyConflictError,
@@ -1929,5 +2087,6 @@ var TaskOutboxDispatcher = class {
   canTransitionTask,
   createTaskFingerprint,
   isTerminalTaskStatus,
-  requiresTaskLease
+  requiresTaskLease,
+  runWithExecutionHeartbeat
 });

package/dist/index.mjs

@@ -1849,12 +1849,166 @@ var TaskOutboxDispatcher = class {
     return result;
   }
 };
+
+// src/single-process-task-supervisor.ts
+var SingleProcessTaskSupervisor = class {
+  static {
+    __name(this, "SingleProcessTaskSupervisor");
+  }
+  options;
+  queued = /* @__PURE__ */ new Set();
+  running = /* @__PURE__ */ new Map();
+  interrupted = /* @__PURE__ */ new Set();
+  queue = [];
+  scanTimer;
+  stopped = false;
+  started = false;
+  constructor(options) {
+    this.options = options;
+  }
+  async onApplicationBootstrap() {
+    if (this.started || this.stopped) return;
+    this.started = true;
+    const interrupted = await this.options.initialize?.() ?? [];
+    interrupted.forEach((id) => this.interrupted.add(id));
+    await this.scanPending();
+    this.scheduleScan();
+  }
+  submit(id) {
+    if (this.stopped || this.queued.has(id) || this.running.has(id)) return;
+    this.queued.add(id);
+    this.queue.push(id);
+    this.drain();
+  }
+  submitRecovery(id) {
+    if (this.stopped || this.queued.has(id) || this.running.has(id)) return;
+    this.interrupted.add(id);
+    this.submit(id);
+  }
+  async waitForIdle() {
+    while (this.queue.length > 0 || this.running.size > 0) {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+  }
+  async onApplicationShutdown() {
+    this.stopped = true;
+    if (this.scanTimer) clearTimeout(this.scanTimer);
+    this.queue = [];
+    this.queued.clear();
+    this.interrupted.clear();
+    for (const id of this.running.keys()) this.options.abort(id);
+  }
+  drain() {
+    while (!this.stopped && this.running.size < this.options.concurrency && this.queue.length > 0) {
+      const id = this.queue.shift();
+      if (id === void 0) return;
+      this.queued.delete(id);
+      const recovery = this.interrupted.delete(id);
+      const execution = Promise.resolve().then(() => this.options.run(id, recovery)).catch((error) => this.options.onExecutionError?.(id, error)).catch(() => {
+      }).finally(() => {
+        this.running.delete(id);
+        this.drain();
+      });
+      this.running.set(id, execution);
+    }
+  }
+  async scanPending() {
+    if (this.stopped) return;
+    const pending = await this.options.loadPending();
+    pending.forEach((id) => this.submit(id));
+  }
+  scheduleScan() {
+    if (this.stopped) return;
+    this.scanTimer = setTimeout(() => {
+      void this.scanPending().catch((error) => this.options.onScanError?.(error)).catch(() => {
+      }).finally(() => this.scheduleScan());
+    }, this.options.scanIntervalMs);
+    this.scanTimer.unref?.();
+  }
+};
+
+// src/execution-heartbeat.ts
+var ExecutionHeartbeatError = class extends Error {
+  static {
+    __name(this, "ExecutionHeartbeatError");
+  }
+  consecutiveFailures;
+  constructor(consecutiveFailures, options) {
+    super(`Execution heartbeat failed ${consecutiveFailures} consecutive times`, options), this.consecutiveFailures = consecutiveFailures;
+    this.name = "ExecutionHeartbeatError";
+  }
+};
+async function runWithExecutionHeartbeat(options, work) {
+  if (!Number.isFinite(options.intervalMs) || options.intervalMs <= 0 || !Number.isSafeInteger(options.failureThreshold) || options.failureThreshold < 1) {
+    throw new RangeError("Heartbeat interval and failure threshold must be positive");
+  }
+  const controller = new AbortController();
+  let stopped = false;
+  let failures = 0;
+  let heartbeatFailure;
+  let timer;
+  let inFlight;
+  const cancel = /* @__PURE__ */ __name(() => {
+    if (timer) clearTimeout(timer);
+    controller.abort(options.signal?.reason);
+  }, "cancel");
+  options.signal?.addEventListener("abort", cancel, {
+    once: true
+  });
+  if (options.signal?.aborted) cancel();
+  const schedule = /* @__PURE__ */ __name(() => {
+    if (stopped || controller.signal.aborted) return;
+    timer = setTimeout(() => {
+      inFlight = tick();
+    }, options.intervalMs);
+    timer.unref?.();
+  }, "schedule");
+  const tick = /* @__PURE__ */ __name(async () => {
+    if (stopped || controller.signal.aborted) return;
+    try {
+      await options.heartbeat();
+      failures = 0;
+    } catch (error) {
+      if (!stopped && !controller.signal.aborted) {
+        failures++;
+        if (failures >= options.failureThreshold) {
+          heartbeatFailure = new ExecutionHeartbeatError(failures, {
+            cause: error
+          });
+          controller.abort(heartbeatFailure);
+        }
+      }
+    } finally {
+      schedule();
+    }
+  }, "tick");
+  try {
+    controller.signal.throwIfAborted();
+    schedule();
+    let result;
+    try {
+      result = await work(controller.signal);
+    } catch (error) {
+      throw heartbeatFailure ?? error;
+    }
+    if (heartbeatFailure) throw heartbeatFailure;
+    controller.signal.throwIfAborted();
+    return result;
+  } finally {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    options.signal?.removeEventListener("abort", cancel);
+    await inFlight;
+  }
+}
+__name(runWithExecutionHeartbeat, "runWithExecutionHeartbeat");
 export {
   DurableTaskLeaseLostError,
   DurableTaskNotClaimableError,
   DurableTaskNotFoundError,
   DurableTaskRetryScheduledError,
   DurableWorkerRuntime,
+  ExecutionHeartbeatError,
   ExponentialTaskRetryPolicy,
   InMemoryTaskOutboxRepository,
   InMemoryTaskRepository,
@@ -1865,6 +2019,7 @@ export {
   PostgresTaskSubmitter,
   PostgresTaskSummaryReader,
   PostgresTaskTimelineReader,
+  SingleProcessTaskSupervisor,
   TASK_STATUSES,
   TASK_TIMELINE_EVENT_TYPES,
   TaskIdempotencyConflictError,
@@ -1877,5 +2032,6 @@ export {
   canTransitionTask,
   createTaskFingerprint,
   isTerminalTaskStatus,
-  requiresTaskLease
+  requiresTaskLease,
+  runWithExecutionHeartbeat
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zucker-framework/task",
-  "version": "1.0.0",
+  "version": "1.0.5",
   "description": "Durable task lifecycle contracts and state machine for Zucker applications",
   "main": "dist/index.js",
   "module": "dist/index.mjs",