bunqueue 2.8.49 → 2.8.50

package/dist/client/flowJobTypes.js

@@ -0,0 +1,6 @@
+export function assertFlowTcpOk(response, operation) {
+    if (response.ok === true)
+        return;
+    const detail = typeof response.error === 'string' ? response.error : `${operation} failed`;
+    throw new Error(detail);
+}

package/dist/client/flowLegacyPlan.d.ts

@@ -0,0 +1,16 @@
+import { type JobId } from '../domain/types/job';
+import type { AtomicFlowBatchInput } from '../domain/types/flow';
+import type { FlowStep } from './flowTypes';
+export declare function planChain<T>(steps: FlowStep<T>[]): {
+    batch: AtomicFlowBatchInput;
+    ids: JobId[];
+};
+export declare function planBulkThen<T>(parallel: FlowStep<T>[], final: FlowStep<T>): {
+    batch: AtomicFlowBatchInput;
+    parallelIds: JobId[];
+    finalId: JobId;
+};
+export declare function planTree<T>(root: FlowStep<T>): {
+    batch: AtomicFlowBatchInput;
+    ids: JobId[];
+};

package/dist/client/flowLegacyPlan.js

@@ -0,0 +1,118 @@
+import { generateJobId, jobId } from '../domain/types/job';
+import { flowJobInput } from './flowOptions';
+const MAX_FLOW_DEPTH = 100;
+const MAX_FLOW_JOBS = 10_000;
+function validateStep(step, depth = 0) {
+    if (!step || typeof step !== 'object')
+        throw new Error('flow step must be an object');
+    if (!step.name || typeof step.name !== 'string' || step.name.length > 256) {
+        throw new Error('flow job name must be a non-empty string of at most 256 characters');
+    }
+    if (!step.queueName || typeof step.queueName !== 'string') {
+        throw new Error('flow queueName is required');
+    }
+    if (depth > MAX_FLOW_DEPTH) {
+        throw new Error(`flow exceeds the ${MAX_FLOW_DEPTH} level depth limit`);
+    }
+    if (step.children !== undefined && !Array.isArray(step.children)) {
+        throw new Error('flow children must be an array');
+    }
+    if (typeof step.data !== 'object' || step.data === null || Array.isArray(step.data)) {
+        throw new Error('flow job data must be an object');
+    }
+    for (const key of Object.keys(step.data)) {
+        if (key === 'name' || key.startsWith('__')) {
+            throw new Error(`flow job data key is reserved: ${key}`);
+        }
+    }
+}
+function validateFlatSteps(steps) {
+    if (steps.length > MAX_FLOW_JOBS)
+        throw new Error(`flow exceeds the ${MAX_FLOW_JOBS} job limit`);
+    for (const step of steps) {
+        validateStep(step);
+        if ((step.children?.length ?? 0) > 0) {
+            throw new Error('nested children are only supported by addTree');
+        }
+    }
+}
+function allocate(step, ids) {
+    const raw = step.opts?.jobId;
+    if (raw !== undefined && (!raw || raw.includes(':'))) {
+        throw new Error('flow jobId must be non-empty and cannot contain a colon');
+    }
+    const id = raw === undefined ? generateJobId() : jobId(raw);
+    if (ids.has(String(id)))
+        throw new Error(`duplicate flow job id: ${String(id)}`);
+    ids.add(String(id));
+    return id;
+}
+function dataFor(step, internal) {
+    return { ...step.data, name: step.name, ...internal };
+}
+export function planChain(steps) {
+    validateFlatSteps(steps);
+    const seen = new Set();
+    const ids = steps.map((step) => allocate(step, seen));
+    const jobs = steps.map((step, index) => {
+        const dependency = index > 0 ? ids[index - 1] : undefined;
+        return {
+            id: ids[index],
+            queue: step.queueName,
+            input: flowJobInput(dataFor(step, { __flowParentId: dependency ? String(dependency) : null }), step.opts ?? {}, { dependsOn: dependency ? [dependency] : undefined }),
+        };
+    });
+    return { batch: { jobs }, ids };
+}
+export function planBulkThen(parallel, final) {
+    validateFlatSteps([...parallel, final]);
+    const seen = new Set();
+    const parallelIds = parallel.map((step) => allocate(step, seen));
+    const finalId = allocate(final, seen);
+    const parallelJobs = parallel.map((step, index) => ({
+        id: parallelIds[index],
+        queue: step.queueName,
+        input: flowJobInput(dataFor(step, {
+            __parentId: String(finalId),
+            __parentQueue: final.queueName,
+        }), step.opts ?? {}, { parentId: finalId }),
+    }));
+    const finalJob = {
+        id: finalId,
+        queue: final.queueName,
+        input: flowJobInput(dataFor(final, {
+            __flowParentIds: parallelIds.map(String),
+            __childrenIds: parallelIds.map(String),
+        }), final.opts ?? {}, {
+            dependsOn: parallelIds.length > 0 ? parallelIds : undefined,
+            childrenIds: parallelIds.length > 0 ? parallelIds : undefined,
+        }),
+    };
+    return { batch: { jobs: [...parallelJobs, finalJob] }, parallelIds, finalId };
+}
+export function planTree(root) {
+    const jobs = [];
+    const ids = [];
+    const allocated = new Set();
+    const seen = new WeakSet();
+    const visit = (step, dependency, depth = 0) => {
+        validateStep(step, depth);
+        if (seen.has(step))
+            throw new Error('flow contains a cycle or shared node');
+        seen.add(step);
+        if (jobs.length >= MAX_FLOW_JOBS) {
+            throw new Error(`flow exceeds the ${MAX_FLOW_JOBS} job limit`);
+        }
+        const id = allocate(step, allocated);
+        ids.push(id);
+        jobs.push({
+            id,
+            queue: step.queueName,
+            input: flowJobInput(dataFor(step, { __flowParentId: dependency ? String(dependency) : null }), step.opts ?? {}, { dependsOn: dependency ? [dependency] : undefined }),
+        });
+        for (const child of step.children ?? [])
+            visit(child, id, depth + 1);
+    };
+    visit(root);
+    return { batch: { jobs }, ids };
+}

