bunqueue 2.8.49 → 2.8.51

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             |
 
@@ -210,6 +212,49 @@ Worker("emails", lambda job: {"sent": True}, concurrency=10).run()
 Every SDK is certified against the same public
 [wire protocol](https://github.com/egeominotti/bunqueue/blob/main/docs/protocol.md) and conformance suite.
 
+### Atomic flows, in every SDK
+
+Every official `FlowProducer` resolves all job IDs and reciprocal dependency
+edges locally, then sends one `PUSHF` command. The broker validates the complete
+graph and commits it atomically, so a worker cannot observe a leaf from a
+partially-created flow.
+
+```typescript
+import { FlowProducer } from 'bunqueue-client';
+
+const flows = new FlowProducer({ host: 'localhost', port: 6789 });
+const root = await flows.add({
+  name: 'publish-release',
+  queueName: 'release',
+  data: { version: 'candidate-42' },
+  children: [
+    { name: 'unit-tests', queueName: 'checks', data: { suite: 'unit' } },
+    { name: 'sdk-tests', queueName: 'checks', data: { suite: 'sdk' } },
+  ],
+});
+
+console.log(root.job.id, root.children?.map(({ job }) => job.id));
+await flows.close();
+```
+
+The repository records the contracts and the test strategy beside each
+implementation:
+
+| SDK | Runtime invariants | Generated tests | Mutation engine |
+| --- | --- | --- | --- |
+| [TypeScript](./sdk/typescript/README.md) | [contract](./sdk/typescript/INVARIANTS.md) | fast-check | StrykerJS |
+| [Python](./sdk/python/README.md) | [contract](./sdk/python/INVARIANTS.md) | Hypothesis | mutmut |
+| [PHP](./sdk/php/README.md) | [contract](./sdk/php/INVARIANTS.md) | Eris | Infection |
+| [Go](./sdk/go/README.md) | [contract](./sdk/go/INVARIANTS.md) | Rapid | Gremlins |
+| [Rust](./sdk/rust/README.md) | [contract](./sdk/rust/INVARIANTS.md) | proptest | cargo-mutants |
+| [Elixir](./sdk/elixir/README.md) | [contract](./sdk/elixir/INVARIANTS.md) | StreamData | Muex |
+
+Property campaigns run in the ordinary SDK gate with deterministic replay
+seeds. Mutation campaigns run separately against the pure planners and
+snapshot validators. Contributors can reproduce the complete isolated SDK
+gate with `bun run test:sandbox:sdk`; language-specific commands live in each
+SDK README and `AGENTS.md`.
+
 [SDK guide (all six languages) →](https://bunqueue.dev/guide/sdks/)
 
 ## Simple Mode
@@ -343,13 +388,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/backgroundTasks.js

@@ -10,10 +10,11 @@ import * as dlqOps from './dlqManager';
 import { checkExpiredLocks } from './lockManager';
 import { cleanup } from './cleanupTasks';
 import { checkStalledJobs } from './stallDetection';
-import { processPendingDependencies } from './dependencyProcessor';
+import { checkpointDependencyPromotion, dependencyReadyState, processPendingDependencies, } from './dependencyProcessor';
 import { handleTaskError, handleTaskSuccess, getTaskErrorStats } from './taskErrorTracking';
 import { runMonitoringChecks } from './monitoringChecks';
-import { isCorruptDependsOn } from '../infrastructure/persistence/sqliteSerializer';
+import { isCorruptDependsOn, persistedJobState, } from '../infrastructure/persistence/sqliteSerializer';
+import { reconcileDependencyCompletionPins } from './dependencyCompletions';
 export { getTaskErrorStats };
 /**
  * Start all background tasks
@@ -195,8 +196,14 @@ function quarantineCorruptDependsOn(ctx, job) {
 export function recover(ctx) {
     if (!ctx.storage)
         return;
+    // Keep the full pre-reconciliation window outside the bounded RAM tracker.
+    // A restart may lower maxCompletedJobs; pruning before Phase 2 reconstructs
+    // reverse edges could discard an old proof still owned by a waiting parent.
+    const dependencyCompletions = ctx.storage.loadDependencyCompletions();
     // Load completed job IDs from SQLite for dependency checking
     const completedInDb = ctx.storage.loadCompletedJobIds();
+    for (const record of dependencyCompletions)
+        completedInDb.add(record.jobId);
     // Load DLQ job IDs so Phase 1 can skip stale active rows for DLQ'd jobs
     // (legacy DBs predate the DLQ-row cleanup fix in failJob).
     const dlqJobIds = ctx.storage.loadDlqJobIds();
@@ -309,9 +316,15 @@ export function recover(ctx) {
                 continue;
             }
             // Check if job has unmet dependencies
-            // Check both in-memory completedJobs AND SQLite job_results table
+            // A ready persisted state is an authoritative checkpoint: dependency
+            // proofs are deliberately bounded and may have expired after promotion.
             const hasDependencies = job.dependsOn && job.dependsOn.length > 0;
+            const recoveredState = persistedJobState(job);
+            const wasAlreadyPromoted = recoveredState === 'waiting' ||
+                recoveredState === 'prioritized' ||
+                recoveredState === 'delayed';
             const needsWaitingDeps = hasDependencies &&
+                !wasAlreadyPromoted &&
                 !job.dependsOn.every((depId) => ctx.completedJobs.has(depId) || completedInDb.has(depId));
             if (needsWaitingDeps) {
                 // Job is waiting for dependencies - don't add to main queue
@@ -323,8 +336,11 @@ export function recover(ctx) {
                 // Job is ready to process
                 shard.getQueue(job.queue).push(job);
                 // Update running counters for O(1) stats and temporal index
-                const isDelayed = job.runAt > now;
+                const state = dependencyReadyState(job, now);
+                const isDelayed = state === 'delayed';
                 shard.incrementQueued(job.id, isDelayed, job.createdAt, job.queue, job.runAt);
+                if (hasDependencies)
+                    checkpointDependencyPromotion(job, state, now, ctx.storage);
             }
             ctx.jobIndex.set(job.id, { type: 'queue', shardIdx: idx, queueName: job.queue });
             ctx.dependencyResults.registerConsumer(job.id, job.dependsOn);
@@ -416,6 +432,7 @@ export function recover(ctx) {
         if (completedBatch.length < batchSize)
             break;
     }
+    reconcileDependencyCompletionPins(ctx);
 }
 // Re-export for backward compatibility
 export { processPendingDependencies };

package/dist/application/cleanupTasks.js

@@ -4,6 +4,7 @@
  */
 import { processingShardIndex, SHARD_COUNT } from '../shared/hash';
 import { withWriteLock } from '../shared/lock';
+import { releaseDependencyCompletionPins } from './dependencyCompletions';
 /**
  * Main cleanup function - called periodically to maintain system health
  * Cleans orphaned entries, stale data, and manages memory
@@ -72,6 +73,7 @@ async function cleanStaleWaitingDependencies(ctx, now) {
             continue;
         const removed = await withWriteLock(ctx.shardLocks[i], () => {
             let count = 0;
+            const released = [];
             for (const id of staleIds) {
                 const job = shard.waitingDeps.get(id);
                 if (!job || now - job.createdAt <= depTimeout)
@@ -81,6 +83,7 @@ async function cleanStaleWaitingDependencies(ctx, now) {
                 ctx.storage?.deleteJob(job.id);
                 shard.waitingDeps.delete(job.id);
                 shard.unregisterDependencies(job.id, job.dependsOn);
+                released.push(...job.dependsOn);
                 if (job.uniqueKey && shard.getUniqueKeyEntry(job.queue, job.uniqueKey)?.jobId === job.id) {
                     shard.releaseUniqueKey(job.queue, job.uniqueKey);
                 }
@@ -91,10 +94,11 @@ async function cleanStaleWaitingDependencies(ctx, now) {
                 ctx.jobIndex.delete(job.id);
                 count++;
             }
-            return count;
+            return { count, released };
         });
-        if (removed > 0) {
-            ctx.dashboardEmit?.('cleanup:stale-deps-removed', { count: removed });
+        releaseDependencyCompletionPins(removed.released, ctx);
+        if (removed.count > 0) {
+            ctx.dashboardEmit?.('cleanup:stale-deps-removed', { count: removed.count });
         }
     }
 }

package/dist/application/contextFactory.d.ts

@@ -13,6 +13,7 @@ import type { WorkerManager } from './workerManager';
 import type { EventsManager } from './eventsManager';
 import type { MonitoringState } from './monitoringChecks';
 import type { DependencyResultTracker } from './dependencyResultTracker';
+import type { DependencyCompletionTracker } from './dependencyCompletions';
 import type { LockContext, BackgroundContext, StatsContext } from './types';
 import type { PushContext } from './operations/push';
 import type { PullContext } from './operations/pull';
@@ -29,12 +30,13 @@ export interface ContextDependencies {
     storage: SqliteStorage | null;
     shards: Shard[];
     shardLocks: RWLock[];
+    customIdLock: RWLock;
     processingShards: Map<JobId, Job>[];
     processingLocks: RWLock[];
     jobIndex: Map<JobId, JobLocation>;
     completedJobs: BoundedSet<JobId>;
     completedJobsData: BoundedMap<JobId, Job>;
-    depCompletions?: BoundedSet<JobId>;
+    depCompletions?: DependencyCompletionTracker;
     timedOutJobs?: BoundedSet<JobId>;
     jobResults: LRUMap<JobId, unknown>;
     dependencyResults: DependencyResultTracker;
@@ -77,12 +79,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

@@ -35,6 +35,7 @@ export class ContextFactory {
             jobIndex: this.deps.jobIndex,
             completedJobs: this.deps.completedJobs,
             depCompletions: this.deps.depCompletions,
+            maxDependencyCompletions: this.deps.config.maxCompletedJobs,
             timedOutJobs: this.deps.timedOutJobs,
             jobResults: this.deps.jobResults,
             dependencyResults: this.deps.dependencyResults,
@@ -82,9 +83,11 @@ 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,
+            maxDependencyCompletions: this.deps.config.maxCompletedJobs,
             timedOutJobs: this.deps.timedOutJobs,
             jobResults: this.deps.jobResults,
             dependencyResults: this.deps.dependencyResults,
@@ -93,6 +96,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() {
@@ -118,6 +122,7 @@ export class ContextFactory {
             completedJobs: this.deps.completedJobs,
             completedJobsData: this.deps.completedJobsData,
             depCompletions: this.deps.depCompletions,
+            maxDependencyCompletions: this.deps.config.maxCompletedJobs,
             jobResults: this.deps.jobResults,
             dependencyResults: this.deps.dependencyResults,
             jobIndex: this.deps.jobIndex,
@@ -127,6 +132,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,
@@ -147,6 +153,8 @@ export class ContextFactory {
             jobLocks: this.deps.jobLocks,
             clientJobs: this.deps.clientJobs,
             dependencyResults: this.deps.dependencyResults,
+            depCompletions: this.deps.depCompletions,
+            maxDependencyCompletions: this.deps.config.maxCompletedJobs,
             webhookManager: this.deps.webhookManager,
             eventsManager: this.deps.eventsManager,
             repeatChain: this.deps.repeatChain,

package/dist/application/dependencyCompletions.d.ts

@@ -0,0 +1,53 @@
+import type { Job, JobId } from '../domain/types/job';
+import type { Shard } from '../domain/queue/shard';
+import type { SqliteStorage } from '../infrastructure/persistence/sqlite';
+import type { SetLike } from '../shared/lru';
+interface CompletionRecord {
+    jobId: JobId;
+    pinned: boolean;
+}
+/**
+ * Payload-free completion evidence has two retention classes:
+ * recent IDs are FIFO-bounded, while IDs referenced by live dependency edges
+ * stay pinned until their final consumer is durably resolved or removed.
+ */
+export declare class DependencyCompletionTracker implements SetLike<JobId> {
+    private readonly onRecentEvict?;
+    private readonly recent;
+    private readonly pinned;
+    private readonly maxRecent;
+    constructor(maxRecent: number, onRecentEvict?: ((jobId: JobId) => void) | undefined);
+    add(jobId: JobId): void;
+    pin(jobId: JobId): void;
+    unpin(jobId: JobId, retainAsRecent: boolean): void;
+    hydrate(records: Iterable<CompletionRecord>): void;
+    pinnedValues(): IterableIterator<JobId>;
+    has(jobId: JobId): boolean;
+    delete(jobId: JobId): boolean;
+    clear(): void;
+    get size(): number;
+}
+export interface DependencyCompletionContext {
+    storage: SqliteStorage | null;
+    shards: Shard[];
+    depCompletions?: DependencyCompletionTracker;
+    maxDependencyCompletions: number;
+}
+export declare function hasDependencyWaiters(shards: Shard[], jobId: JobId): boolean;
+/** Persist a removeOnComplete transition before publishing its RAM evidence. */
+export declare function commitRemovedCompletion(job: Pick<Job, 'id' | 'queue'>, ctx: DependencyCompletionContext, completedAt?: number): void;
+/**
+ * Protect recent proofs when a newly accepted parent waits on another
+ * dependency. SQLite is updated first so RAM never advertises a stronger
+ * durability guarantee than the database.
+ */
+export declare function pinReferencedCompletions(dependencyIds: Iterable<JobId>, ctx: Pick<DependencyCompletionContext, 'storage' | 'depCompletions'>): void;
+/**
+ * Unpin candidates only after every shard has released its reverse edge.
+ * Storage returns the complete retained set because pruning can also evict
+ * older recent entries; hydrating from it keeps both RAM tiers exact.
+ */
+export declare function releaseDependencyCompletionPins(dependencyIds: Iterable<JobId>, ctx: DependencyCompletionContext): void;
+/** Rebuild pin ownership from the authoritative reverse dependency indexes. */
+export declare function reconcileDependencyCompletionPins(ctx: DependencyCompletionContext): void;
+export {};

package/dist/application/dependencyCompletions.js

@@ -0,0 +1,123 @@
+/**
+ * Payload-free completion evidence has two retention classes:
+ * recent IDs are FIFO-bounded, while IDs referenced by live dependency edges
+ * stay pinned until their final consumer is durably resolved or removed.
+ */
+export class DependencyCompletionTracker {
+    onRecentEvict;
+    recent = new Set();
+    pinned = new Set();
+    maxRecent;
+    constructor(maxRecent, onRecentEvict) {
+        this.onRecentEvict = onRecentEvict;
+        this.maxRecent = Math.max(1, Math.trunc(maxRecent));
+    }
+    add(jobId) {
+        if (this.pinned.has(jobId) || this.recent.has(jobId))
+            return;
+        if (this.recent.size >= this.maxRecent) {
+            const oldest = this.recent.values().next().value;
+            if (oldest !== undefined) {
+                this.recent.delete(oldest);
+                this.onRecentEvict?.(oldest);
+            }
+        }
+        this.recent.add(jobId);
+    }
+    pin(jobId) {
+        this.recent.delete(jobId);
+        this.pinned.add(jobId);
+    }
+    unpin(jobId, retainAsRecent) {
+        this.pinned.delete(jobId);
+        if (retainAsRecent)
+            this.recent.add(jobId);
+        else
+            this.recent.delete(jobId);
+    }
+    hydrate(records) {
+        this.clear();
+        for (const record of records) {
+            if (record.pinned)
+                this.pin(record.jobId);
+            else
+                this.add(record.jobId);
+        }
+    }
+    pinnedValues() {
+        return this.pinned.values();
+    }
+    has(jobId) {
+        return this.pinned.has(jobId) || this.recent.has(jobId);
+    }
+    delete(jobId) {
+        const wasPinned = this.pinned.delete(jobId);
+        return this.recent.delete(jobId) || wasPinned;
+    }
+    clear() {
+        this.recent.clear();
+        this.pinned.clear();
+    }
+    get size() {
+        return this.recent.size + this.pinned.size;
+    }
+}
+export function hasDependencyWaiters(shards, jobId) {
+    return shards.some((shard) => (shard.getJobsWaitingFor(jobId)?.size ?? 0) > 0);
+}
+/** Persist a removeOnComplete transition before publishing its RAM evidence. */
+export function commitRemovedCompletion(job, ctx, completedAt = Date.now()) {
+    const pinned = hasDependencyWaiters(ctx.shards, job.id);
+    ctx.storage?.commitRemovedCompletion(job, ctx.maxDependencyCompletions, pinned, completedAt);
+    if (pinned)
+        ctx.depCompletions?.pin(job.id);
+    else
+        ctx.depCompletions?.add(job.id);
+}
+/**
+ * Protect recent proofs when a newly accepted parent waits on another
+ * dependency. SQLite is updated first so RAM never advertises a stronger
+ * durability guarantee than the database.
+ */
+export function pinReferencedCompletions(dependencyIds, ctx) {
+    const ids = [...new Set(dependencyIds)].filter((id) => ctx.depCompletions?.has(id) ?? false);
+    if (ids.length === 0)
+        return;
+    ctx.storage?.pinDependencyCompletions(ids);
+    for (const id of ids)
+        ctx.depCompletions?.pin(id);
+}
+/**
+ * Unpin candidates only after every shard has released its reverse edge.
+ * Storage returns the complete retained set because pruning can also evict
+ * older recent entries; hydrating from it keeps both RAM tiers exact.
+ */
+export function releaseDependencyCompletionPins(dependencyIds, ctx) {
+    const candidates = [...new Set(dependencyIds)].filter((id) => !hasDependencyWaiters(ctx.shards, id));
+    if (candidates.length === 0)
+        return;
+    if (ctx.storage) {
+        const records = ctx.storage.unpinDependencyCompletions(candidates, ctx.maxDependencyCompletions);
+        ctx.depCompletions?.hydrate(records);
+        return;
+    }
+    for (const id of candidates)
+        ctx.depCompletions?.unpin(id, true);
+}
+/** Rebuild pin ownership from the authoritative reverse dependency indexes. */
+export function reconcileDependencyCompletionPins(ctx) {
+    const referenced = new Set();
+    for (const shard of ctx.shards) {
+        for (const dependencyId of shard.dependencyIndex.keys())
+            referenced.add(dependencyId);
+    }
+    if (ctx.storage) {
+        const records = ctx.storage.reconcileDependencyCompletionPins(referenced, ctx.maxDependencyCompletions);
+        ctx.depCompletions?.hydrate(records);
+        return;
+    }
+    for (const id of ctx.depCompletions?.pinnedValues() ?? []) {
+        if (!referenced.has(id))
+            ctx.depCompletions?.unpin(id, true);
+    }
+}

package/dist/application/dependencyProcessor.d.ts

@@ -2,9 +2,14 @@
  * Dependency Processor - Job dependency resolution
  * Uses reverse index for O(m) where m = jobs waiting on completed deps
  */
+import type { Job } from '../domain/types/job';
 import type { BackgroundContext } from './types';
+type DependencyReadyState = 'delayed' | 'prioritized' | 'waiting';
+export declare function dependencyReadyState(job: Job, now: number): DependencyReadyState;
+export declare function checkpointDependencyPromotion(job: Job, state: DependencyReadyState, now: number, storage: BackgroundContext['storage']): void;
 /**
  * Process pending dependency checks
  * Resolves jobs whose dependencies have been completed
  */
 export declare function processPendingDependencies(ctx: BackgroundContext): Promise<void>;
+export {};

package/dist/application/dependencyProcessor.js

@@ -5,6 +5,18 @@
 import { MAX_TIMELINE_ENTRIES } from '../domain/types/job';
 import { SHARD_COUNT } from '../shared/hash';
 import { withWriteLock } from '../shared/lock';
+import { releaseDependencyCompletionPins } from './dependencyCompletions';
+export function dependencyReadyState(job, now) {
+    if (job.runAt > now)
+        return 'delayed';
+    return job.priority > 0 ? 'prioritized' : 'waiting';
+}
+export function checkpointDependencyPromotion(job, state, now, storage) {
+    if (job.timeline.at(-1)?.state !== state && job.timeline.length < MAX_TIMELINE_ENTRIES) {
+        job.timeline.push({ state, timestamp: now });
+    }
+    storage?.updateFlowParentResolution(job, state);
+}
 /**
  * Process pending dependency checks
  * Resolves jobs whose dependencies have been completed
@@ -13,8 +25,10 @@ export async function processPendingDependencies(ctx) {
     if (ctx.pendingDepChecks.size === 0)
         return;
     const completedIds = Array.from(ctx.pendingDepChecks);
+    const completedNow = new Set(completedIds);
     ctx.pendingDepChecks.clear();
     const jobsToCheckByShard = new Map();
+    const releasedDependencyIds = new Set();
     // Find all jobs waiting for the completed dependencies
     for (const completedId of completedIds) {
         for (let i = 0; i < SHARD_COUNT; i++) {
@@ -42,37 +56,35 @@ export async function processPendingDependencies(ctx) {
             // dropped to bound memory), so also honor its bare-id depCompletions entry.
             for (const jobId of jobIdsToCheck) {
                 const job = shard.waitingDeps.get(jobId);
-                if (job?.dependsOn.every((dep) => ctx.completedJobs.has(dep) || (ctx.depCompletions?.has(dep) ?? false))) {
+                if (job?.dependsOn.every((dep) => completedNow.has(dep) ||
+                    ctx.completedJobs.has(dep) ||
+                    (ctx.depCompletions?.has(dep) ?? false))) {
                     jobsToPromote.push(job);
                 }
             }
             // Promote jobs with all dependencies satisfied
             if (jobsToPromote.length > 0) {
-                promoteJobsToQueue(jobsToPromote, shard, ctx, i);
+                promoteJobsToQueue(jobsToPromote, shard, ctx, i, releasedDependencyIds);
             }
         });
     }));
-    // NOTE: depCompletions is intentionally NOT pruned here. It is a FIFO
-    // BoundedSet (same cap as completedJobs), so it self-bounds. Pruning eagerly
-    // once "no waiters remain" would orphan a dependent pushed AFTER a
-    // removeOnComplete parent completed — exactly the symmetry completedJobs
-    // provides for normal parents (readiness holds for the whole bounded window).
+    releaseDependencyCompletionPins(releasedDependencyIds, ctx);
 }
 /** Move jobs from waitingDeps to the active queue */
-function promoteJobsToQueue(jobsToPromote, shard, ctx, shardIdx) {
+function promoteJobsToQueue(jobsToPromote, shard, ctx, shardIdx, releasedDependencyIds) {
     const now = Date.now();
     for (const job of jobsToPromote) {
         if (shard.waitingDeps.has(job.id)) {
+            const state = dependencyReadyState(job, now);
+            checkpointDependencyPromotion(job, state, now, ctx.storage);
             shard.waitingDeps.delete(job.id);
             shard.unregisterDependencies(job.id, job.dependsOn);
+            for (const dependencyId of job.dependsOn)
+                releasedDependencyIds.add(dependencyId);
             shard.getQueue(job.queue).push(job);
-            const isDelayed = job.runAt > now;
+            const isDelayed = state === 'delayed';
             shard.incrementQueued(job.id, isDelayed, job.createdAt, job.queue, job.runAt);
             ctx.jobIndex.set(job.id, { type: 'queue', shardIdx, queueName: job.queue });
-            if (job.timeline.length < MAX_TIMELINE_ENTRIES) {
-                const state = isDelayed ? 'delayed' : job.priority > 0 ? 'prioritized' : 'waiting';
-                job.timeline.push({ state, timestamp: now });
-            }
         }
     }
     if (jobsToPromote.length > 0) {

package/dist/application/flowFailureRecovery.d.ts

@@ -0,0 +1,20 @@
+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';
+import { type DependencyCompletionTracker } from './dependencyCompletions';
+export interface FlowFailureRecoveryContext {
+    readonly storage: SqliteStorage;
+    readonly shards: Shard[];
+    readonly jobIndex: Map<JobId, JobLocation>;
+    readonly completedJobs: SetLike<JobId>;
+    readonly depCompletions?: DependencyCompletionTracker;
+    readonly maxDependencyCompletions: number;
+    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;