bunqueue-client 0.1.8 → 0.2.0

package/dist/types/src/client/worker/processorHandlers.d.ts

@@ -0,0 +1,4 @@
+export * from "./handlers/completion.js";
+export * from "./handlers/dependencies.js";
+export * from "./handlers/mutations.js";
+export * from "./handlers/queries.js";

package/dist/types/src/client/worker/processorOutcome.d.ts

@@ -0,0 +1,14 @@
+import type { EventEmitter } from 'events';
+import type { Job as InternalJob } from "../../domain/types/job.js";
+import type { FlowJobData, Job } from "../types.js";
+import type { FailureContext, ProcessorConfig } from "./types/index.js";
+import type { ManualMove } from "./types/index.js";
+/** Settle an explicit processor-owned outcome or nonterminal transition. */
+export declare function handleManualMove<T extends FlowJobData>(manualMove: ManualMove, job: Job<T>, config: {
+    onOutcome?: (succeeded: boolean) => void;
+    emitter: EventEmitter;
+    shouldAbandonOutcome?: () => boolean;
+}, internalJob: InternalJob): Promise<boolean>;
+/** Identify an outcome that lost its processing generation before completion. */
+export declare function isJobNotFoundError(err: Error): boolean;
+export declare function handleJobFailure<T, R>(internalJob: InternalJob, error: unknown, config: ProcessorConfig<T, R>, context: FailureContext<T & FlowJobData>): Promise<void>;

package/dist/types/src/client/worker/processorResult.d.ts

@@ -0,0 +1,2 @@
+import type { ObservableLike } from "../types.js";
+export declare function resolveProcessorResult<T>(value: Promise<T> | ObservableLike<T> | T, signal: AbortSignal): Promise<T>;

package/dist/types/src/client/worker/runtime/buffer.d.ts

@@ -0,0 +1,8 @@
+import { WorkerLifecycle } from "./lifecycle.js";
+import type { PulledJob, WorkerDelivery } from "./state.js";
+export declare abstract class WorkerBuffer<T = unknown, R = unknown> extends WorkerLifecycle<T, R> {
+    protected registerPulledJobs(items: PulledJob[]): WorkerDelivery[];
+    protected getBufferedJob(): WorkerDelivery | null;
+    protected requeueItem(item: WorkerDelivery): void;
+    protected getNextEligibleJob(): WorkerDelivery | null;
+}

package/dist/types/src/client/worker/runtime/control.d.ts

@@ -0,0 +1,28 @@
+import type { Job } from "../../types.js";
+import { WorkerState } from "./state.js";
+export declare abstract class WorkerControl<T = unknown, R = unknown> extends WorkerState<T, R> {
+    run(): void;
+    protected subscribeToStalledEvents(): void;
+    pause(): void;
+    resume(): void;
+    isRunning(): boolean;
+    isPaused(): boolean;
+    isClosed(): boolean;
+    get concurrency(): number;
+    set concurrency(value: number);
+    get closing(): Promise<void> | null;
+    waitUntilReady(): Promise<void>;
+    cancelJob(jobId: string, reason?: string): boolean;
+    cancelAllJobs(reason?: string): void;
+    isJobCancelled(jobId: string): boolean;
+    getRateLimiterInfo(): {
+        current: number;
+        max: number;
+        duration: number;
+    } | null;
+    rateLimit(expireTimeMs: number): void;
+    isRateLimited(): boolean;
+    rateLimitGroup(job: Job<T>, duration: number): Promise<void>;
+    startStalledCheckTimer(): Promise<void>;
+    delay(milliseconds?: number, abortController?: AbortController): Promise<void>;
+}

package/dist/types/src/client/worker/runtime/execution.d.ts

@@ -0,0 +1,16 @@
+import type { HeartbeatDeps } from "../workerHeartbeat.js";
+import type { PullConfig } from "../workerPull.js";
+import { WorkerPolling } from "./polling.js";
+import type { WorkerDelivery } from "./state.js";
+export declare class WorkerExecution<T = unknown, R = unknown> extends WorkerPolling<T, R> {
+    private batchWaitDeadline;
+    private batchFillPending;
+    protected startJob(delivery: WorkerDelivery): boolean;
+    private startBatch;
+    private fillPendingBatch;
+    private startDeliveries;
+    protected registerWithServer(): void;
+    protected startWorkerHeartbeat(): void;
+    protected getHeartbeatDeps(): HeartbeatDeps;
+    protected getPullConfig(): PullConfig;
+}