package/dist/client/flowOptions.d.ts

@@ -0,0 +1,10 @@
+import type { JobInput, JobId } from '../domain/types/job';
+import type { JobOptions } from './types';
+/** Options intentionally unsupported by BullMQ-compatible atomic flows. */
+export declare function assertAtomicFlowOptions(opts: JobOptions): void;
+/** Convert public JobOptions into the domain input used by the atomic broker command. */
+export declare function flowJobInput(data: unknown, opts: JobOptions, links?: {
+    parentId?: JobId;
+    dependsOn?: JobId[];
+    childrenIds?: JobId[];
+}): JobInput;

package/dist/client/flowOptions.js

@@ -0,0 +1,44 @@
+function removeFlag(value) {
+    return typeof value === 'boolean' ? value : false;
+}
+/** Options intentionally unsupported by BullMQ-compatible atomic flows. */
+export function assertAtomicFlowOptions(opts) {
+    if (opts.repeat)
+        throw new Error('repeat is not supported inside an atomic flow');
+    if (opts.deduplication) {
+        throw new Error('deduplication is not supported inside an atomic flow');
+    }
+    if (opts.debounce)
+        throw new Error('debounce is not supported inside an atomic flow');
+    if (opts.parent)
+        throw new Error('FlowProducer owns parent links; opts.parent is not allowed');
+}
+/** Convert public JobOptions into the domain input used by the atomic broker command. */
+export function flowJobInput(data, opts, links = {}) {
+    assertAtomicFlowOptions(opts);
+    return {
+        data,
+        priority: opts.priority,
+        delay: opts.delay,
+        maxAttempts: opts.attempts,
+        backoff: opts.backoff,
+        timeout: opts.timeout,
+        customId: opts.jobId,
+        dependsOn: links.dependsOn,
+        childrenIds: links.childrenIds,
+        parentId: links.parentId,
+        lifo: opts.lifo,
+        removeOnComplete: removeFlag(opts.removeOnComplete),
+        removeOnFail: removeFlag(opts.removeOnFail),
+        durable: opts.durable,
+        stallTimeout: opts.stallTimeout,
+        stackTraceLimit: opts.stackTraceLimit,
+        keepLogs: opts.keepLogs,
+        sizeLimit: opts.sizeLimit,
+        failParentOnFailure: opts.failParentOnFailure,
+        removeDependencyOnFailure: opts.removeDependencyOnFailure,
+        continueParentOnFailure: opts.continueParentOnFailure,
+        ignoreDependencyOnFailure: opts.ignoreDependencyOnFailure,
+        timestamp: opts.timestamp,
+    };
+}

package/dist/client/flowPlan.d.ts

