bunqueue 2.8.49 → 2.8.50

package/README.md

@@ -103,7 +103,9 @@ Python, PHP, Go, Rust and Elixir clients speak the same protocol — see
 - **BullMQ-compatible API** — same `Queue`, `Worker`, `QueueEvents`; [migrating takes minutes](https://bunqueue.dev/guide/migration/)
 - **MCP server included** — 73 tools; AI agents get full queue control out of the box
 - **Everything server-side** — retries with backoff, priorities, cron, rate limits, dead letter queue
-- **Up to 630K ops/sec** — [verified benchmarks](https://bunqueue.dev/guide/benchmarks/) with methodology
+- **Measured, operation-specific performance** — 729K jobs/sec internal
+  in-memory batch push, 186K jobs/sec public on-disk Embedded `addBulk`, and
+  159K jobs/sec TCP `PUSHB`; [methodology and distributions](https://bunqueue.dev/guide/benchmarks/)
 
 **Great for:** single-server deployments, AI agents that need a scheduler,
 prototypes and MVPs, embedded use cases (CLI tools, edge, serverless), teams
@@ -120,7 +122,7 @@ failover today. If you already run Redis and BullMQ works for you, keep it.
 | ---------------- | ------------------------------------- | -------------------------------------------- |
 | **How it works** | Queue runs inside your process        | Standalone server, clients connect via TCP   |
 | **Setup**        | `bun add bunqueue`                    | `docker run` or `bunqueue start`             |
-| **Performance**  | 630K ops/sec (bulk push)              | 90K ops/sec (push)                           |
+| **Performance**  | 186K jobs/sec on-disk `addBulk`; 729K internal in-memory batch | 159K jobs/sec TCP `PUSHB`; 17K jobs/sec worker drain |
 | **Best for**     | Single-process apps, CLIs, serverless | Multiple workers, separate producer/consumer |
 | **Scaling**      | Same process only                     | Multiple clients across machines             |
 
@@ -343,13 +345,21 @@ https://github.com/user-attachments/assets/e8a8d38e-b4a6-4dc8-8360-876c0f24d116
 
 ## Performance
 
-| Mode     | Peak Throughput          | Use Case            |
-| -------- | ------------------------ | ------------------- |
-| Embedded | 630K ops/sec (bulk push) | Same process        |
-| TCP      | 90K ops/sec (push)       | Distributed workers |
-
-Run `bun run bench` to verify on your hardware.
-[Benchmark methodology →](https://bunqueue.dev/guide/benchmarks/)
+Native Ryzen 9 9950X3D, Bun 1.3.14; medians from repeated fresh processes:
+
+| Workload | Mode | Median | Persistence |
+| --- | --- | ---: | --- |
+| Internal batched push, 1M jobs | Embedded | 729,395 jobs/sec | In-memory, no `dataPath` |
+| Public sustained `addBulk`, 50K cell | Embedded | 186,384 jobs/sec | On-disk buffered SQLite |
+| `PUSHB`, fresh 50K sample | TCP | 158,779 jobs/sec | On-disk buffered SQLite |
+| No-work worker drain, concurrency 50 | TCP | 17,256 jobs/sec | Full pull/process/ACK |
+| Linear Workflow Engine | Embedded / TCP | 2,700 / 3,187 workflows/sec | Workflow SQLite + 3 queue nodes |
+
+These operations do different work; the internal in-memory result is not an
+SQLite or public-API claim. Run `bun run bench`, `bun run bench:tcp`, or
+`bun run bench:workflow` on your hardware.
+[Benchmark methodology →](https://bunqueue.dev/guide/benchmarks/) ·
+[full engineering report](docs/benchmarks/native-engineering-2026-07-30.md)
 
 ## Documentation
 

package/dist/application/contextFactory.d.ts

@@ -29,6 +29,7 @@ export interface ContextDependencies {
     storage: SqliteStorage | null;
     shards: Shard[];
     shardLocks: RWLock[];
+    customIdLock: RWLock;
     processingShards: Map<JobId, Job>[];
     processingLocks: RWLock[];
     jobIndex: Map<JobId, JobLocation>;
@@ -77,12 +78,13 @@ export interface ContextCallbacks {
     registerQueueName: (queue: string) => void;
     unregisterQueueName: (queue: string) => void;
     onJobCompleted: (completedId: JobId) => void;
+    onJobFailed?: (failedId: JobId) => void;
     onJobsCompleted: (completedIds: JobId[]) => void;
     hasPendingDeps: () => boolean;
     onRepeat: (job: Job) => void;
     emitDashboardEvent?: (event: string, data: Record<string, unknown>) => void;
-    onChildTerminalFailure?: (childJob: Job, error: string | undefined) => void;
-    onChildDependencyOption?: (childJob: Job, error: string | undefined) => void;
+    onChildTerminalFailure?: (childJob: Job, error: string | undefined) => Promise<void>;
+    onChildDependencyOption?: (childJob: Job, error: string | undefined) => Promise<void>;
 }
 /**
  * Factory for building context objects

package/dist/application/contextFactory.js

@@ -82,6 +82,7 @@ export class ContextFactory {
             storage: this.deps.storage,
             shards: this.deps.shards,
             shardLocks: this.deps.shardLocks,
+            customIdLock: this.deps.customIdLock,
             completedJobs: this.deps.completedJobs,
             completedJobsData: this.deps.completedJobsData,
             depCompletions: this.deps.depCompletions,
@@ -93,6 +94,7 @@ export class ContextFactory {
             totalPushed: this.deps.metrics.totalPushed,
             broadcast: this.deps.eventsManager.broadcast.bind(this.deps.eventsManager),
             dashboardEmit: this.callbacks.emitDashboardEvent,
+            registerQueueName: this.callbacks.registerQueueName,
         };
     }
     getPullContext() {
@@ -127,6 +129,7 @@ export class ContextFactory {
             perQueueMetrics: this.deps.perQueueMetrics,
             broadcast: this.deps.eventsManager.broadcast.bind(this.deps.eventsManager),
             onJobCompleted: this.callbacks.onJobCompleted,
+            onJobFailed: this.callbacks.onJobFailed,
             onJobsCompleted: this.callbacks.onJobsCompleted,
             needsBroadcast: this.deps.eventsManager.needsBroadcast.bind(this.deps.eventsManager),
             hasPendingDeps: this.callbacks.hasPendingDeps,

package/dist/application/flowFailureRecovery.d.ts

@@ -0,0 +1,17 @@
+import type { JobId } from '../domain/types/job';
+import type { JobLocation } from '../domain/types/queue';
+import type { Shard } from '../domain/queue/shard';
+import type { SqliteStorage } from '../infrastructure/persistence/sqlite';
+import type { SetLike } from '../shared/lru';
+import type { DependencyResultTracker } from './dependencyResultTracker';
+export interface FlowFailureRecoveryContext {
+    readonly storage: SqliteStorage;
+    readonly shards: Shard[];
+    readonly jobIndex: Map<JobId, JobLocation>;
+    readonly completedJobs: SetLike<JobId>;
+    readonly dependencyResults: DependencyResultTracker;
+    readonly failedChildrenValues: Map<JobId, Record<string, string>>;
+    readonly ignoredChildrenFailures: Map<JobId, Record<string, string>>;
+}
+/** Replay the durable flow-failure outbox before workers can observe recovered jobs. */
+export declare function recoverFlowFailures(ctx: FlowFailureRecoveryContext): void;

package/dist/application/flowFailureRecovery.js

@@ -0,0 +1,92 @@
+import { shardIndex } from '../shared/hash';
+function findQueuedJob(ctx, id) {
+    const location = ctx.jobIndex.get(id);
+    if (location?.type !== 'queue')
+        return null;
+    const shard = ctx.shards[location.shardIdx];
+    return (shard.getQueue(location.queueName).find(id) ??
+        shard.waitingDeps.get(id) ??
+        shard.waitingChildren.get(id) ??
+        null);
+}
+function promote(parent, ctx) {
+    const idx = shardIndex(parent.queue);
+    const shard = ctx.shards[idx];
+    if (shard.waitingDeps.delete(parent.id)) {
+        shard.unregisterDependencies(parent.id, parent.dependsOn);
+    }
+    shard.waitingChildren.delete(parent.id);
+    const queue = shard.getQueue(parent.queue);
+    if (!queue.find(parent.id)) {
+        parent.runAt = Date.now();
+        queue.push(parent);
+        shard.incrementQueued(parent.id, false, parent.createdAt, parent.queue, parent.runAt);
+        shard.notify(parent.queue);
+    }
+    ctx.storage.updateFlowParentResolution(parent);
+}
+function failParent(parent, childId, error, ctx) {
+    const shard = ctx.shards[shardIndex(parent.queue)];
+    if (shard.waitingDeps.delete(parent.id)) {
+        shard.unregisterDependencies(parent.id, parent.dependsOn);
+    }
+    shard.waitingChildren.delete(parent.id);
+    const queued = shard.getQueue(parent.queue).remove(parent.id);
+    if (queued)
+        shard.decrementQueued(parent.id);
+    const message = `Child job ${String(childId)} failed: ${error}`;
+    const entry = shard.addToDlq(parent, "unknown" /* FailureReason.Unknown */, message);
+    ctx.storage.commitFailedJob(parent.id, entry, null);
+    ctx.jobIndex.set(parent.id, { type: 'dlq', queueName: parent.queue });
+    ctx.dependencyResults.releaseConsumer(parent.id);
+}
+/** Replay the durable flow-failure outbox before workers can observe recovered jobs. */
+export function recoverFlowFailures(ctx) {
+    for (const record of ctx.storage.loadFlowFailures()) {
+        const parent = findQueuedJob(ctx, record.parentId);
+        if (!parent) {
+            if (ctx.jobIndex.get(record.parentId)?.type !== 'queue') {
+                ctx.storage.deleteFlowFailure(record.parentId, record.childId);
+            }
+            continue;
+        }
+        const childKey = `${record.childQueue}:${String(record.childId)}`;
+        if (record.mode === 'fail') {
+            failParent(parent, record.childId, record.error, ctx);
+            ctx.storage.deleteFlowFailure(record.parentId, record.childId);
+            continue;
+        }
+        if (record.mode === 'continue') {
+            const values = ctx.failedChildrenValues.get(parent.id) ?? {};
+            values[childKey] = record.error;
+            ctx.failedChildrenValues.set(parent.id, values);
+            const dependencies = [...parent.dependsOn];
+            ctx.shards[shardIndex(parent.queue)].unregisterDependencies(parent.id, dependencies);
+            for (const dependency of dependencies) {
+                ctx.dependencyResults.releaseDependency(parent.id, dependency);
+            }
+            parent.dependsOn = [];
+            promote(parent, ctx);
+            continue;
+        }
+        if (record.mode === 'ignore') {
+            const values = ctx.ignoredChildrenFailures.get(parent.id) ?? {};
+            values[childKey] = record.error;
+            ctx.ignoredChildrenFailures.set(parent.id, values);
+        }
+        const dependencyIndex = parent.dependsOn.indexOf(record.childId);
+        if (dependencyIndex !== -1) {
+            parent.dependsOn.splice(dependencyIndex, 1);
+            ctx.shards[shardIndex(parent.queue)].unregisterDependencies(parent.id, [record.childId]);
+            ctx.dependencyResults.releaseDependency(parent.id, record.childId);
+            ctx.storage.updateFlowParentResolution(parent);
+        }
+        const ready = parent.dependsOn.length === 0 ||
+            parent.dependsOn.every((dependency) => ctx.completedJobs.has(dependency));
+        if (ready)
+            promote(parent, ctx);
+        if (record.mode === 'remove') {
+            ctx.storage.deleteFlowFailure(record.parentId, record.childId);
+        }
+    }
+}

package/dist/application/operations/ack.d.ts

@@ -44,15 +44,16 @@ export interface AckContext {
         prev?: string;
     }) => void;
     onJobCompleted: (jobId: JobId) => void;
+    onJobFailed?: (jobId: JobId) => void;
     onJobsCompleted?: (jobIds: JobId[]) => void;
     needsBroadcast?: () => boolean;
     emitDashboardEvent?: (event: string, data: Record<string, unknown>) => void;
     hasPendingDeps?: () => boolean;
     onRepeat?: (job: Job) => void;
     /** Called when a child job with failParentOnFailure terminally fails */
-    onChildTerminalFailure?: (childJob: Job, error: string | undefined) => void;
+    onChildTerminalFailure?: (childJob: Job, error: string | undefined) => Promise<void>;
     /** Called when a child job with removeDependencyOnFailure/ignoreDependencyOnFailure/continueParentOnFailure terminally fails */
-    onChildDependencyOption?: (childJob: Job, error: string | undefined) => void;
+    onChildDependencyOption?: (childJob: Job, error: string | undefined) => Promise<void>;
 }
 /**
  * Acknowledge job completion

package/dist/application/operations/ack.js

@@ -91,11 +91,11 @@ export async function ackJob(jobId, result, ctx) {
     latencyTracker.ack.observe((Bun.nanoseconds() - startNs) / 1e6);
 }
 /** Move a permanently-failed job to DLQ (terminal path in failJob). */
-function moveFailedJobToDlq(job, jobId, error, shard, ctx) {
+function moveFailedJobToDlq(input) {
+    const { job, jobId, error, shard, ctx, flowFailure } = input;
     const entry = shard.addToDlq(job, "max_attempts_exceeded" /* FailureReason.MaxAttemptsExceeded */, error ?? null);
     ctx.jobIndex.set(jobId, { type: 'dlq', queueName: job.queue });
-    ctx.storage?.saveDlqEntry(entry);
-    ctx.storage?.deleteJob(jobId);
+    ctx.storage?.commitFailedJob(jobId, entry, flowFailure);
     ctx.totalFailed.value++;
     if (ctx.perQueueMetrics) {
         const pq = ctx.perQueueMetrics.get(job.queue);
@@ -121,6 +121,29 @@ function moveFailedJobToDlq(job, jobId, error, shard, ctx) {
         });
     }
 }
+function flowFailureRecord(job, error) {
+    if (!job.parentId)
+        return null;
+    let mode = null;
+    if (job.failParentOnFailure)
+        mode = 'fail';
+    else if (job.continueParentOnFailure)
+        mode = 'continue';
+    else if (job.ignoreDependencyOnFailure)
+        mode = 'ignore';
+    else if (job.removeDependencyOnFailure)
+        mode = 'remove';
+    if (!mode)
+        return null;
+    return {
+        parentId: job.parentId,
+        childId: job.id,
+        childQueue: job.queue,
+        mode,
+        error: error ?? 'unknown error',
+        createdAt: Date.now(),
+    };
+}
 /**
  * Mark job as failed
  */
@@ -149,10 +172,12 @@ export async function failJob(jobId, error, ctx, unrecoverable = false, stack) {
     }
     const idx = shardIndex(job.queue);
     let wasRetried = false;
+    const willRetry = !unrecoverable && canRetry(job);
+    const flowFailure = willRetry ? null : flowFailureRecord(job, error);
     await withWriteLock(ctx.shardLocks[idx], () => {
         const shard = ctx.shards[idx];
         shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId);
-        if (!unrecoverable && canRetry(job)) {
+        if (willRetry) {
             const now = Date.now();
             job.runAt = now + calculateBackoff(job);
             shard.getQueue(job.queue).push(job);
@@ -166,7 +191,7 @@ export async function failJob(jobId, error, ctx, unrecoverable = false, stack) {
         }
         else if (job.removeOnFail) {
             ctx.jobIndex.delete(jobId);
-            ctx.storage?.deleteJob(jobId);
+            ctx.storage?.commitFailedJob(jobId, null, flowFailure);
             ctx.totalFailed.value++;
             if (ctx.perQueueMetrics) {
                 const pq = ctx.perQueueMetrics.get(job.queue);
@@ -184,7 +209,7 @@ export async function failJob(jobId, error, ctx, unrecoverable = false, stack) {
             }
         }
         else {
-            moveFailedJobToDlq(job, jobId, error, shard, ctx);
+            moveFailedJobToDlq({ job, jobId, error, shard, ctx, flowFailure });
         }
         // Terminal failure and retry both release queue concurrency (and possibly
         // an active FIFO group), so another job may now be eligible.
@@ -210,17 +235,18 @@ export async function failJob(jobId, error, ctx, unrecoverable = false, stack) {
     }
     else {
         ctx.dependencyResults.releaseConsumer(jobId);
+        ctx.onJobFailed?.(jobId);
     }
     // BullMQ v5: failParentOnFailure — propagate terminal failure to parent
     if (!wasRetried && job.failParentOnFailure && job.parentId && ctx.onChildTerminalFailure) {
-        ctx.onChildTerminalFailure(job, error);
+        await ctx.onChildTerminalFailure(job, error);
     }
     // removeDependencyOnFailure / ignoreDependencyOnFailure / continueParentOnFailure
     if (!wasRetried &&
         job.parentId &&
         ctx.onChildDependencyOption &&
         (job.removeDependencyOnFailure || job.ignoreDependencyOnFailure || job.continueParentOnFailure)) {
-        ctx.onChildDependencyOption(job, error);
+        await ctx.onChildDependencyOption(job, error);
     }
 }
 /**

package/dist/application/operations/flowPush.d.ts

@@ -0,0 +1,9 @@
+import type { AtomicFlowBatchInput, AtomicFlowBatchResult } from '../../domain/types/flow';
+import type { PushContext } from './push';
+/**
+ * Commit a complete flow graph as one broker-side operation.
+ *
+ * SQLite is committed before the graph is published in memory. Workers acquire
+ * the same shard locks, so the first visible leaf always observes every edge.
+ */
+export declare function pushFlowBatch(batch: AtomicFlowBatchInput, ctx: PushContext): Promise<AtomicFlowBatchResult>;

package/dist/application/operations/flowPush.js

@@ -0,0 +1,112 @@
+import { createJob } from '../../domain/types/job';
+import { shardIndex } from '../../shared/hash';
+import { latencyTracker } from '../latencyTracker';
+import { throughputTracker } from '../throughputTracker';
+import { initialJobState, insertJobToShard } from './pushInsert';
+import { validateAtomicFlowBatch } from './flowValidation';
+function existingJobError(id) {
+    return new Error(`Flow job ${String(id)} already exists`);
+}
+function assertIdsAvailable(batch, ctx) {
+    for (const planned of batch.jobs) {
+        if (ctx.jobIndex.has(planned.id) ||
+            ctx.completedJobs.has(planned.id) ||
+            (ctx.depCompletions?.has(planned.id) ?? false) ||
+            ctx.jobResults.has(planned.id) ||
+            (ctx.timedOutJobs?.has(planned.id) ?? false) ||
+            ctx.shards.some((shard) => (shard.getJobsWaitingFor(planned.id)?.size ?? 0) > 0) ||
+            ctx.storage?.getJob(planned.id) ||
+            ctx.storage?.hasDlqEntry(planned.id)) {
+            throw existingJobError(planned.id);
+        }
+        if (planned.input.customId) {
+            const owner = ctx.customIdMap.get(planned.input.customId);
+            if (owner !== undefined)
+                throw existingJobError(owner);
+        }
+    }
+}
+function prepareJobs(batch, ctx, now) {
+    return batch.jobs.map((planned) => {
+        const job = createJob(planned.id, planned.queue, planned.input, now);
+        job.timeline.push({ state: initialJobState(job, ctx, now), timestamp: now });
+        return job;
+    });
+}
+function publishJobs(jobs, ctx) {
+    const notifications = new Map();
+    for (const job of jobs) {
+        const idx = shardIndex(job.queue);
+        insertJobToShard(job, { queue: job.queue, shard: ctx.shards[idx], shardIdx: idx }, ctx, false);
+        if (job.customId)
+            ctx.customIdMap.set(job.customId, job.id);
+        notifications.set(job.queue, (notifications.get(job.queue) ?? 0) + 1);
+    }
+    return notifications;
+}
+async function acquireFlowLocks(batch, ctx) {
+    const guards = [];
+    try {
+        if (batch.jobs.some((job) => job.input.customId)) {
+            guards.push(await ctx.customIdLock.acquireWrite());
+        }
+        const indexes = [...new Set(batch.jobs.map((job) => shardIndex(job.queue)))].sort((a, b) => a - b);
+        for (const index of indexes)
+            guards.push(await ctx.shardLocks[index].acquireWrite());
+        return guards;
+    }
+    catch (error) {
+        for (let index = guards.length - 1; index >= 0; index--)
+            guards[index].release();
+        throw error;
+    }
+}
+/**
+ * Commit a complete flow graph as one broker-side operation.
+ *
+ * SQLite is committed before the graph is published in memory. Workers acquire
+ * the same shard locks, so the first visible leaf always observes every edge.
+ */
+export async function pushFlowBatch(batch, ctx) {
+    const startNs = Bun.nanoseconds();
+    validateAtomicFlowBatch(batch);
+    if (batch.jobs.length === 0)
+        return { jobs: [] };
+    for (const queue of new Set(batch.jobs.map((job) => job.queue))) {
+        ctx.registerQueueName?.(queue);
+    }
+    const guards = await acquireFlowLocks(batch, ctx);
+    let jobs;
+    let notifications;
+    try {
+        assertIdsAvailable(batch, ctx);
+        const now = Date.now();
+        jobs = prepareJobs(batch, ctx, now);
+        ctx.storage?.insertJobsBatch(jobs, true);
+        notifications = publishJobs(jobs, ctx);
+    }
+    finally {
+        for (let index = guards.length - 1; index >= 0; index--)
+            guards[index].release();
+    }
+    for (const [queue, count] of notifications) {
+        ctx.shards[shardIndex(queue)].notifyBatch(queue, count);
+    }
+    ctx.totalPushed.value += BigInt(jobs.length);
+    throughputTracker.pushRate.increment(jobs.length);
+    const timestamp = Date.now();
+    for (const job of jobs) {
+        ctx.broadcast({
+            eventType: "pushed" /* EventType.Pushed */,
+            queue: job.queue,
+            jobId: job.id,
+            timestamp,
+        });
+    }
+    ctx.dashboardEmit?.('flow:pushed', {
+        jobs: jobs.length,
+        queues: notifications.size,
+    });
+    latencyTracker.push.observe((Bun.nanoseconds() - startNs) / 1e6);
+    return { jobs };
+}

package/dist/application/operations/flowTopologyValidation.d.ts

@@ -0,0 +1,3 @@
+import type { AtomicFlowBatchInput } from '../../domain/types/flow';
+/** Validate references, symmetric parent edges, metadata, and acyclicity in O(V+E). */
+export declare function validateFlowTopology(batch: AtomicFlowBatchInput, dataById: ReadonlyMap<string, Record<string, unknown>>): void;

package/dist/application/operations/flowTopologyValidation.js

@@ -0,0 +1,101 @@
+function assertMatchingIds(actual, expected, name) {
+    if (!Array.isArray(actual) ||
+        actual.length !== expected.length ||
+        actual.some((id, index) => id !== expected[index])) {
+        throw new Error(`${name} does not match the canonical flow topology`);
+    }
+}
+function assertAcyclic(topology) {
+    const remaining = new Map([...topology].map(([id, links]) => [id, links.dependencies.length]));
+    const dependents = new Map();
+    for (const [id, links] of topology) {
+        for (const dependency of links.dependencies) {
+            const list = dependents.get(dependency) ?? [];
+            list.push(id);
+            dependents.set(dependency, list);
+        }
+    }
+    const ready = [...remaining].filter(([, count]) => count === 0).map(([id]) => id);
+    let visited = 0;
+    while (ready.length > 0) {
+        const id = ready.pop();
+        if (id === undefined)
+            throw new Error('flow topology traversal failed');
+        visited++;
+        for (const dependent of dependents.get(id) ?? []) {
+            const count = remaining.get(dependent);
+            if (count === undefined)
+                throw new Error(`flow dependency not found: ${dependent}`);
+            const next = count - 1;
+            remaining.set(dependent, next);
+            if (next === 0)
+                ready.push(dependent);
+        }
+    }
+    if (visited !== topology.size)
+        throw new Error('flow contains a dependency cycle');
+}
+function buildTopology(job) {
+    const dependencies = (job.input.dependsOn ?? []).map(String);
+    const children = (job.input.childrenIds ?? []).map(String);
+    const dependencySet = new Set(dependencies);
+    const childSet = new Set(children);
+    if (dependencySet.size !== dependencies.length) {
+        throw new Error(`duplicate dependency in flow job: ${String(job.id)}`);
+    }
+    if (childSet.size !== children.length) {
+        throw new Error(`duplicate child in flow job: ${String(job.id)}`);
+    }
+    return { dependencies, dependencySet, children, childSet };
+}
+/** Validate references, symmetric parent edges, metadata, and acyclicity in O(V+E). */
+export function validateFlowTopology(batch, dataById) {
+    const jobsById = new Map(batch.jobs.map((job) => [String(job.id), job]));
+    const topology = new Map(batch.jobs.map((job) => [String(job.id), buildTopology(job)]));
+    for (const job of batch.jobs) {
+        const id = String(job.id);
+        const links = topology.get(id);
+        if (!links)
+            throw new Error(`flow topology missing job: ${id}`);
+        for (const dependency of links.dependencies) {
+            if (!jobsById.has(dependency))
+                throw new Error(`flow dependency not found: ${dependency}`);
+            if (dependency === id)
+                throw new Error(`flow job cannot depend on itself: ${id}`);
+        }
+        for (const child of links.children) {
+            if (!links.dependencySet.has(child)) {
+                throw new Error(`flow child is missing from dependencies: ${child}`);
+            }
+            const childJob = jobsById.get(child);
+            if (!childJob)
+                throw new Error(`flow child not found: ${child}`);
+            if (String(childJob.input.parentId) !== id) {
+                throw new Error(`flow child ${child} does not point back to parent ${id}`);
+            }
+        }
+        const parentId = job.input.parentId ? String(job.input.parentId) : null;
+        if (parentId) {
+            const parent = jobsById.get(parentId);
+            if (!parent)
+                throw new Error(`flow parent not found: ${parentId}`);
+            const parentLinks = topology.get(parentId);
+            if (!parentLinks?.childSet.has(id)) {
+                throw new Error(`flow parent ${parentId} does not own child ${id}`);
+            }
+            const data = dataById.get(id);
+            if (!data)
+                throw new Error(`flow metadata missing for child ${id}`);
+            if (data.__parentId !== parentId || data.__parentQueue !== parent.queue) {
+                throw new Error(`flow child ${id} metadata does not match parent ${parentId}`);
+            }
+        }
+        if (links.children.length > 0) {
+            const data = dataById.get(id);
+            if (!data)
+                throw new Error(`flow metadata missing for parent ${id}`);
+            assertMatchingIds(data.__childrenIds, links.children, `flow parent ${id} children`);
+        }
+    }
+    assertAcyclic(topology);
+}

package/dist/application/operations/flowValidation.d.ts

@@ -0,0 +1,3 @@
+import type { AtomicFlowBatchInput } from '../../domain/types/flow';
+/** Validate the whole graph before any lock, storage write, or queue mutation. */
+export declare function validateAtomicFlowBatch(batch: AtomicFlowBatchInput): void;