bunqueue 2.8.49 → 2.8.51

package/dist/application/flowFailureRecovery.js

@@ -0,0 +1,94 @@
+import { shardIndex } from '../shared/hash';
+import { reconcileDependencyCompletionPins, } from './dependencyCompletions';
+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) || (ctx.depCompletions?.has(dependency) ?? false));
+        if (ready)
+            promote(parent, ctx);
+        if (record.mode === 'remove') {
+            ctx.storage.deleteFlowFailure(record.parentId, record.childId);
+        }
+    }
+    reconcileDependencyCompletionPins(ctx);
+}

package/dist/application/flowParentBackpatch.d.ts

@@ -0,0 +1,27 @@
+import type { Job, 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 { RWLock } from '../shared/lock';
+import type { MapLike, SetLike } from '../shared/lru';
+export interface FlowParentBackpatchContext {
+    readonly storage: SqliteStorage | null;
+    readonly customIdLock: RWLock;
+    readonly shards: Shard[];
+    readonly shardLocks: RWLock[];
+    readonly processingShards: Map<JobId, Job>[];
+    readonly processingLocks: RWLock[];
+    readonly jobIndex: Map<JobId, JobLocation>;
+    readonly completedJobsData: MapLike<JobId, Job>;
+    readonly depCompletions: SetLike<JobId>;
+}
+/** Reject a backpatch that would steal a child from an existing real parent. */
+export declare function assertFlowParentOwnership(child: Job, parentId: JobId): void;
+export declare function isDeclaredFlowChild(parent: Job, childId: JobId): boolean;
+export declare function canAcceptRemovedFlowChild(parent: Job | null, childId: JobId, depCompletions: SetLike<JobId>): boolean;
+export declare function flowChildFailureError(child: Job, shards: Shard[]): string | undefined;
+/**
+ * Replace the legacy `pending` parent marker for an edge already declared by
+ * the parent. This operation never changes parent scheduling or terminal state.
+ */
+export declare function backpatchDeclaredFlowChild(child: Job, parent: Job, ctx: FlowParentBackpatchContext): Promise<Job>;

package/dist/application/flowParentBackpatch.js

@@ -0,0 +1,120 @@
+import { processingShardIndex, shardIndex } from '../shared/hash';
+function parentFromData(job) {
+    if (!job.data || typeof job.data !== 'object' || Array.isArray(job.data))
+        return null;
+    const value = job.data.__parentId;
+    return value === undefined || value === null ? null : String(value);
+}
+/** Reject a backpatch that would steal a child from an existing real parent. */
+export function assertFlowParentOwnership(child, parentId) {
+    const candidates = [child.parentId ? String(child.parentId) : null, parentFromData(child)];
+    for (const owner of candidates) {
+        if (owner && owner !== 'pending' && owner !== String(parentId)) {
+            throw new Error(`Child job ${String(child.id)} already belongs to parent ${owner}`);
+        }
+    }
+}
+export function isDeclaredFlowChild(parent, childId) {
+    return parent.childrenIds.includes(childId);
+}
+export function canAcceptRemovedFlowChild(parent, childId, depCompletions) {
+    return Boolean(parent && isDeclaredFlowChild(parent, childId) && depCompletions.has(childId));
+}
+function queuedJob(id, location, ctx) {
+    const shard = ctx.shards[location.shardIdx];
+    return (shard.getQueue(location.queueName).find(id) ??
+        shard.waitingDeps.get(id) ??
+        shard.waitingChildren.get(id) ??
+        null);
+}
+function dlqJob(id, queue, ctx) {
+    return ctx.shards[shardIndex(queue)].getDlq(queue).find((job) => job.id === id) ?? null;
+}
+export function flowChildFailureError(child, shards) {
+    const entry = shards[shardIndex(child.queue)]
+        .getDlqEntries(child.queue)
+        .find((candidate) => candidate.job.id === child.id);
+    return entry?.error ?? undefined;
+}
+/** Resolve the canonical in-memory object while all relevant locks are held. */
+function lockedJob(id, fallback, ctx) {
+    const location = ctx.jobIndex.get(id);
+    if (!location)
+        return ctx.completedJobsData.get(id) ?? fallback;
+    if (location.type === 'queue')
+        return queuedJob(id, location, ctx) ?? fallback;
+    if (location.type === 'processing') {
+        return ctx.processingShards[location.shardIdx].get(id) ?? fallback;
+    }
+    if (location.type === 'completed')
+        return ctx.completedJobsData.get(id) ?? fallback;
+    return dlqJob(id, location.queueName, ctx) ?? fallback;
+}
+async function acquireBackpatchLocks(child, parent, ctx) {
+    const guards = [];
+    try {
+        guards.push(await ctx.customIdLock.acquireWrite());
+        const shardIndexes = [...new Set([shardIndex(child.queue), shardIndex(parent.queue)])].sort((a, b) => a - b);
+        for (const index of shardIndexes)
+            guards.push(await ctx.shardLocks[index].acquireWrite());
+        const processingIndexes = [
+            ...new Set([processingShardIndex(child.id), processingShardIndex(parent.id)]),
+        ].sort((a, b) => a - b);
+        for (const index of processingIndexes) {
+            guards.push(await ctx.processingLocks[index].acquireWrite());
+        }
+        return guards;
+    }
+    catch (error) {
+        for (let index = guards.length - 1; index >= 0; index--)
+            guards[index].release();
+        throw error;
+    }
+}
+function linkedData(child, parent) {
+    const source = child.data && typeof child.data === 'object' && !Array.isArray(child.data)
+        ? child.data
+        : {};
+    return {
+        ...source,
+        __parentId: String(parent.id),
+        __parentQueue: parent.queue,
+    };
+}
+function mutateChild(target, parentId, data) {
+    target.parentId = parentId;
+    target.data = data;
+}
+/**
+ * Replace the legacy `pending` parent marker for an edge already declared by
+ * the parent. This operation never changes parent scheduling or terminal state.
+ */
+export async function backpatchDeclaredFlowChild(child, parent, ctx) {
+    const guards = await acquireBackpatchLocks(child, parent, ctx);
+    try {
+        const lockedParent = lockedJob(parent.id, parent, ctx);
+        if (!ctx.jobIndex.has(child.id) &&
+            !ctx.completedJobsData.has(child.id) &&
+            ctx.depCompletions.has(child.id)) {
+            return child;
+        }
+        const lockedChild = lockedJob(child.id, child, ctx);
+        if (!isDeclaredFlowChild(lockedParent, child.id)) {
+            throw new Error(`Parent job ${String(parent.id)} is not linkable`);
+        }
+        assertFlowParentOwnership(lockedChild, parent.id);
+        const data = linkedData(lockedChild, lockedParent);
+        const linkedChild = { ...lockedChild, parentId: lockedParent.id, data };
+        ctx.storage?.backpatchFlowChild(linkedChild, lockedChild.parentId);
+        const targets = [child, lockedChild, dlqJob(child.id, child.queue, ctx)];
+        for (const target of targets) {
+            if (target)
+                mutateChild(target, lockedParent.id, data);
+        }
+        return linkedChild;
+    }
+    finally {
+        for (let index = guards.length - 1; index >= 0; index--)
+            guards[index].release();
+    }
+}

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

@@ -9,6 +9,7 @@ import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
 import type { RWLock } from '../../shared/lock';
 import type { SetLike, MapLike } from '../../shared/lru';
 import type { DependencyResultTracker } from '../dependencyResultTracker';
+import { type DependencyCompletionTracker } from '../dependencyCompletions';
 /** Ack operation context */
 export interface AckContext {
     storage: SqliteStorage | null;
@@ -19,7 +20,8 @@ export interface AckContext {
     completedJobs: SetLike<JobId>;
     completedJobsData: MapLike<JobId, Job>;
     /** Bare completion ids for removeOnComplete jobs so dependents can unblock */
-    depCompletions?: SetLike<JobId>;
+    depCompletions?: DependencyCompletionTracker;
+    maxDependencyCompletions: number;
     jobResults: MapLike<JobId, unknown>;
     dependencyResults: DependencyResultTracker;
     jobIndex: Map<JobId, JobLocation>;
@@ -44,15 +46,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

@@ -8,6 +8,7 @@ import { shardIndex, processingShardIndex } from '../../shared/hash';
 import { latencyTracker } from '../latencyTracker';
 import { throughputTracker } from '../throughputTracker';
 import { groupByProcShard, groupItemsByProcShard, extractJobs, extractJobsWithResults, groupByQueueShard, releaseResources, finalizeBatchAck, } from './ackHelpers';
+import { commitRemovedCompletion, } from '../dependencyCompletions';
 /**
  * Acknowledge job completion
  */
@@ -52,13 +53,12 @@ export async function ackJob(jobId, result, ctx) {
         ctx.storage?.markCompleted(jobId, now, job.timeline);
     }
     else {
+        commitRemovedCompletion(job, ctx);
         ctx.jobIndex.delete(jobId);
-        ctx.storage?.deleteJob(jobId);
         // removeOnComplete drops the full job (index + data + persisted row) to bound
         // memory, but dependent jobs gate readiness on completedJobs.has(parentId).
         // Record the bare completion id (no payload) so dependents still unblock,
         // without making the job appear in state/stats queries.
-        ctx.depCompletions?.add(jobId);
     }
     if (result !== undefined)
         ctx.dependencyResults.retain(jobId, result);
@@ -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/ackHelpers.d.ts

@@ -1,6 +1,4 @@
-/**
- * Ack Helpers - Shared batch processing utilities
- */
+/** Shared batch acknowledgement utilities. */
 import type { Job, JobId } from '../../domain/types/job';
 import type { JobLocation, EventType } from '../../domain/types/queue';
 import type { Shard } from '../../domain/queue/shard';
@@ -8,6 +6,7 @@ import type { RWLock } from '../../shared/lock';
 import type { SetLike, MapLike } from '../../shared/lru';
 import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
 import type { DependencyResultTracker } from '../dependencyResultTracker';
+import { type DependencyCompletionTracker } from '../dependencyCompletions';
 export interface ExtractedJob<T = unknown> {
     id: JobId;
     job: Job;
@@ -53,10 +52,12 @@ export declare function releaseResources(byQueueShard: Map<number, Job[]>, ctx:
 /** Context for finalize operations */
 export interface FinalizeContext {
     storage: SqliteStorage | null;
+    shards: Shard[];
     completedJobs: SetLike<JobId>;
     completedJobsData: MapLike<JobId, Job>;
     /** Bare completion ids for removeOnComplete jobs so dependents can unblock */
-    depCompletions?: SetLike<JobId>;
+    depCompletions?: DependencyCompletionTracker;
+    maxDependencyCompletions: number;
     jobResults: MapLike<JobId, unknown>;
     dependencyResults?: DependencyResultTracker;
     jobIndex: Map<JobId, JobLocation>;

package/dist/application/operations/ackHelpers.js

@@ -1,10 +1,8 @@
-/**
- * Ack Helpers - Shared batch processing utilities
- */
 import { MAX_TIMELINE_ENTRIES } from '../../domain/types/job';
 import { withWriteLock } from '../../shared/lock';
 import { shardIndex, processingShardIndex } from '../../shared/hash';
 import { throughputTracker } from '../throughputTracker';
+import { commitRemovedCompletion, } from '../dependencyCompletions';
 /**
  * Group job IDs by processing shard
  * Returns Map<shardIndex, jobIds[]>
@@ -161,14 +159,10 @@ export function finalizeBatchAck(extractedJobs, ctx, includeResults) {
             ctx.completedJobs.add(jobId);
         }
         else {
+            commitRemovedCompletion(job, ctx, now);
             ctx.jobIndex.delete(jobId);
-            if (hasStorage)
-                storage.deleteJob(jobId);
-            // removeOnComplete drops the full job to bound memory, but dependents gate
-            // readiness on completedJobs.has(parentId). Record the bare completion id
-            // (no payload) so dependent jobs still unblock, without surfacing the job
-            // in state/stats queries.
-            ctx.depCompletions?.add(jobId);
+            // The helper publishes payload-free dependency evidence only after its
+            // durable job-removal transaction commits.
         }
     }
     for (let i = 0; i < jobCount; i++) {

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

@@ -3,11 +3,14 @@ import { type Job, type JobId, type JobInput } from '../../domain/types/job';
 import type { JobLocation } from '../../domain/types/queue';
 import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
 import type { MapLike, SetLike } from '../../shared/lru';
+import { type DependencyCompletionTracker } from '../dependencyCompletions';
 export interface CustomIdContext {
     storage: SqliteStorage | null;
     shards: Shard[];
     completedJobs: SetLike<JobId>;
     completedJobsData: MapLike<JobId, Job>;
+    depCompletions?: DependencyCompletionTracker;
+    maxDependencyCompletions: number;
     timedOutJobs?: SetLike<JobId>;
     jobResults: MapLike<JobId, unknown>;
     customIdMap: MapLike<string, JobId>;

package/dist/application/operations/customId.js

@@ -1,5 +1,6 @@
 import { generateJobId, jobId } from '../../domain/types/job';
 import { shardIndex } from '../../shared/hash';
+import { releaseDependencyCompletionPins, } from '../dependencyCompletions';
 /**
  * Enforce custom-ID idempotency while the caller holds the target shard lock.
  * Live generations are returned unchanged; terminal generations are retired
@@ -50,6 +51,15 @@ export function handleCustomId(input, ctx, lockedShardIndexes) {
         // id. The fresh jobs row is inserted only after this retirement completes.
         ctx.storage?.deleteDlqEntry(id);
     }
+    if (ctx.depCompletions?.has(id)) {
+        const hasUnresolvedConsumers = ctx.shards.some((shard) => (shard.getJobsWaitingFor(id)?.size ?? 0) > 0);
+        if (hasUnresolvedConsumers) {
+            throw new Error(`Custom ID ${String(id)} still has unresolved dependency consumers`);
+        }
+        releaseDependencyCompletionPins([id], ctx);
+        ctx.storage?.deleteDependencyCompletion(id);
+        ctx.depCompletions.delete(id);
+    }
     // A durable jobs row may outlive its in-memory tracking after an interrupted
     // cleanup. The storage insert upserts that orphan without adding a DELETE to
     // every custom-ID push.

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;