bunqueue 2.8.50 → 2.8.52

package/README.md

@@ -212,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

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';
@@ -35,7 +36,7 @@ export interface ContextDependencies {
     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;

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,
@@ -86,6 +87,7 @@ export class ContextFactory {
             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,
@@ -120,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,
@@ -150,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

@@ -4,11 +4,14 @@ 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>>;

package/dist/application/flowFailureRecovery.js

@@ -1,4 +1,5 @@
 import { shardIndex } from '../shared/hash';
+import { reconcileDependencyCompletionPins, } from './dependencyCompletions';
 function findQueuedJob(ctx, id) {
     const location = ctx.jobIndex.get(id);
     if (location?.type !== 'queue')
@@ -82,11 +83,12 @@ export function recoverFlowFailures(ctx) {
             ctx.storage.updateFlowParentResolution(parent);
         }
         const ready = parent.dependsOn.length === 0 ||
-            parent.dependsOn.every((dependency) => ctx.completedJobs.has(dependency));
+            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();
+    }
+}