@@ -0,0 +1,16 @@
+import { type JobId } from '../domain/types/job';
+import type { AtomicFlowBatchInput } from '../domain/types/flow';
+import type { FlowJob, FlowOpts } from './flowTypes';
+export interface PlannedFlowNode<T> {
+    readonly id: JobId;
+    readonly name: string;
+    readonly queueName: string;
+    readonly data: T | undefined;
+    readonly children?: PlannedFlowNode<T>[];
+}
+export interface FlowPlan<T> {
+    readonly batch: AtomicFlowBatchInput;
+    readonly roots: PlannedFlowNode<T>[];
+}
+/** Compile one or more trees into a fully-resolved graph before contacting the broker. */
+export declare function planFlows<T>(flows: FlowJob<T>[], options?: FlowOpts): FlowPlan<T>;

package/dist/client/flowPlan.js

@@ -0,0 +1,93 @@
+import { generateJobId, jobId } from '../domain/types/job';
+import { flowJobInput } from './flowOptions';
+const MAX_FLOW_DEPTH = 100;
+const MAX_FLOW_JOBS = 10_000;
+function validateNodeShape(node, depth) {
+    if (!node || typeof node !== 'object')
+        throw new Error('flow node must be an object');
+    if (!node.name || typeof node.name !== 'string')
+        throw new Error('flow job name is required');
+    if (!node.queueName || typeof node.queueName !== 'string') {
+        throw new Error('flow queueName is required');
+    }
+    if (depth > MAX_FLOW_DEPTH) {
+        throw new Error(`flow exceeds the ${MAX_FLOW_DEPTH} level depth limit`);
+    }
+    if (node.children !== undefined && !Array.isArray(node.children)) {
+        throw new Error('flow children must be an array');
+    }
+    if (node.data !== undefined) {
+        if (typeof node.data !== 'object' || node.data === null || Array.isArray(node.data)) {
+            throw new Error('flow job data must be an object');
+        }
+        for (const key of Object.keys(node.data)) {
+            if (key === 'name' || key.startsWith('__')) {
+                throw new Error(`flow job data key is reserved: ${key}`);
+            }
+        }
+    }
+}
+function plannedId(node) {
+    const custom = node.opts?.jobId;
+    if (custom === undefined)
+        return generateJobId();
+    if (!custom || custom.includes(':')) {
+        throw new Error('flow jobId must be non-empty and cannot contain a colon');
+    }
+    return jobId(custom);
+}
+/** Compile one or more trees into a fully-resolved graph before contacting the broker. */
+export function planFlows(flows, options) {
+    const jobs = [];
+    const ids = new Set();
+    const seen = new WeakSet();
+    let nodeCount = 0;
+    const visit = (node, parent, depth) => {
+        validateNodeShape(node, depth);
+        if (seen.has(node))
+            throw new Error('flow contains a cycle or shared node');
+        seen.add(node);
+        nodeCount++;
+        if (nodeCount > MAX_FLOW_JOBS) {
+            throw new Error(`flow exceeds the ${MAX_FLOW_JOBS} job limit`);
+        }
+        const id = plannedId(node);
+        if (ids.has(String(id)))
+            throw new Error(`duplicate flow job id: ${String(id)}`);
+        ids.add(String(id));
+        const children = (node.children ?? []).map((child) => visit(child, { id, queue: node.queueName }, depth + 1));
+        const childIds = children.map((child) => child.id);
+        const defaults = options?.queuesOptions?.[node.queueName];
+        const opts = defaults ? { ...defaults, ...node.opts } : (node.opts ?? {});
+        const internalData = {
+            ...node.data,
+            name: node.name,
+        };
+        if (parent) {
+            internalData.__parentId = String(parent.id);
+            internalData.__parentQueue = parent.queue;
+        }
+        if (childIds.length > 0)
+            internalData.__childrenIds = childIds.map(String);
+        jobs.push({
+            id,
+            queue: node.queueName,
+            input: flowJobInput(internalData, opts, {
+                parentId: parent?.id,
+                dependsOn: childIds.length > 0 ? childIds : undefined,
+                childrenIds: childIds.length > 0 ? childIds : undefined,
+            }),
+        });
+        return {
+            id,
+            name: node.name,
+            queueName: node.queueName,
+            data: node.data,
+            children: children.length > 0 ? children : undefined,
+        };
+    };
+    return {
+        batch: { jobs },
+        roots: flows.map((flow) => visit(flow, undefined, 0)),
+    };
+}

package/dist/client/flowPush.js