package/dist/types/src/client/worker/runtime/lifecycle.d.ts

@@ -0,0 +1,7 @@
+import { WorkerManual } from "./manual.js";
+export declare abstract class WorkerLifecycle<T = unknown, R = unknown> extends WorkerManual<T, R> {
+    close(force?: boolean): Promise<void>;
+    protected _doClose(force: boolean): Promise<void>;
+    protected releaseBufferedJobs(): Promise<void>;
+    private releasePulledJob;
+}

package/dist/types/src/client/worker/runtime/manual.d.ts

@@ -0,0 +1,10 @@
+import type { ManualJob } from "../types/index.js";
+import { WorkerControl } from "./control.js";
+export declare abstract class WorkerManual<T = unknown, R = unknown> extends WorkerControl<T, R> {
+    private registerManualJob;
+    getNextJob(token?: string, _opts?: {
+        block?: boolean;
+    }): Promise<ManualJob<T> | undefined>;
+    processJobManually(job: ManualJob<T>, token?: string, fetchNextCallback?: () => Promise<ManualJob<T> | undefined>): Promise<ManualJob<T> | undefined>;
+    extendJobLocks(jobIds: string[], tokens: string[], duration: number): Promise<number>;
+}

package/dist/types/src/client/worker/runtime/options.d.ts

@@ -0,0 +1,5 @@
+import type { WorkerOptions } from "../../types.js";
+import { TcpConnectionPool } from "../../tcpPool.js";
+import type { ExtendedWorkerOptions } from "../types/index.js";
+export declare function resolveWorkerOptions(options: WorkerOptions, embedded: boolean): ExtendedWorkerOptions;
+export declare function createTcpPool(options: WorkerOptions, concurrency: number): TcpConnectionPool;

package/dist/types/src/client/worker/runtime/polling.d.ts

@@ -0,0 +1,14 @@
+import { type PullConfig } from "../workerPull.js";
+import { WorkerBuffer } from "./buffer.js";
+import type { PulledJob, WorkerDelivery } from "./state.js";
+export declare abstract class WorkerPolling<T = unknown, R = unknown> extends WorkerBuffer<T, R> {
+    protected poll(): void;
+    protected scheduleProcessing(): void;
+    protected tryProcess(): Promise<void>;
+    protected doPullBatch(): Promise<PulledJob[]>;
+    private scheduleRateLimitPoll;
+    private schedulePoll;
+    protected handlePullError(errorValue: unknown): void;
+    protected abstract startJob(delivery: WorkerDelivery): boolean;
+    protected abstract getPullConfig(): PullConfig;
+}

package/dist/types/src/client/worker/runtime/state.d.ts

