@zucker-framework/task 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,604 @@
+declare const TASK_STATUSES: readonly ["QUEUED", "PROCESSING", "WAITING_PROVIDER", "RETRYING", "COMPLETED", "FAILED", "CANCELLED"];
+type TaskStatus = (typeof TASK_STATUSES)[number];
+declare class InvalidTaskTransitionError extends Error {
+    readonly from: TaskStatus;
+    readonly to: TaskStatus;
+    constructor(from: TaskStatus, to: TaskStatus);
+}
+declare function canTransitionTask(from: TaskStatus, to: TaskStatus): boolean;
+declare function assertTaskTransition(from: TaskStatus, to: TaskStatus): void;
+declare function isTerminalTaskStatus(status: TaskStatus): boolean;
+declare function requiresTaskLease(status: TaskStatus): boolean;
+
+/** Produces a deterministic SHA-256 fingerprint for a JSON-compatible task request. */
+declare function createTaskFingerprint(value: unknown): string;
+
+interface TaskResourceRef {
+    type: string;
+    id: string;
+}
+type TaskFailureCategory = 'RATE_LIMIT' | 'NETWORK' | 'PROVIDER_5XX' | 'PROVIDER_TIMEOUT' | 'INTERNAL' | 'VALIDATION' | 'AUTHENTICATION' | 'AUTHORIZATION' | 'CONTENT_POLICY' | 'CANCELLED' | 'UNKNOWN';
+interface TaskErrorSummary {
+    code: string;
+    category: TaskFailureCategory;
+    summary: string;
+    retryable: boolean;
+    metadata?: Readonly<Record<string, string | number | boolean | null>>;
+}
+interface TaskRecord<TPayload = unknown, TResult = unknown> {
+    id: string;
+    kind: string;
+    resource: TaskResourceRef;
+    userId?: string;
+    orderId?: string;
+    status: TaskStatus;
+    stage?: string;
+    progress: number;
+    attempt: number;
+    maxAttempts: number;
+    idempotencyKey: string;
+    idempotencyFingerprint: string;
+    handlerVersion: string;
+    payload: TPayload;
+    result?: TResult;
+    error?: TaskErrorSummary;
+    providerRequestId?: string;
+    workerId?: string;
+    leaseToken?: string;
+    leaseExpiresAt?: Date;
+    heartbeatAt?: Date;
+    availableAt: Date;
+    createdAt: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+    updatedAt: Date;
+    version: number;
+}
+interface CreateTaskInput<TPayload> {
+    id: string;
+    kind: string;
+    resource: TaskResourceRef;
+    userId?: string;
+    orderId?: string;
+    idempotencyKey: string;
+    idempotencyFingerprint: string;
+    handlerVersion: string;
+    payload: TPayload;
+    maxAttempts: number;
+    availableAt?: Date;
+    now: Date;
+}
+interface CreateTaskResult<TPayload, TResult> {
+    task: TaskRecord<TPayload, TResult>;
+    created: boolean;
+}
+interface ClaimTaskInput {
+    id: string;
+    workerId: string;
+    leaseToken: string;
+    leaseExpiresAt: Date;
+    now: Date;
+}
+interface HeartbeatTaskInput {
+    id: string;
+    leaseToken: string;
+    leaseExpiresAt: Date;
+    now: Date;
+}
+interface ReportTaskProgressInput {
+    id: string;
+    leaseToken: string;
+    stage?: string;
+    progress: number;
+    now: Date;
+}
+interface TransitionTaskInput<TResult> {
+    id: string;
+    from: TaskStatus;
+    to: TaskStatus;
+    leaseToken?: string;
+    stage?: string;
+    progress?: number;
+    result?: TResult;
+    error?: TaskErrorSummary;
+    providerRequestId?: string;
+    availableAt?: Date;
+    now: Date;
+}
+interface FindExpiredTaskLeasesInput {
+    now: Date;
+    limit: number;
+}
+interface FindReadyQueuedTasksInput {
+    now: Date;
+    limit: number;
+    offset?: number;
+}
+interface RecoverExpiredTaskLeaseInput {
+    id: string;
+    leaseToken: string;
+    now: Date;
+    availableAt?: Date;
+    error: TaskErrorSummary;
+}
+interface TaskRepository<TPayload = unknown, TResult = unknown> {
+    create(input: CreateTaskInput<TPayload>): Promise<CreateTaskResult<TPayload, TResult>>;
+    findById(id: string): Promise<TaskRecord<TPayload, TResult> | null>;
+    findByIdempotencyKey(key: string): Promise<TaskRecord<TPayload, TResult> | null>;
+    /** The only operation allowed to start a queued attempt and issue its lease. */
+    claim(input: ClaimTaskInput): Promise<TaskRecord<TPayload, TResult> | null>;
+    heartbeat(input: HeartbeatTaskInput): Promise<boolean>;
+    /** Reports monotonic progress only while the current attempt lease is valid. */
+    reportProgress(input: ReportTaskProgressInput): Promise<TaskRecord<TPayload, TResult> | null>;
+    /** Applies lifecycle transitions other than QUEUED -> PROCESSING, which must use claim(). */
+    transition(input: TransitionTaskInput<TResult>): Promise<TaskRecord<TPayload, TResult> | null>;
+    /** Returns durable work that should have a corresponding transport message. */
+    findReadyQueued(input: FindReadyQueuedTasksInput): Promise<TaskRecord<TPayload, TResult>[]>;
+    findExpiredLeases(input: FindExpiredTaskLeasesInput): Promise<TaskRecord<TPayload, TResult>[]>;
+    recoverExpiredLease(input: RecoverExpiredTaskLeaseInput): Promise<TaskRecord<TPayload, TResult> | null>;
+    cancel(id: string, now: Date): Promise<TaskRecord<TPayload, TResult> | null>;
+}
+declare class TaskIdempotencyConflictError extends Error {
+    readonly idempotencyKey: string;
+    constructor(idempotencyKey: string);
+}
+
+/**
+ * Reference implementation for contract tests and local development only.
+ * Production applications must use a repository with durable storage and atomic conditional updates.
+ */
+declare class InMemoryTaskRepository<TPayload = unknown, TResult = unknown> implements TaskRepository<TPayload, TResult> {
+    private readonly tasks;
+    private readonly idempotencyIndex;
+    create(input: CreateTaskInput<TPayload>): Promise<CreateTaskResult<TPayload, TResult>>;
+    findById(id: string): Promise<TaskRecord<TPayload, TResult> | null>;
+    findByIdempotencyKey(key: string): Promise<TaskRecord<TPayload, TResult> | null>;
+    claim(input: ClaimTaskInput): Promise<TaskRecord<TPayload, TResult> | null>;
+    heartbeat(input: HeartbeatTaskInput): Promise<boolean>;
+    reportProgress(input: ReportTaskProgressInput): Promise<TaskRecord<TPayload, TResult> | null>;
+    transition(input: TransitionTaskInput<TResult>): Promise<TaskRecord<TPayload, TResult> | null>;
+    findExpiredLeases(input: FindExpiredTaskLeasesInput): Promise<TaskRecord<TPayload, TResult>[]>;
+    findReadyQueued(input: FindReadyQueuedTasksInput): Promise<TaskRecord<TPayload, TResult>[]>;
+    recoverExpiredLease(input: RecoverExpiredTaskLeaseInput): Promise<TaskRecord<TPayload, TResult> | null>;
+    cancel(id: string, now: Date): Promise<TaskRecord<TPayload, TResult> | null>;
+}
+
+interface PostgresQueryResult<TRow> {
+    rows: TRow[];
+}
+/** Minimal port implemented by pg clients, PGlite, and thin Prisma raw-query adapters. */
+interface PostgresTaskClient {
+    query<TRow>(sql: string, parameters?: readonly unknown[]): Promise<PostgresQueryResult<TRow>>;
+}
+/**
+ * PostgreSQL reference repository for the published Prisma schema fragment.
+ * All ownership-changing operations use conditional UPDATE ... RETURNING statements.
+ */
+declare class PostgresTaskRepository<TPayload = unknown, TResult = unknown> implements TaskRepository<TPayload, TResult> {
+    private readonly client;
+    constructor(client: PostgresTaskClient);
+    create(input: CreateTaskInput<TPayload>): Promise<CreateTaskResult<TPayload, TResult>>;
+    findById(id: string): Promise<TaskRecord<TPayload, TResult> | null>;
+    findByIdempotencyKey(key: string): Promise<TaskRecord<TPayload, TResult> | null>;
+    claim(input: ClaimTaskInput): Promise<TaskRecord<TPayload, TResult> | null>;
+    heartbeat(input: HeartbeatTaskInput): Promise<boolean>;
+    reportProgress(input: ReportTaskProgressInput): Promise<TaskRecord<TPayload, TResult> | null>;
+    transition(input: TransitionTaskInput<TResult>): Promise<TaskRecord<TPayload, TResult> | null>;
+    findExpiredLeases(input: FindExpiredTaskLeasesInput): Promise<TaskRecord<TPayload, TResult>[]>;
+    findReadyQueued(input: FindReadyQueuedTasksInput): Promise<TaskRecord<TPayload, TResult>[]>;
+    recoverExpiredLease(input: RecoverExpiredTaskLeaseInput): Promise<TaskRecord<TPayload, TResult> | null>;
+    cancel(id: string, now: Date): Promise<TaskRecord<TPayload, TResult> | null>;
+    private toTask;
+}
+
+interface TaskSummaryError {
+    code: string;
+    category: TaskFailureCategory;
+    summary: string;
+    retryable: boolean;
+}
+interface TaskSummary {
+    id: string;
+    kind: string;
+    resource: TaskResourceRef;
+    status: TaskStatus;
+    stage?: string;
+    progress: number;
+    attempt: number;
+    maxAttempts: number;
+    error?: TaskSummaryError;
+    createdAt: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+    updatedAt: Date;
+    version: number;
+}
+interface ListOwnedTaskSummariesInput {
+    userId: string;
+    statuses?: readonly TaskStatus[];
+    limit?: number;
+}
+/** Read-only, owner-scoped task projection that never loads task payloads or results. */
+declare class PostgresTaskSummaryReader {
+    private readonly client;
+    constructor(client: PostgresTaskClient);
+    findOwnedById(taskId: string, userId: string): Promise<TaskSummary | null>;
+    listOwned(input: ListOwnedTaskSummariesInput): Promise<TaskSummary[]>;
+}
+
+declare const TASK_TIMELINE_EVENT_TYPES: readonly ["SNAPSHOT", "CREATED", "CLAIMED", "PROGRESS", "RETRY_SCHEDULED", "REQUEUED", "LEASE_RECOVERED", "MANUAL_REDRIVE", "COMPLETED", "FAILED", "CANCELLED", "STATUS_CHANGED"];
+type TaskTimelineEventType = (typeof TASK_TIMELINE_EVENT_TYPES)[number];
+interface OwnedTaskTimelineEvent {
+    id: string;
+    taskId: string;
+    sequence: number;
+    type: TaskTimelineEventType;
+    fromStatus?: TaskStatus;
+    toStatus: TaskStatus;
+    stage?: string;
+    progress: number;
+    attempt: number;
+    maxAttempts: number;
+    error?: {
+        code: string;
+        category: TaskFailureCategory;
+        summary: string;
+        retryable: boolean;
+    };
+    createdAt: Date;
+}
+interface TaskTimelineEvent extends OwnedTaskTimelineEvent {
+    workerId?: string;
+    providerRequestId?: string;
+}
+/** Payload-free timeline reader with separate owner and operator projections. */
+declare class PostgresTaskTimelineReader {
+    private readonly client;
+    constructor(client: PostgresTaskClient);
+    listOwned(taskId: string, userId: string, limit?: number): Promise<OwnedTaskTimelineEvent[]>;
+    listByTaskId(taskId: string, limit?: number): Promise<TaskTimelineEvent[]>;
+    private normalizeLimit;
+}
+
+interface RedriveFailedTaskInput {
+    taskId: string;
+    now: Date;
+    additionalAttempts?: number;
+    stage?: string;
+}
+interface TaskRedriveResult {
+    taskId: string;
+    attempt: number;
+    maxAttempts: number;
+    version: number;
+    availableAt: Date;
+}
+/** Generic terminal-failure redrive primitive; domain projections and outbox stay application-owned. */
+declare class PostgresTaskRedriver {
+    private readonly client;
+    constructor(client: PostgresTaskClient);
+    redriveFailed(input: RedriveFailedTaskInput): Promise<TaskRedriveResult | null>;
+}
+
+type TaskOutboxStatus = 'PENDING' | 'PUBLISHING' | 'PUBLISHED';
+interface TaskOutboxRecord<TPayload = unknown> {
+    id: string;
+    taskId: string;
+    topic: string;
+    payload: TPayload;
+    status: TaskOutboxStatus;
+    attempt: number;
+    availableAt: Date;
+    workerId?: string;
+    leaseToken?: string;
+    leaseExpiresAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+    publishedAt?: Date;
+    lastError?: string;
+}
+interface AppendTaskOutboxInput<TPayload> {
+    id: string;
+    taskId: string;
+    topic: string;
+    payload: TPayload;
+    availableAt?: Date;
+    now: Date;
+}
+interface ClaimTaskOutboxInput {
+    workerId: string;
+    leaseToken: string;
+    leaseExpiresAt: Date;
+    limit: number;
+    now: Date;
+}
+interface TaskOutboxRepository<TPayload = unknown> {
+    append(input: AppendTaskOutboxInput<TPayload>): Promise<{
+        record: TaskOutboxRecord<TPayload>;
+        created: boolean;
+    }>;
+    claimBatch(input: ClaimTaskOutboxInput): Promise<TaskOutboxRecord<TPayload>[]>;
+    markPublished(id: string, leaseToken: string, now: Date): Promise<boolean>;
+    reschedule(id: string, leaseToken: string, availableAt: Date, errorSummary: string, now: Date): Promise<boolean>;
+}
+interface TaskQueuePublisher<TPayload = unknown> {
+    publish(message: TaskOutboxRecord<TPayload>): Promise<void>;
+}
+declare class TaskOutboxConflictError extends Error {
+    readonly eventId: string;
+    constructor(eventId: string);
+}
+
+interface PostgresTaskTransactionRunner {
+    runInTransaction<T>(work: (client: PostgresTaskClient) => Promise<T>): Promise<T>;
+}
+interface SubmitTaskOutboxInput<TPayload> {
+    id: string;
+    topic: string;
+    payload: TPayload;
+    availableAt?: Date;
+}
+interface SubmitTaskInput<TTaskPayload, TOutboxPayload> {
+    task: CreateTaskInput<TTaskPayload>;
+    outbox: SubmitTaskOutboxInput<TOutboxPayload>;
+}
+interface SubmitTaskResult<TTaskPayload, TTaskResult, TOutboxPayload> {
+    task: CreateTaskResult<TTaskPayload, TTaskResult>;
+    outbox: {
+        record: TaskOutboxRecord<TOutboxPayload>;
+        created: boolean;
+    };
+}
+interface SubmitTaskOptions<TTaskPayload, TTaskResult, TOutboxPayload> {
+    /**
+     * Persists an application-owned projection in the same transaction as the
+     * durable task and outbox intent. The callback can run again for an
+     * idempotent submission, so application writes must also be idempotent.
+     */
+    transactionalWork?: (client: PostgresTaskClient, result: SubmitTaskResult<TTaskPayload, TTaskResult, TOutboxPayload>) => Promise<void>;
+}
+interface SubmitTaskBatchOptions<TTaskPayload, TTaskResult, TOutboxPayload> {
+    /**
+     * Persists application-owned batch projections in the same transaction as
+     * every task and outbox intent. The callback receives results in input order
+     * and must remain idempotent when a batch is submitted again.
+     */
+    transactionalWork?: (client: PostgresTaskClient, results: SubmitTaskResult<TTaskPayload, TTaskResult, TOutboxPayload>[]) => Promise<void>;
+}
+/** Creates the durable task and its queue intent in one database transaction. */
+declare class PostgresTaskSubmitter<TTaskPayload = unknown, TTaskResult = unknown, TOutboxPayload = unknown> {
+    private readonly transactions;
+    constructor(transactions: PostgresTaskTransactionRunner);
+    submit(input: SubmitTaskInput<TTaskPayload, TOutboxPayload>, options?: SubmitTaskOptions<TTaskPayload, TTaskResult, TOutboxPayload>): Promise<SubmitTaskResult<TTaskPayload, TTaskResult, TOutboxPayload>>;
+    submitBatch(inputs: readonly SubmitTaskInput<TTaskPayload, TOutboxPayload>[], options?: SubmitTaskBatchOptions<TTaskPayload, TTaskResult, TOutboxPayload>): Promise<SubmitTaskResult<TTaskPayload, TTaskResult, TOutboxPayload>[]>;
+    private submitWithClient;
+}
+
+interface TaskLeaseReconcilerOptions {
+    batchSize?: number;
+    retryDelayMs?: number;
+    now?: () => Date;
+}
+interface TaskLeaseReconcileResult {
+    found: number;
+    requeued: number;
+    failed: number;
+    conflicts: number;
+}
+declare class TaskLeaseReconciler<TPayload = unknown, TResult = unknown> {
+    private readonly repository;
+    private readonly batchSize;
+    private readonly retryDelayMs;
+    private readonly now;
+    constructor(repository: TaskRepository<TPayload, TResult>, options?: TaskLeaseReconcilerOptions);
+    runOnce(): Promise<TaskLeaseReconcileResult>;
+}
+
+interface TaskQueueReconcilerOptions {
+    batchSize?: number;
+    now?: () => Date;
+}
+interface TaskQueueReconcileResult {
+    found: number;
+    ensured: number;
+    failed: number;
+}
+interface ReadyTaskPublisher<TPayload = unknown, TResult = unknown> {
+    ensure(task: TaskRecord<TPayload, TResult>): Promise<void>;
+}
+/**
+ * Repairs drift between the durable task store and an at-least-once queue.
+ * A publish failure leaves the task QUEUED so a later pass can retry safely.
+ */
+declare class TaskQueueReconciler<TPayload = unknown, TResult = unknown> {
+    private readonly repository;
+    private readonly publisher;
+    private readonly batchSize;
+    private readonly now;
+    private offset;
+    constructor(repository: TaskRepository<TPayload, TResult>, publisher: ReadyTaskPublisher<TPayload, TResult>, options?: TaskQueueReconcilerOptions);
+    runOnce(): Promise<TaskQueueReconcileResult>;
+}
+
+interface TaskRetryContext {
+    error: TaskErrorSummary;
+    attempt: number;
+    maxAttempts: number;
+    retryAfterMs?: number;
+}
+type TaskRetryDecision = {
+    retry: false;
+    reason: 'NON_RETRYABLE' | 'ATTEMPTS_EXHAUSTED';
+} | {
+    retry: true;
+    delayMs: number;
+};
+interface TaskRetryPolicy {
+    decide(context: TaskRetryContext): TaskRetryDecision;
+}
+interface ExponentialTaskRetryPolicyOptions {
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitterRatio?: number;
+    retryableCategories?: readonly TaskFailureCategory[];
+    random?: () => number;
+}
+declare class ExponentialTaskRetryPolicy implements TaskRetryPolicy {
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly jitterRatio;
+    private readonly retryableCategories;
+    private readonly random;
+    constructor(options?: ExponentialTaskRetryPolicyOptions);
+    decide(context: TaskRetryContext): TaskRetryDecision;
+}
+
+interface DurableTaskAttemptContext<TPayload = unknown, TResult = unknown> {
+    readonly task: TaskRecord<TPayload, TResult>;
+    readonly leaseToken: string;
+    readonly signal: AbortSignal;
+    now(): Date;
+    assertActive(): Promise<void>;
+    reportProgress(stage: string | undefined, progress: number): Promise<TaskRecord<TPayload, TResult>>;
+}
+interface DurableTaskHandler<TPayload = unknown, TResult = unknown> {
+    execute(context: DurableTaskAttemptContext<TPayload, TResult>): Promise<TResult>;
+    /**
+     * Override when task completion and a business projection must commit atomically.
+     * Returning false means the current lease no longer owns the commit.
+     */
+    complete?(context: DurableTaskAttemptContext<TPayload, TResult>, result: TResult): Promise<boolean>;
+    /** Override when retry state and a business projection must commit atomically. */
+    retry?(context: DurableTaskAttemptContext<TPayload, TResult>, error: TaskErrorSummary, retryAt: Date): Promise<boolean>;
+    /** Override when failure state and a business projection must commit atomically. */
+    fail?(context: DurableTaskAttemptContext<TPayload, TResult>, error: TaskErrorSummary): Promise<boolean>;
+    onCancelled?(context: DurableTaskAttemptContext<TPayload, TResult>): Promise<void> | void;
+    cleanup?(context: DurableTaskAttemptContext<TPayload, TResult>): Promise<void> | void;
+}
+interface DurableWorkerRuntimeLogger {
+    debug?(message: string, context: Readonly<Record<string, unknown>>): void;
+    warn?(message: string, context: Readonly<Record<string, unknown>>): void;
+    error?(message: string, context: Readonly<Record<string, unknown>>): void;
+}
+interface DurableWorkerHeartbeatScheduler {
+    start(tick: () => Promise<void>, intervalMs: number): unknown;
+    stop(handle: unknown): void;
+}
+interface DurableWorkerRuntimeOptions<TPayload = unknown, TResult = unknown> {
+    repository: TaskRepository<TPayload, TResult>;
+    resolveHandler(task: TaskRecord<TPayload, TResult>): DurableTaskHandler<TPayload, TResult> | null | undefined;
+    retryPolicy: TaskRetryPolicy;
+    classifyError(error: unknown, task: TaskRecord<TPayload, TResult>): TaskErrorSummary;
+    workerId: string;
+    leaseDurationMs?: number;
+    heartbeatIntervalMs?: number;
+    maxConsecutiveHeartbeatFailures?: number;
+    now?: () => Date;
+    createLeaseToken?: () => string;
+    retryAfterMs?(error: unknown, task: TaskRecord<TPayload, TResult>): number | undefined;
+    heartbeatScheduler?: DurableWorkerHeartbeatScheduler;
+    logger?: DurableWorkerRuntimeLogger;
+    onAbort?(task: TaskRecord<TPayload, TResult>, reason: DurableTaskLeaseLostError): Promise<void> | void;
+}
+interface DurableWorkerRunResult {
+    taskId: string;
+    kind: string;
+    status: TaskStatus;
+}
+declare class DurableTaskNotFoundError extends Error {
+    readonly taskId: string;
+    constructor(taskId: string);
+}
+declare class UnsupportedDurableTaskKindError extends Error {
+    readonly taskId: string;
+    readonly kind: string;
+    constructor(taskId: string, kind: string);
+}
+declare class DurableTaskNotClaimableError extends Error {
+    readonly taskId: string;
+    readonly status: TaskStatus;
+    constructor(taskId: string, status: TaskStatus);
+}
+declare class DurableTaskLeaseLostError extends Error {
+    readonly taskId: string;
+    readonly operation: string;
+    constructor(taskId: string, operation: string);
+}
+declare class DurableTaskRetryScheduledError extends Error {
+    readonly taskId: string;
+    readonly taskError: TaskErrorSummary;
+    readonly retryAt: Date;
+    constructor(taskId: string, taskError: TaskErrorSummary, retryAt: Date);
+}
+declare class DurableWorkerRuntime<TPayload = unknown, TResult = unknown> {
+    private readonly options;
+    private readonly repository;
+    private readonly retryPolicy;
+    private readonly workerId;
+    private readonly leaseDurationMs;
+    private readonly heartbeatIntervalMs;
+    private readonly maxConsecutiveHeartbeatFailures;
+    private readonly now;
+    private readonly createLeaseToken;
+    private readonly heartbeatScheduler;
+    constructor(options: DurableWorkerRuntimeOptions<TPayload, TResult>);
+    run(taskId: string): Promise<DurableWorkerRunResult>;
+    private leaseExpiry;
+    private retry;
+    private resolveRejectedCommit;
+    private findLatestBestEffort;
+}
+
+/** Reference outbox for contract tests and local development only. */
+declare class InMemoryTaskOutboxRepository<TPayload = unknown> implements TaskOutboxRepository<TPayload> {
+    private readonly records;
+    append(input: AppendTaskOutboxInput<TPayload>): Promise<{
+        record: TaskOutboxRecord<TPayload>;
+        created: boolean;
+    }>;
+    claimBatch(input: ClaimTaskOutboxInput): Promise<TaskOutboxRecord<TPayload>[]>;
+    markPublished(id: string, leaseToken: string, now: Date): Promise<boolean>;
+    reschedule(id: string, leaseToken: string, availableAt: Date, errorSummary: string, now: Date): Promise<boolean>;
+}
+
+/** PostgreSQL outbox repository with atomic multi-dispatcher claims. */
+declare class PostgresTaskOutboxRepository<TPayload = unknown> implements TaskOutboxRepository<TPayload> {
+    private readonly client;
+    constructor(client: PostgresTaskClient);
+    append(input: AppendTaskOutboxInput<TPayload>): Promise<{
+        record: TaskOutboxRecord<TPayload>;
+        created: boolean;
+    }>;
+    claimBatch(input: ClaimTaskOutboxInput): Promise<TaskOutboxRecord<TPayload>[]>;
+    markPublished(id: string, leaseToken: string, now: Date): Promise<boolean>;
+    reschedule(id: string, leaseToken: string, availableAt: Date, errorSummary: string, now: Date): Promise<boolean>;
+    private toRecord;
+}
+
+interface TaskOutboxDispatcherOptions {
+    workerId: string;
+    createLeaseToken: () => string;
+    batchSize?: number;
+    leaseDurationMs?: number;
+    retryDelayMs?: (attempt: number) => number;
+    now?: () => Date;
+}
+interface TaskOutboxDispatchResult {
+    claimed: number;
+    published: number;
+    rescheduled: number;
+    conflicts: number;
+}
+declare class TaskOutboxDispatcher<TPayload = unknown> {
+    private readonly repository;
+    private readonly publisher;
+    private readonly options;
+    private readonly batchSize;
+    private readonly leaseDurationMs;
+    private readonly retryDelayMs;
+    private readonly now;
+    constructor(repository: TaskOutboxRepository<TPayload>, publisher: TaskQueuePublisher<TPayload>, options: TaskOutboxDispatcherOptions);
+    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 };