@@ -169,7 +169,10 @@ export async function pushJobWithParent(ctx, params) {
     // Update children with real parent ID (like embedded mode does)
     if (childIds.length > 0) {
         for (const childId of childIds) {
-            await ctx.tcp.send({ cmd: 'UpdateParent', childId, parentId: parentJobId });
+            const update = await ctx.tcp.send({ cmd: 'UpdateParent', childId, parentId: parentJobId });
+            if (update.ok !== true) {
+                throw new Error(typeof update.error === 'string' ? update.error : `Failed to link child ${childId}`);
+            }
         }
     }
     return parentJobId;

package/dist/client/flowReader.d.ts

@@ -0,0 +1,10 @@
+import type { FlowJobCallbacks } from './flowJobTypes';
+import type { GetFlowOpts, JobNode } from './flowTypes';
+import type { TcpConnectionPool } from './tcpPool';
+export interface FlowReaderContext {
+    embedded: boolean;
+    tcp: TcpConnectionPool | null;
+    buildCallbacks: (queueName: string) => FlowJobCallbacks;
+}
+/** Read a flow without silently truncating transport or topology errors. */
+export declare function readFlow<T>(context: FlowReaderContext, opts: GetFlowOpts): Promise<JobNode<T> | null>;

package/dist/client/flowReader.js

@@ -0,0 +1,147 @@
+import { jobId } from '../domain/types/job';
+import { createFlowJobObject, extractUserDataFromInternal } from './flowJobFactory';
+import { getSharedManager } from './manager';
+function traversalLimit(value, name) {
+    if (value === undefined)
+        return Infinity;
+    if (value === Infinity)
+        return value;
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`${name} must be a non-negative integer`);
+    }
+    return value;
+}
+function childIdsFromTcp(job) {
+    const data = typeof job.data === 'object' && job.data !== null ? job.data : {};
+    const raw = job.childrenIds ?? data.__childrenIds;
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw) || raw.some((id) => typeof id !== 'string')) {
+        throw new Error(`Flow job ${String(job.id)} has invalid childrenIds`);
+    }
+    return raw;
+}
+function assertNoCycle(id, ancestors) {
+    if (ancestors.has(id))
+        throw new Error(`Flow topology contains a cycle at job ${id}`);
+    const next = new Set(ancestors);
+    next.add(id);
+    return next;
+}
+function assertParentLink(id, parentId, data, expected) {
+    if (!expected)
+        return;
+    if (String(parentId) !== expected.id ||
+        data.__parentId !== expected.id ||
+        data.__parentQueue !== expected.queue) {
+        throw new Error(`Flow child ${id} does not point back to parent ${expected.id}`);
+    }
+}
+async function buildEmbeddedNode(context, job, traversal) {
+    const { depth, maxChildren, ancestors, expectedParent } = traversal;
+    const id = String(job.id);
+    const nextAncestors = assertNoCycle(id, ancestors);
+    const data = job.data;
+    assertParentLink(id, job.parentId, data, expectedParent);
+    const name = typeof data.name === 'string' ? data.name : 'default';
+    const node = {
+        job: createFlowJobObject(id, name, extractUserDataFromInternal(data), job.queue, {
+            callbacks: context.buildCallbacks(job.queue),
+            snapshot: job,
+        }),
+    };
+    if (depth <= 0 || job.childrenIds.length === 0 || maxChildren === 0)
+        return node;
+    const childIds = maxChildren === Infinity ? job.childrenIds : job.childrenIds.slice(0, maxChildren);
+    const children = [];
+    for (const childId of childIds) {
+        const child = await getSharedManager().getJob(childId);
+        if (!child)
+            throw new Error(`Flow child job ${String(childId)} not found`);
+        children.push(await buildEmbeddedNode(context, child, {
+            depth: depth - 1,
+            maxChildren,
+            ancestors: nextAncestors,
+            expectedParent: { id, queue: job.queue },
+        }));
+    }
+    if (children.length > 0)
+        node.children = children;
+    return node;
+}
+async function getTcpJob(tcp, id, root) {
+    const response = await tcp.send({ cmd: 'GetJob', id });
+    if (response.ok !== true) {
+        if (root && response.error === 'Job not found')
+            return null;
+        throw new Error(typeof response.error === 'string' ? response.error : `Unable to fetch flow job ${id}`);
+    }
+    if (!response.job || typeof response.job !== 'object') {
+        throw new Error(`GetJob returned no snapshot for flow job ${id}`);
+    }
+    return response.job;
+}
+async function buildTcpNode(context, job, traversal) {
+    const { depth, maxChildren, ancestors, expectedParent } = traversal;
+    const tcp = context.tcp;
+    if (!tcp)
+        throw new Error('TCP connection not initialized');
+    const id = String(job.id);
+    const queueName = String(job.queue);
+    const nextAncestors = assertNoCycle(id, ancestors);
+    const data = typeof job.data === 'object' && job.data !== null ? job.data : {};
+    assertParentLink(id, job.parentId, data, expectedParent);
+    const name = typeof data.name === 'string' ? data.name : 'default';
+    const node = {
+        job: createFlowJobObject(id, name, extractUserDataFromInternal(data), queueName, {
+            callbacks: context.buildCallbacks(queueName),
+            snapshot: job,
+        }),
+    };
+    const childIds = childIdsFromTcp(job);
+    if (depth <= 0 || childIds.length === 0 || maxChildren === 0)
+        return node;
+    const selected = maxChildren === Infinity ? childIds : childIds.slice(0, maxChildren);
+    const children = [];
+    for (const childId of selected) {
+        const child = await getTcpJob(tcp, childId, false);
+        if (!child)
+            throw new Error(`Flow child job ${childId} not found`);
+        children.push(await buildTcpNode(context, child, {
+            depth: depth - 1,
+            maxChildren,
+            ancestors: nextAncestors,
+            expectedParent: { id, queue: queueName },
+        }));
+    }
+    if (children.length > 0)
+        node.children = children;
+    return node;
+}
+/** Read a flow without silently truncating transport or topology errors. */
+export async function readFlow(context, opts) {
+    const depth = traversalLimit(opts.depth, 'depth');
+    const maxChildren = traversalLimit(opts.maxChildren, 'maxChildren');
+    if (context.embedded) {
+        const job = await getSharedManager().getJob(jobId(opts.id));
+        if (!job || job.queue !== opts.queueName)
+            return null;
+        return buildEmbeddedNode(context, job, {
+            depth,
+            maxChildren,
+            ancestors: new Set(),
+            expectedParent: null,
+        });
+    }
+    if (!context.tcp)
+        throw new Error('TCP connection not initialized');
+    const job = await getTcpJob(context.tcp, opts.id, true);
+    if (!job || job.queue !== opts.queueName)
+        return null;
+    return buildTcpNode(context, job, {
+        depth,
+        maxChildren,
+        ancestors: new Set(),
+        expectedParent: null,
+    });
+}