@@ -0,0 +1,121 @@
+import { EventEmitter } from 'events';
+import type { Job as InternalJob } from "../../../domain/types/job.js";
+import type { Job, Processor, WorkerOptions } from "../../types.js";
+import type { TcpConnectionPool } from "../../tcpPool.js";
+import { AckBatcher } from "../ackBatcher.js";
+import { GroupConcurrencyLimiter } from "../groupConcurrency.js";
+import type { HeartbeatDeps } from "../workerHeartbeat.js";
+import { WorkerRateLimiter } from "../workerRateLimiter.js";
+import type { ExtendedWorkerOptions, TcpConnection } from "../types/index.js";
+import type { TcpEventSubscription } from "../../queue-events/tcpSubscription.js";
+export interface PulledJob {
+    job: InternalJob;
+    token: string | null;
+}
+export interface WorkerDelivery extends PulledJob {
+    generation: number;
+}
+export declare abstract class WorkerState<T = unknown, R = unknown> extends EventEmitter {
+    readonly name: string;
+    protected readonly queueKey: string;
+    readonly opts: ExtendedWorkerOptions;
+    protected readonly processor: Processor<T, R>;
+    protected readonly embedded: boolean;
+    protected readonly tcp: TcpConnection | null;
+    protected readonly tcpPool: TcpConnectionPool | null;
+    protected readonly ackBatcher: AckBatcher;
+    protected readonly rateLimiter: WorkerRateLimiter;
+    protected readonly groupLimiter: GroupConcurrencyLimiter | null;
+    protected running: boolean;
+    protected paused: boolean;
+    protected _closing: boolean;
+    protected _forceClose: boolean;
+    protected _closingPromise: Promise<void> | null;
+    protected closed: boolean;
+    protected activeJobs: number;
+    protected pollTimer: ReturnType<typeof setTimeout> | null;
+    protected pollDeadline: number | null;
+    protected consecutiveErrors: number;
+    protected readonly pulledJobIds: Set<string>;
+    protected readonly jobTokens: Map<string, string>;
+    protected readonly cancelledJobs: Set<string>;
+    private readonly abortControllers;
+    private deliverySequence;
+    private readonly currentDeliveries;
+    private readonly activeDeliveries;
+    private readonly unqueuedAckCandidates;
+    protected heartbeatTimer: ReturnType<typeof setInterval> | null;
+    protected workerHeartbeatTimer: ReturnType<typeof setInterval> | null;
+    protected processedCount: number;
+    protected failedCount: number;
+    protected readonly startedAt: number;
+    protected registered: boolean;
+    protected readonly workerId: string;
+    protected pendingJobs: WorkerDelivery[];
+    protected pendingJobsHead: number;
+    protected processingScheduled: boolean;
+    protected batchAffinity: string | null | undefined;
+    protected pendingPull: number;
+    protected lastDrainedEmit: number;
+    protected stalledUnsubscribe: (() => void) | null;
+    protected stalledSubscription: TcpEventSubscription | null;
+    on(event: 'ready' | 'drained' | 'closed', listener: () => void): this;
+    on(event: 'active', listener: (job: Job<T>) => void): this;
+    on(event: 'completed', listener: (job: Job<T>, result: R) => void): this;
+    on(event: 'failed', listener: (job: Job<T>, error: Error) => void): this;
+    on(event: 'progress', listener: (job: Job<T> | null, progress: number) => void): this;
+    on(event: 'stalled', listener: (jobId: string, reason: string) => void): this;
+    on(event: 'error', listener: (error: Error) => void): this;
+    on(event: 'cancelled', listener: (data: {
+        jobId: string;
+        reason: string;
+    }) => void): this;
+    on(event: 'log', listener: (job: Job<T>, message: string) => void): this;
+    once(event: 'ready' | 'drained' | 'closed', listener: () => void): this;
+    once(event: 'active', listener: (job: Job<T>) => void): this;
+    once(event: 'completed', listener: (job: Job<T>, result: R) => void): this;
+    once(event: 'failed', listener: (job: Job<T>, error: Error) => void): this;
+    once(event: 'progress', listener: (job: Job<T> | null, progress: number) => void): this;
+    once(event: 'stalled', listener: (jobId: string, reason: string) => void): this;
+    once(event: 'error', listener: (error: Error) => void): this;
+    once(event: 'cancelled', listener: (data: {
+        jobId: string;
+        reason: string;
+    }) => void): this;
+    once(event: 'log', listener: (job: Job<T>, message: string) => void): this;
+    off(event: 'ready' | 'drained' | 'closed', listener: () => void): this;
+    off(event: 'active', listener: (job: Job<T>) => void): this;
+    off(event: 'completed', listener: (job: Job<T>, result: R) => void): this;
+    off(event: 'failed', listener: (job: Job<T>, error: Error) => void): this;
+    off(event: 'progress', listener: (job: Job<T> | null, progress: number) => void): this;
+    off(event: 'stalled', listener: (jobId: string, reason: string) => void): this;
+    off(event: 'error', listener: (error: Error) => void): this;
+    off(event: 'cancelled', listener: (data: {
+        jobId: string;
+        reason: string;
+    }) => void): this;
+    off(event: 'log', listener: (job: Job<T>, message: string) => void): this;
+    constructor(name: string, processor: Processor<T, R>, options?: WorkerOptions);
+    protected trackDelivery(item: PulledJob): WorkerDelivery;
+    protected currentDelivery(jobId: string): WorkerDelivery | undefined;
+    protected isCurrentDelivery(delivery: WorkerDelivery): boolean;
+    protected isActiveDelivery(delivery: WorkerDelivery): boolean;
+    protected beginDelivery(delivery: WorkerDelivery): void;
+    protected queueAckCandidate(delivery: WorkerDelivery): void;
+    protected retireAckCandidate(delivery: WorkerDelivery): void;
+    protected finishDelivery(delivery: WorkerDelivery): void;
+    protected forgetDelivery(delivery: WorkerDelivery): void;
+    protected hasActiveDelivery(jobId: string): boolean;
+    protected activeDeliveryIds(): IterableIterator<string>;
+    protected clearDeliveries(): void;
+    protected createAbortController(jobId: string): AbortController;
+    protected releaseAbortController(jobId: string, controller: AbortController): void;
+    protected abortJob(jobId: string, reason: string): boolean;
+    protected clearPollTimer(): void;
+    private reachableUnqueuedAckCount;
+    abstract run(): void;
+    protected abstract registerWithServer(): void;
+    protected abstract getHeartbeatDeps(): HeartbeatDeps;
+    protected abstract startWorkerHeartbeat(): void;
+    protected abstract poll(): void;
+}