package/dist/client/jobHelpers.js

@@ -81,6 +81,8 @@ export function buildJobOpts(job) {
         sizeLimit: job.sizeLimit ?? undefined,
         failParentOnFailure: job.failParentOnFailure,
         removeDependencyOnFailure: job.removeDependencyOnFailure,
+        continueParentOnFailure: job.continueParentOnFailure,
+        ignoreDependencyOnFailure: job.ignoreDependencyOnFailure,
         deduplication: job.deduplicationTtl !== null
             ? { id: job.customId ?? '', ttl: job.deduplicationTtl }
             : undefined,

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

@@ -24,8 +24,10 @@ export interface Clock {
     /** 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 and execution ids. */
+    /** 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. */

package/dist/client/workflow/clock.js

@@ -23,6 +23,7 @@ const realClock = {
     setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
     clearTimeout: (h) => globalThis.clearTimeout(h),
     random: () => Math.random(),
+    randomBytes: (length) => crypto.getRandomValues(new Uint8Array(length)),
 };
 let current = realClock;
 /** The clock the engine reads. Real unless a simulation installed its own. */
@@ -58,6 +59,7 @@ export function simulatedClock(seed, startAt = 1_700_000_000_000) {
     let time = startAt;
     let sequence = 0;
     let state = seed >>> 0 || 0x9e3779b9;
+    let entropyState = (seed ^ 0xa5a5a5a5) >>> 0 || 0x6d2b79f5;
     const timers = new Map();
     const random = () => {
         // xorshift32: small, seeded, and identical across runs and platforms.
@@ -69,10 +71,25 @@ export function simulatedClock(seed, startAt = 1_700_000_000_000) {
     return {
         now: () => time,
         random,
+        randomBytes(length) {
+            const bytes = new Uint8Array(length);
+            for (let i = 0; i < length; i++) {
+                entropyState ^= entropyState << 13;
+                entropyState ^= entropyState >>> 17;
+                entropyState ^= entropyState << 5;
+                bytes[i] = entropyState >>> 24;
+            }
+            return bytes;
+        },
         setTimeout(fn, ms) {
             const id = sequence++;
             timers.set(id, { at: time + Math.max(0, ms), order: id, fn });
-            return { unref() { }, __id: id };
+            return {
+                unref() {
+                    // Simulated timers own no process handle.
+                },
+                __id: id,
+            };
         },
         clearTimeout(handle) {
             const id = handle?.__id;

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

@@ -0,0 +1,30 @@
+/** Nested-saga compensation. */
+import type { WorkflowEmitter } from './emitter';
+import type { WorkflowStore } from './store';
+import type { Execution, StepRecord } from './types';
+import type { Workflow } from './workflow';
+export interface ChildUnwindRequest {
+    exec: Execution;
+    workflow: Workflow;
+    store: WorkflowStore;
+    emitter: WorkflowEmitter | null;
+    workflows?: Map<string, Workflow>;
+    retryFailed?: boolean;
+}
+export type ChildUnwind = (request: ChildUnwindRequest) => Promise<'ran' | 'claim-lost'>;
+export interface UnwindChildRequest {
+    record: StepRecord;
+    store: WorkflowStore;
+    emitter: WorkflowEmitter | null;
+    workflows?: Map<string, Workflow>;
+    runChild: ChildUnwind;
+    retryFailed?: boolean;
+}
+/** 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/client/workflow/compensationChild.js

@@ -0,0 +1,65 @@
+/** Nested-saga compensation. */
+import { isLive } from './admission';
+/** Run the child workflow's own unwind and propagate every uncertain outcome. */
+export async function unwindChild(request) {
+    const { record, store, emitter, workflows, runChild, retryFailed } = request;
+    const childId = record.childExecutionId;
+    if (!childId)
+        throw new Error('sub-workflow record carries no child execution id');
+    if (!workflows)
+        throw new Error('workflow registry unavailable to unwind a sub-workflow');
+    const child = store.get(childId);
+    if (!child)
+        throw new Error(`child execution "${childId}" not found`);
+    const childWf = workflows.get(child.workflowName);
+    if (!childWf)
+        throw new Error(`child workflow "${child.workflowName}" is not registered`);
+    if (child.state === 'failed' && child.rollbackStatus === 'stuck') {
+        throw new AbandonedCompensationError(child.workflowName, childId);
+    }
+    // Forward progress and rollback must never write the same child concurrently.
+    if (isLive(child.state)) {
+        throw new Error(`child "${child.workflowName}" (${childId}) is still ${child.state}; ` +
+            'it cannot be rolled back until it stops');
+    }
+    const outcome = await runChild({
+        exec: child,
+        workflow: childWf,
+        store,
+        emitter,
+        workflows,
+        retryFailed,
+    });
+    if (outcome === 'claim-lost') {
+        throw new Error(`child "${child.workflowName}" (${childId}) is being rolled back by another driver; ` +
+            'outcome unknown');
+    }
+    // The recursive unwind may have crossed an async boundary or been driven by
+    // another engine. Interpret the authoritative row, not the snapshot passed in.
+    const settledChild = store.get(childId);
+    if (!settledChild)
+        throw new Error(`child execution "${childId}" disappeared during rollback`);
+    if (settledChild.state === 'failed' && settledChild.rollbackStatus === 'stuck') {
+        throw new AbandonedCompensationError(settledChild.workflowName, childId);
+    }
+    if (settledChild.rollbackStatus === 'stuck') {
+        throw new Error(`child "${settledChild.workflowName}" (${childId}) parked mid-rollback`);
+    }
+    if (settledChild.rollbackStatus === 'not-applicable' && settledChild.committedAt !== undefined) {
+        throw new CommittedChildError(settledChild.workflowName, childId);
+    }
+}
+export class AbandonedCompensationError extends Error {
+    constructor(workflowName, executionId) {
+        super(`child "${workflowName}" (${executionId}) has an explicitly abandoned rollback; ` +
+            'it is terminal and cannot be resumed through an ancestor');
+        this.name = 'AbandonedCompensationError';
+    }
+}
+export class CommittedChildError extends Error {
+    constructor(workflowName, executionId) {
+        super(`child "${workflowName}" (${executionId}) is committed past its pivot; ` +
+            'nothing was rolled back');
+        this.name = 'CommittedChildError';
+    }
+}

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

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