package/dist/types/src/client/worker/types/index.d.ts

@@ -0,0 +1,5 @@
+export type { ExtendedWorkerOptions } from "./options.js";
+export type { ManualJob } from "./manual.js";
+export type { ManualMove, PendingTransitionSettlement } from "./outcome.js";
+export type { FailureContext, ProcessorConfig } from "./processor.js";
+export type { PendingAck, TcpConnection } from "./transport.js";

package/dist/types/src/client/worker/types/manual.d.ts

@@ -0,0 +1,7 @@
+import type { Job as InternalJob } from "../../../domain/types/job.js";
+/** Job returned by Worker.getNextJob() for explicit manual processing. */
+export type ManualJob<T = unknown> = Omit<InternalJob, 'data'> & {
+    readonly data: T;
+    /** Broker lease token when WorkerOptions.useLocks is enabled. */
+    readonly token?: string;
+};

package/dist/types/src/client/worker/types/options.d.ts

@@ -0,0 +1,26 @@
+import type { BatchWorkerOptions, ConnectionOptions, GroupWorkerOptions } from "../../types.js";
+export interface ExtendedWorkerOptions {
+    concurrency: number;
+    autorun: boolean;
+    heartbeatInterval: number;
+    batchSize: number;
+    pollTimeout: number;
+    embedded: boolean;
+    useLocks: boolean;
+    skipLockRenewal: boolean;
+    skipStalledCheck: boolean;
+    drainDelay: number;
+    lockDuration: number;
+    maxStalledCount: number;
+    removeOnComplete?: boolean | number | {
+        age?: number;
+        count?: number;
+    };
+    removeOnFail?: boolean | number | {
+        age?: number;
+        count?: number;
+    };
+    connection?: ConnectionOptions;
+    group?: GroupWorkerOptions;
+    batch?: Required<BatchWorkerOptions>;
+}

package/dist/types/src/client/worker/types/outcome.d.ts

@@ -0,0 +1,23 @@
+export type PendingTransitionSettlement = {
+    status: 'applied';
+} | {
+    status: 'ignored';
+} | {
+    status: 'failed';
+    error: Error;
+};
+export interface ManualMove {
+    result: {
+        type: 'completed';
+        value?: unknown;
+    } | {
+        type: 'failed';
+        error?: Error;
+    } | {
+        type: 'ignored' | 'transitioned';
+    } | {
+        type: 'pending-transition';
+        context: 'discard';
+        pending: Promise<PendingTransitionSettlement>;
+    } | null;
+}

package/dist/types/src/client/worker/types/processor.d.ts

@@ -0,0 +1,25 @@
+import type { EventEmitter } from 'events';
+import type { FlowJobData, Job, Processor } from "../../types.js";
+import type { AckBatcher } from "../ackBatcher.js";
+import type { TcpConnection } from "./transport.js";
+export interface ProcessorConfig<T, R> {
+    name: string;
+    processor: Processor<T, R>;
+    embedded: boolean;
+    tcp: TcpConnection | null;
+    ackBatcher: AckBatcher;
+    emitter: EventEmitter;
+    token?: string | null;
+    removeOnComplete?: boolean;
+    removeOnFail?: boolean;
+    onOutcome?: (succeeded: boolean) => void;
+    onAckQueued?: () => void;
+    onAckUnavailable?: () => void;
+    shouldAbandonOutcome?: () => boolean;
+    abortController?: AbortController;
+}
+export interface FailureContext<T extends FlowJobData> {
+    job: Job<T>;
+    jobIdStr: string;
+    token?: string | null;
+}

package/dist/types/src/client/worker/types/transport.d.ts

@@ -0,0 +1,11 @@
+export interface PendingAck {
+    id: string;
+    result: unknown;
+    token?: string;
+    removeOnComplete?: boolean;
+    resolve: (applied: boolean) => void;
+    reject: (error: Error) => void;
+}
+export interface TcpConnection {
+    send: (command: Record<string, unknown>) => Promise<Record<string, unknown>>;
+}

package/dist/types/src/client/worker/worker.d.ts

@@ -0,0 +1,6 @@
+/** Public Worker façade. Runtime implementation lives in worker/runtime/. */
+import { WorkerExecution } from "./runtime/execution.js";
+import { RateLimitError } from "../errors.js";
+export declare class Worker<T = unknown, R = unknown> extends WorkerExecution<T, R> {
+    static RateLimitError(): RateLimitError;
+}

package/dist/types/src/client/worker/workerHeartbeat.d.ts

@@ -0,0 +1,15 @@
+/**
+ * WorkerHeartbeat - Heartbeat sending for TCP worker connections
+ * Sends periodic heartbeats to keep locks alive and prevent stall detection
+ */
+import type { EventEmitter } from 'events';
+import type { TcpConnection } from "./types/index.js";
+export interface HeartbeatDeps {
+    readonly pulledJobIds: Set<string>;
+    readonly jobTokens: Map<string, string>;
+    readonly tcp: TcpConnection | null;
+    readonly useLocks: boolean;
+    readonly emitter: EventEmitter;
+}
+export declare function startHeartbeat(deps: HeartbeatDeps, intervalMs: number): ReturnType<typeof setInterval>;
+export declare function sendHeartbeat(deps: HeartbeatDeps): Promise<void>;

package/dist/types/src/client/worker/workerPull.d.ts

@@ -0,0 +1,24 @@
+/**
+ * WorkerPull - Job pulling functions for embedded and TCP modes
+ * Handles batch pulling with optional lock-based ownership
+ */
+import type { Job as InternalJob } from "../../domain/types/job.js";
+import type { TcpConnection } from "./types/index.js";
+import type { GroupWorkerOptions } from "../types.js";
+export interface PullConfig {
+    readonly name: string;
+    readonly workerId: string;
+    readonly useLocks: boolean;
+    readonly pollTimeout: number;
+    /** Lock TTL in ms to request from the server on a lock-based pull. */
+    readonly lockDuration?: number;
+    readonly group?: GroupWorkerOptions;
+}
+export declare function pullEmbedded(config: PullConfig, count: number): Promise<Array<{
+    job: InternalJob;
+    token: string | null;
+}>>;
+export declare function pullTcp(config: PullConfig, tcp: TcpConnection, count: number, closing: boolean): Promise<Array<{
+    job: InternalJob;
+    token: string | null;
+}>>;

package/dist/types/src/client/worker/workerRateLimiter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * WorkerRateLimiter - Rate limiting for worker job processing
+ * BullMQ v5 compatible sliding window rate limiter
+ *
+ * Uses a head-pointer approach instead of Array.filter() for O(1) amortized
+ * token expiration. Tokens are always pushed in chronological order, so
+ * expired tokens are always at the front — we just advance the head pointer.
+ */
+import type { RateLimiterOptions } from "../types.js";
+export declare class WorkerRateLimiter {
+    private readonly limiter;
+    private limiterTokens;
+    private head;
+    private rateLimitExpiration;
+    constructor(limiter: RateLimiterOptions | null);
+    /**
+     * Check if rate limiter allows processing another job.
+     * Returns true if we can process, false if rate limited.
+     * O(1) amortized — advances head pointer past expired tokens.
+     */
+    canProcessWithinLimit(): boolean;
+    /** Atomically reserve starts in the current window. */
+    tryAcquire(count?: number): boolean;
+    /** Record a synthetic start, retained for diagnostics and focused unit tests. */
+    recordJobForLimiter(): void;
+    /** Number of starts that can be admitted without waiting. */
+    getAvailableSlots(): number;
+    /**
+     * Get time until rate limiter allows next job (ms).
+     * Returns 0 if not rate limited.
+     * O(1) — oldest active token is at this.limiterTokens[this.head].
+     */
+    getTimeUntilNextSlot(): number;
+    /** Get rate limiter info (for debugging/monitoring). */
+    getRateLimiterInfo(): {
+        current: number;
+        max: number;
+        duration: number;
+    } | null;
+    /**
+     * Apply rate limiting (BullMQ v5 compatible).
+     * The worker will not process jobs until the rate limit expires.
+     */
+    rateLimit(expireTimeMs: number): void;
+    /** Check if worker is currently rate limited. */
+    isRateLimited(): boolean;
+    /** Number of active (non-expired) tokens. */
+    private activeCount;
+    /** Advance head pointer past expired tokens. Compact when head > half the array. */
+    private evictExpired;
+}

package/dist/types/src/client/worker.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Worker - Re-exports from worker module
+ * @deprecated Import from './worker' instead
+ */
+export { Worker } from "./worker/worker.js";
+export type { ManualJob } from "./worker/types/index.js";

package/dist/types/src/client/workflow/admission.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Whether a node job may run, decided as a pure function.
+ *
+ * WHY THIS FILE EXISTS. Job delivery is at-least-once, so the same node job arrives
+ * twice as a matter of course: a queue retry, a `recover()` over a run the live engine
+ * is already driving, a timeout re-check racing a signal. Three guards decide whether
+ * an arrival is the real one, and when one of them was missing a duplicate re-ran the
+ * node AND every node after it, giving one execution two independent advance chains,
+ * doubled side effects, and a final state of `completed` that hid the whole thing.
+ *
+ * That defect was found by the state-machine model after a long campaign, because the
+ * decision lived inside an async method that also read SQLite and dispatched work: the
+ * only way to observe it was to reproduce the race. As a function of its inputs it is
+ * a table, and a table can be enumerated.
+ *
+ * The three rejections are deliberately distinguished rather than collapsed into a
+ * boolean. `stale-cursor` and `already-in-flight` mean very different things to anyone
+ * reading a log: one is an arrival for work the run has already moved past, the other
+ * is a second arrival for work in progress right now.
+ */
+import type { Execution } from "./types.js";
+export type Admission = {
+    kind: 'run';
+} | {
+    kind: 'reject';
+    /**
+     * `missing`           the execution is not in the store at all
+     * `not-live`          it is terminal, compensating or parked, so no node may run
+     * `stale-cursor`      the job names a node the run has already left
+     * `already-in-flight` this exact node is executing in this process right now
+     */
+    reason: 'missing' | 'not-live' | 'stale-cursor' | 'already-in-flight';
+};
+/** States in which a node job may execute. Anything else is not a live run. */
+export declare function isLive(state: Execution['state']): boolean;
+/**
+ * Decide whether the job for `nodeIndex` of `exec` may run.
+ *
+ * `inFlight` is the set of `<executionId>:<nodeIndex>` claims held by this process.
+ * It is passed in rather than read from module state so the decision stays a function
+ * of its arguments.
+ */
+export declare function decideAdmission(exec: Execution | null, nodeIndex: number, inFlight: ReadonlySet<string>): Admission;
+/** The claim a running node holds. One string, one place that builds it. */
+export declare function claimKey(executionId: string, nodeIndex: number): string;

package/dist/types/src/client/workflow/clock.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The engine's only source of time and randomness.
+ *
+ * WHY THIS EXISTS. Every defect this engine has shipped in a crash or concurrency
+ * window took a property-based campaign roughly one run in eleven to surface, and the
+ * seed that produced it did NOT reproduce it: the seed drove the sequence of commands,
+ * while the interleaving came from real timers and real process death. A failing seed
+ * you cannot replay is a bug report you cannot act on.
+ *
+ * With every `Date.now()`, `Math.random()` and `setTimeout` routed through here, a
+ * simulated clock makes a seed drive the interleaving too, so a failure replays
+ * exactly, every time, and a fix can be proven rather than hoped for.
+ *
+ * WHAT THIS IS NOT. It does not make the engine deterministic on its own: SQLite, the
+ * queue's own worker loop and the OS scheduler are still outside. It removes the
+ * engine's own contribution, which is the part the engine can be held responsible for.
+ *
+ * The default is the real clock, and it is installed by default, so nothing changes
+ * for anyone who does not ask for a simulated one.
+ */
+export interface Clock {
+    /** Milliseconds since the epoch. */
+    now(): number;
+    /** Schedule `fn` after `ms`. The handle is whatever `clear` accepts. */
+    setTimeout(fn: () => void, ms: number): TimerHandle;
+    clearTimeout(handle: TimerHandle): void;
+    /** A number in [0, 1). Used for retry jitter. */
+    random(): number;
+    /** Replayable entropy; cryptographically strong on the real clock. */
+    randomBytes(length: number): Uint8Array;
+}
+export interface TimerHandle {
+    /** Real timers can be unref'd so a pending one does not hold the process open. */
+    unref?(): void;
+}
+/** The clock the engine reads. Real unless a simulation installed its own. */
+export declare function clock(): Clock;
+/**
+ * Install a clock, returning the previous one so a test can restore it.
+ *
+ * Deliberately process-global rather than threaded through every call site: the
+ * alternative is a `Clock` parameter on roughly forty internal functions, which is a
+ * large diff through code whose correctness was hard-won, for no gain in a runtime
+ * that already keeps one engine per process.
+ */
+export declare function setClock(next: Clock): Clock;
+/** Restore the real clock. */
+export declare function resetClock(): void;
+/**
+ * A clock where time only moves when the simulation says so.
+ *
+ * `advance` fires every timer due at or before the new instant, in due order, and
+ * timers scheduled BY those callbacks are picked up in the same advance, so a chain of
+ * re-armed timeouts settles the way it would in real time rather than needing one
+ * `advance` per link. Ties break by insertion order, so a seed replays identically.
+ */
+export declare function simulatedClock(seed: number, startAt?: number): Clock & {
+    advance(ms: number): number;
+    pending(): number;
+};

package/dist/types/src/client/workflow/compensationChild.d.ts

@@ -0,0 +1,33 @@
+/** Nested-saga compensation. */
+import type { LostCompensationClaim } from "./compensationClaim.js";
+import type { WorkflowEmitter } from "./emitter.js";
+import type { WorkflowStore } from "./store.js";
+import type { Execution, StepRecord } from "./types.js";
+import type { Workflow } from "./workflow.js";
+export interface ChildUnwindRequest {
+    exec: Execution;
+    workflow: Workflow;
+    store: WorkflowStore;
+    emitter: WorkflowEmitter | null;
+    workflows?: Map<string, Workflow>;
+    retryFailed?: boolean;
+    assertActive: () => void;
+}
+export type ChildUnwind = (request: ChildUnwindRequest) => Promise<'ran' | LostCompensationClaim>;
+export interface UnwindChildRequest {
+    record: StepRecord;
+    store: WorkflowStore;
+    emitter: WorkflowEmitter | null;
+    workflows?: Map<string, Workflow>;
+    runChild: ChildUnwind;
+    retryFailed?: boolean;
+    assertActive: () => void;
+}
+/** Run the child workflow's own unwind and propagate every uncertain outcome. */
+export declare function unwindChild(request: UnwindChildRequest): Promise<void>;
+export declare class AbandonedCompensationError extends Error {
+    constructor(workflowName: string, executionId: string);
+}
+export declare class CommittedChildError extends Error {
+    constructor(workflowName: string, executionId: string);
+}

package/dist/types/src/client/workflow/compensationClaim.d.ts

@@ -0,0 +1,11 @@
+/** Process-local ownership for one workflow unwind. */
+export interface AcquiredCompensationClaim {
+    readonly kind: 'acquired';
+    release(): void;
+}
+export interface LostCompensationClaim {
+    readonly kind: 'claim-lost';
+    readonly sameOwner: boolean;
+    readonly settled: Promise<void>;
+}
+export declare function acquireCompensationClaim(executionId: string, owner: object): AcquiredCompensationClaim | LostCompensationClaim;

package/dist/types/src/client/workflow/compensationPass.d.ts

@@ -0,0 +1,17 @@
+/** One checkpointed compensation pass. */
+import { type ChildUnwind } from "./compensationChild.js";
+import type { WorkflowEmitter } from "./emitter.js";
+import type { WorkflowStore } from "./store.js";
+import type { Execution, StepRecord } from "./types.js";
+import type { Workflow } from "./workflow.js";
+export interface UnwindPass {
+    exec: Execution;
+    wf: Workflow;
+    store: WorkflowStore;
+    emitter: WorkflowEmitter | null;
+    eligible: [string, StepRecord][];
+    workflows?: Map<string, Workflow>;
+    retryFailed?: boolean;
+    assertActive: () => void;
+}
+export declare function unwind(pass: UnwindPass, runChild: ChildUnwind): Promise<void>;