@tstdl/base 0.93.139 → 0.93.141

package/task-queue/tests/dependencies.test.js

@@ -1,6 +1,6 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
 import { CancellationToken } from '../../cancellation/index.js';
-import { DependencyJoinMode, TaskQueueProvider, TaskStatus } from '../../task-queue/index.js';
+import { TaskQueueProvider, TaskStatus } from '../../task-queue/index.js';
 import { setupIntegrationTest } from '../../testing/index.js';
 import { timeout } from '../../utils/timing.js';
 describe('Queue Dependencies & Tree Tests', () => {
@@ -28,35 +28,38 @@ describe('Queue Dependencies & Tree Tests', () => {
             if (task?.status == status) {
                 return;
             }
-            await queue.processPendingFanIn();
             await timeout(50);
         }
     }
-    describe('Dependencies (Fan-In)', () => {
-        it('should schedule a task only after dependency completes (completeAfterTags)', async () => {
-            // 1. Create a dependent task (Waiting)
+    describe('Dependencies (DAG)', () => {
+        it('should schedule a task only after dependency completes (completeAfter)', async () => {
+            // 1. Prereq
+            const prereq = await queue.enqueue('prereq', { val: 1 });
+            // 2. Dependent (Waiting)
             const dependent = await queue.enqueue('dependent', { foo: 'bar' }, {
-                completeAfterTags: ['tag-a'],
+                completeAfter: [prereq.id],
             });
-            expect(dependent.status).toBe(TaskStatus.Waiting);
-            // 2. Create the prerequisite task
-            const prereq = await queue.enqueue('prereq', { val: 1 }, { tags: ['tag-a'] });
+            expect(dependent.status).toBe(TaskStatus.Pending);
             // 3. Complete prereq
             const dequeued = await queue.dequeue({ types: ['prereq'] });
             expect(dequeued?.id).toBe(prereq.id);
             await queue.complete(dequeued);
-            await waitForStatus(dependent.id, TaskStatus.Completed);
+            // Complete dependent too so it reaches finalized state for waitForTasks
+            const dDependent = await queue.dequeue({ types: ['dependent'] });
+            expect(dDependent?.id).toBe(dependent.id);
+            await queue.complete(dDependent);
+            await queue.waitForTasks([dependent.id]);
             const updatedDependent = await queue.getTask(dependent.id);
             expect(updatedDependent?.status).toBe(TaskStatus.Completed);
         });
-        it('should schedule a task to run after dependency completes (scheduleAfterTags)', async () => {
-            // 1. Dependent task
+        it('should schedule a task to run after dependency completes (scheduleAfter)', async () => {
+            // 1. Prereq
+            const prereq = await queue.enqueue('prereq', {});
+            // 2. Dependent task
             const dependent = await queue.enqueue('dependent', { foo: 'bar' }, {
-                scheduleAfterTags: ['tag-b'],
+                scheduleAfter: [prereq.id],
             });
             expect(dependent.status).toBe(TaskStatus.Waiting);
-            // 2. Prereq
-            const prereq = await queue.enqueue('prereq', {}, { tags: ['tag-b'] });
             // 3. Complete prereq
             const dequeued = await queue.dequeue({ types: ['prereq'] });
             await queue.complete(dequeued);
@@ -69,29 +72,28 @@ describe('Queue Dependencies & Tree Tests', () => {
             expect(d2?.id).toBe(dependent.id);
         });
         it('should fail-fast if dependency fails', async () => {
+            const prereq = await queue.enqueue('prereq', {});
             const dependent = await queue.enqueue('dependent', {}, {
-                scheduleAfterTags: ['tag-fail'],
+                scheduleAfter: [prereq.id],
                 failFast: true
             });
-            const prereq = await queue.enqueue('prereq', {}, { tags: ['tag-fail'] });
             const dequeued = await queue.dequeue({ types: ['prereq'] });
             // Fail fatally
             await queue.fail(dequeued, new Error('boom'), { fatal: true });
-            await waitForStatus(dependent.id, TaskStatus.Dead);
+            await queue.waitForTasks([dependent.id]);
             const updatedDependent = await queue.getTask(dependent.id);
             expect(updatedDependent?.status).toBe(TaskStatus.Dead);
             expect(updatedDependent?.error?.code).toBe('DependencyFailed');
         });
-        it('should respect DependencyJoinMode.Or', async () => {
-            // Wait for tag-1 OR tag-2
+        it('should respect requiredStatuses', async () => {
+            const prereq = await queue.enqueue('prereq', {});
+            // Wait for prereq to be Dead or Completed
             const dependent = await queue.enqueue('dependent', {}, {
-                scheduleAfterTags: ['tag-1', 'tag-2'],
-                dependencyJoinMode: DependencyJoinMode.Or
+                scheduleAfter: [{ id: prereq.id, requiredStatuses: [TaskStatus.Dead, TaskStatus.Completed] }]
             });
-            // Complete tag-1 only
-            await queue.enqueue('t1', {}, { tags: ['tag-1'] });
-            const d1 = await queue.dequeue({ types: ['t1'] });
-            await queue.complete(d1);
+            // Fail fatally -> Dead
+            const d1 = await queue.dequeue({ types: ['prereq'] });
+            await queue.fail(d1, new Error('boom'), { fatal: true });
             await waitForStatus(dependent.id, TaskStatus.Pending);
             const updated = await queue.getTask(dependent.id);
             expect(updated?.status).toBe(TaskStatus.Pending);

package/task-queue/tests/extensive-dependencies.test.js

@@ -1,5 +1,5 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
-import { DependencyJoinMode, TaskQueueProvider, TaskStatus } from '../../task-queue/index.js';
+import { TaskQueueProvider, TaskStatus } from '../../task-queue/index.js';
 import { setupIntegrationTest } from '../../testing/index.js';
 import { timeout } from '../../utils/timing.js';
 describe('Extensive Task Queue Dependency Tests', () => {
@@ -26,7 +26,6 @@ describe('Extensive Task Queue Dependency Tests', () => {
             const task = await queue.getTask(id);
             if (task?.status === status)
                 return;
-            await queue.processPendingFanIn();
             await timeout(50);
         }
         const finalTask = await queue.getTask(id);
@@ -37,19 +36,18 @@ describe('Extensive Task Queue Dependency Tests', () => {
         if (!dequeued)
             throw new Error(`Could not dequeue task of type ${type}`);
         await queue.complete(dequeued);
-        await queue.processPendingFanIn();
     }
     it('should handle complex mixed chain: A -> (B -> D, C -> E) -> F', async () => {
-        // F depends on D and E
-        const taskF = await queue.enqueue('F', {}, { scheduleAfterTags: ['mc-d', 'mc-e'] });
-        // D depends on B, E depends on C
-        const taskD = await queue.enqueue('D', {}, { tags: ['mc-d'], scheduleAfterTags: ['mc-b'] });
-        const taskE = await queue.enqueue('E', {}, { tags: ['mc-e'], scheduleAfterTags: ['mc-c'] });
-        // B and C depend on A
-        const taskB = await queue.enqueue('B', {}, { tags: ['mc-b'], scheduleAfterTags: ['mc-a'] });
-        const taskC = await queue.enqueue('C', {}, { tags: ['mc-c'], scheduleAfterTags: ['mc-a'] });
         // A is the root
-        const taskA = await queue.enqueue('A', {}, { tags: ['mc-a'] });
+        const taskA = await queue.enqueue('A', {});
+        // B and C depend on A
+        const taskB = await queue.enqueue('B', {}, { scheduleAfter: [taskA.id] });
+        const taskC = await queue.enqueue('C', {}, { scheduleAfter: [taskA.id] });
+        // D depends on B, E depends on C
+        const taskD = await queue.enqueue('D', {}, { scheduleAfter: [taskB.id] });
+        const taskE = await queue.enqueue('E', {}, { scheduleAfter: [taskC.id] });
+        // F depends on D and E
+        const taskF = await queue.enqueue('F', {}, { scheduleAfter: [taskD.id, taskE.id] });
         expect(taskA.status).toBe(TaskStatus.Pending);
         expect(taskB.status).toBe(TaskStatus.Waiting);
         expect(taskC.status).toBe(TaskStatus.Waiting);
@@ -77,158 +75,85 @@ describe('Extensive Task Queue Dependency Tests', () => {
         await completeTask('E');
         await waitForStatus(taskF.id, TaskStatus.Pending);
     });
-    it('should handle requested pattern: A -> B & C -> D', async () => {
-        const taskD = await queue.enqueue('D', {}, { scheduleAfterTags: ['B', 'C'] });
-        const taskB = await queue.enqueue('B', {}, { tags: ['B'], scheduleAfterTags: ['A'] });
-        const taskC = await queue.enqueue('C', {}, { tags: ['C'], scheduleAfterTags: ['A'] });
-        const taskA = await queue.enqueue('A', {}, { tags: ['A'] });
-        // Initial check
-        expect(taskA.status).toBe(TaskStatus.Pending);
-        expect(taskB.status).toBe(TaskStatus.Waiting);
-        expect(taskC.status).toBe(TaskStatus.Waiting);
-        expect(taskD.status).toBe(TaskStatus.Waiting);
-        // Complete A
+    it('should handle Diamond Dependency (A -> B, A -> C, (B&C) -> D)', async () => {
+        const taskA = await queue.enqueue('A', {});
+        const taskB = await queue.enqueue('B', {}, { scheduleAfter: [taskA.id] });
+        const taskC = await queue.enqueue('C', {}, { scheduleAfter: [taskA.id] });
+        const taskD = await queue.enqueue('D', {}, { scheduleAfter: [taskB.id, taskC.id] });
         await completeTask('A');
         await waitForStatus(taskB.id, TaskStatus.Pending);
         await waitForStatus(taskC.id, TaskStatus.Pending);
-        // B and C can be dequeued now (in any order)
-        const dB = await queue.dequeue({ types: ['B'] });
-        const dC = await queue.dequeue({ types: ['C'] });
-        expect(dB).toBeDefined();
-        expect(dC).toBeDefined();
-        // D still waiting
-        expect((await queue.getTask(taskD.id))?.status).toBe(TaskStatus.Waiting);
-        // Complete B
-        await queue.complete(dB);
-        await queue.processPendingFanIn();
+        await completeTask('B');
         expect((await queue.getTask(taskD.id))?.status).toBe(TaskStatus.Waiting);
-        // Complete C
-        await queue.complete(dC);
+        await completeTask('C');
         await waitForStatus(taskD.id, TaskStatus.Pending);
     });
-    it('should strictly adhere to order: A -> B -> C', async () => {
-        const taskC = await queue.enqueue('C', {}, { tags: ['C'], scheduleAfterTags: ['B'] });
-        const taskB = await queue.enqueue('B', {}, { tags: ['B'], scheduleAfterTags: ['A'] });
-        const taskA = await queue.enqueue('A', {}, { tags: ['A'] });
-        // Try to dequeue B and C - should fail
-        const dC = await queue.dequeue({ types: ['C'] });
-        const dB = await queue.dequeue({ types: ['B'] });
-        expect(dC).toBeUndefined();
-        expect(dB).toBeUndefined();
-        // Complete A
-        const dA = await queue.dequeue({ types: ['A'] });
-        expect(dA?.id).toBe(taskA.id);
-        await queue.complete(dA);
-        await queue.processPendingFanIn();
-        // Now B should be available, but C still not
-        const dC_2 = await queue.dequeue({ types: ['C'] });
-        expect(dC_2).toBeUndefined();
-        const dB_2 = await queue.dequeue({ types: ['B'] });
-        expect(dB_2?.id).toBe(taskB.id);
-        await queue.complete(dB_2);
-        await queue.processPendingFanIn();
-        // Now C should be available
-        const dC_3 = await queue.dequeue({ types: ['C'] });
-        expect(dC_3?.id).toBe(taskC.id);
-        await queue.complete(dC_3);
-    });
-    it('should handle large fan-in: (T1, T2, T3, T4, T5) -> Result', async () => {
-        const tags = ['t1', 't2', 't3', 't4', 't5'];
-        const taskResult = await queue.enqueue('Result', {}, { scheduleAfterTags: tags });
-        for (const tag of tags) {
-            await queue.enqueue(`Task-${tag}`, {}, { tags: [tag] });
-        }
-        // Complete all but one
-        for (let i = 0; i < 4; i++) {
-            await completeTask(`Task-${tags[i]}`);
-            expect((await queue.getTask(taskResult.id))?.status).toBe(TaskStatus.Waiting);
-        }
-        // Complete the last one
-        await completeTask(`Task-${tags[4]}`);
-        await waitForStatus(taskResult.id, TaskStatus.Pending);
+    it('should handle Deep Chain (A -> B -> C -> D)', async () => {
+        const taskA = await queue.enqueue('A', {});
+        const taskB = await queue.enqueue('B', {}, { scheduleAfter: [taskA.id] });
+        const taskC = await queue.enqueue('C', {}, { scheduleAfter: [taskB.id] });
+        const taskD = await queue.enqueue('D', {}, { scheduleAfter: [taskC.id] });
+        await completeTask('A');
+        await waitForStatus(taskB.id, TaskStatus.Pending);
+        await completeTask('B');
+        await waitForStatus(taskC.id, TaskStatus.Pending);
+        await completeTask('C');
+        await waitForStatus(taskD.id, TaskStatus.Pending);
     });
-    it('should handle large fan-in with OR: (T1, T2, T3, T4, T5) -> Result', async () => {
-        const tags = ['o1', 'o2', 'o3', 'o4', 'o5'];
-        const taskResult = await queue.enqueue('Result', {}, {
-            scheduleAfterTags: tags,
-            dependencyJoinMode: DependencyJoinMode.Or
-        });
-        for (const tag of tags) {
-            await queue.enqueue(`Task-${tag}`, {}, { tags: [tag] });
+    it('should handle wide fan-out (A -> [B1...B50] -> C)', async () => {
+        const taskA = await queue.enqueue('A', {});
+        const bTasks = await queue.enqueueMany(Array.from({ length: 50 }, (_, i) => ({ type: `B${i}`, data: {}, scheduleAfter: [taskA.id] })), { returnTasks: true });
+        const taskC = await queue.enqueue('C', {}, { scheduleAfter: bTasks.map(t => t.id) });
+        await completeTask('A');
+        for (let i = 0; i < 49; i++) {
+            await completeTask(`B${i}`);
+            expect((await queue.getTask(taskC.id))?.status).toBe(TaskStatus.Waiting);
         }
-        // Complete one
-        await completeTask(`Task-${tags[2]}`);
-        await waitForStatus(taskResult.id, TaskStatus.Pending);
+        await completeTask('B49');
+        await waitForStatus(taskC.id, TaskStatus.Pending);
     });
-    it('should handle Diamond of Diamonds: A -> (B1, B2) -> C -> (D1, D2) -> E', async () => {
-        const taskE = await queue.enqueue('E', {}, { scheduleAfterTags: ['tag-d1', 'tag-d2'] });
-        const taskD1 = await queue.enqueue('D1', {}, { tags: ['tag-d1'], scheduleAfterTags: ['tag-c'] });
-        const taskD2 = await queue.enqueue('D2', {}, { tags: ['tag-d2'], scheduleAfterTags: ['tag-c'] });
-        const taskC = await queue.enqueue('C', {}, { tags: ['tag-c'], scheduleAfterTags: ['tag-b1', 'tag-b2'] });
-        const taskB1 = await queue.enqueue('B1', {}, { tags: ['tag-b1'], scheduleAfterTags: ['tag-a'] });
-        const taskB2 = await queue.enqueue('B2', {}, { tags: ['tag-b2'], scheduleAfterTags: ['tag-a'] });
-        const taskA = await queue.enqueue('A', {}, { tags: ['tag-a'] });
-        // Step by step completion
+    it('should handle deep tree with branching and merging', async () => {
+        const taskA = await queue.enqueue('A', {});
+        const taskB1 = await queue.enqueue('B1', {}, { scheduleAfter: [taskA.id] });
+        const taskB2 = await queue.enqueue('B2', {}, { scheduleAfter: [taskA.id] });
+        const taskC = await queue.enqueue('C', {}, { scheduleAfter: [taskB1.id, taskB2.id] });
+        const taskD1 = await queue.enqueue('D1', {}, { scheduleAfter: [taskC.id] });
+        const taskD2 = await queue.enqueue('D2', {}, { scheduleAfter: [taskC.id] });
+        const taskE = await queue.enqueue('E', {}, { scheduleAfter: [taskD1.id, taskD2.id] });
         await completeTask('A');
-        await waitForStatus(taskB1.id, TaskStatus.Pending);
-        await waitForStatus(taskB2.id, TaskStatus.Pending);
         await completeTask('B1');
-        expect((await queue.getTask(taskC.id))?.status).toBe(TaskStatus.Waiting);
         await completeTask('B2');
         await waitForStatus(taskC.id, TaskStatus.Pending);
         await completeTask('C');
         await waitForStatus(taskD1.id, TaskStatus.Pending);
         await waitForStatus(taskD2.id, TaskStatus.Pending);
         await completeTask('D1');
-        expect((await queue.getTask(taskE.id))?.status).toBe(TaskStatus.Waiting);
         await completeTask('D2');
         await waitForStatus(taskE.id, TaskStatus.Pending);
     });
-    it('should fail-fast entire branch if one dependency fails fatal', async () => {
-        // A -> B -> C
-        //   -> D -> E
-        // (C & E) -> F
-        const taskF = await queue.enqueue('F', {}, { scheduleAfterTags: ['C', 'E'], failFast: true });
-        const taskC = await queue.enqueue('C', {}, { tags: ['C'], scheduleAfterTags: ['B'], failFast: true });
-        const taskE = await queue.enqueue('E', {}, { tags: ['E'], scheduleAfterTags: ['D'], failFast: true });
-        const taskB = await queue.enqueue('B', {}, { tags: ['B'], scheduleAfterTags: ['A'], failFast: true });
-        const taskD = await queue.enqueue('D', {}, { tags: ['D'], scheduleAfterTags: ['A'], failFast: true });
-        const taskA = await queue.enqueue('A', {}, { tags: ['A'] });
-        await completeTask('A');
-        await waitForStatus(taskB.id, TaskStatus.Pending);
-        await waitForStatus(taskD.id, TaskStatus.Pending);
-        // Fail B fatally
-        const dB = await queue.dequeue({ types: ['B'] });
-        await queue.fail(dB, new Error('fatal B'), { fatal: true });
-        await queue.processPendingFanIn();
-        // B failed fatally -> C should die -> F should die
+    it('should handle fail-fast cascade', async () => {
+        const taskA = await queue.enqueue('A', {});
+        const taskB = await queue.enqueue('B', {}, { scheduleAfter: [taskA.id], failFast: true });
+        const taskC = await queue.enqueue('C', {}, { scheduleAfter: [taskB.id], failFast: true });
+        const taskD = await queue.enqueue('D', {}, { scheduleAfter: [taskA.id], failFast: true });
+        const taskE = await queue.enqueue('E', {}, { scheduleAfter: [taskC.id, taskD.id], failFast: true });
+        const dA = await queue.dequeue({ types: ['A'] });
+        await queue.fail(dA, new Error('fatal'), { fatal: true });
+        await waitForStatus(taskB.id, TaskStatus.Dead);
         await waitForStatus(taskC.id, TaskStatus.Dead);
-        await waitForStatus(taskF.id, TaskStatus.Dead);
-        // D and E should be unaffected (except E is still waiting for D)
-        const uD = await queue.getTask(taskD.id);
-        expect(uD?.status).toBe(TaskStatus.Pending);
+        await waitForStatus(taskD.id, TaskStatus.Dead);
+        await waitForStatus(taskE.id, TaskStatus.Dead);
     });
-    it('should handle many-to-many dependencies', async () => {
-        // {A, B} -> {C, D} -> {E, F}
-        // Each of C, D depends on BOTH A and B.
-        // Each of E, F depends on BOTH C and D.
-        const taskE = await queue.enqueue('E', {}, { scheduleAfterTags: ['C', 'D'] });
-        const taskF = await queue.enqueue('F', {}, { scheduleAfterTags: ['C', 'D'] });
-        const taskC = await queue.enqueue('C', {}, { tags: ['C'], scheduleAfterTags: ['A', 'B'] });
-        const taskD = await queue.enqueue('D', {}, { tags: ['D'], scheduleAfterTags: ['A', 'B'] });
-        const taskA = await queue.enqueue('A', {}, { tags: ['A'] });
-        const taskB = await queue.enqueue('B', {}, { tags: ['B'] });
+    it('should NOT schedule if only one of two dependencies is met (AND logic)', async () => {
+        const taskA = await queue.enqueue('A', {});
+        const taskB = await queue.enqueue('B', {});
+        const taskC = await queue.enqueue('C', {}, { scheduleAfter: [taskA.id, taskB.id] });
         await completeTask('A');
         expect((await queue.getTask(taskC.id))?.status).toBe(TaskStatus.Waiting);
-        expect((await queue.getTask(taskD.id))?.status).toBe(TaskStatus.Waiting);
+        // Still waiting even after some time
+        await timeout(100);
+        expect((await queue.getTask(taskC.id))?.status).toBe(TaskStatus.Waiting);
         await completeTask('B');
         await waitForStatus(taskC.id, TaskStatus.Pending);
-        await waitForStatus(taskD.id, TaskStatus.Pending);
-        await completeTask('C');
-        expect((await queue.getTask(taskE.id))?.status).toBe(TaskStatus.Waiting);
-        expect((await queue.getTask(taskF.id))?.status).toBe(TaskStatus.Waiting);
-        await completeTask('D');
-        await waitForStatus(taskE.id, TaskStatus.Pending);
-        await waitForStatus(taskF.id, TaskStatus.Pending);
     });
 });

package/task-queue/tests/fan-out-spawning.test.d.ts

@@ -0,0 +1 @@
+export {};

package/task-queue/tests/fan-out-spawning.test.js

@@ -0,0 +1,53 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { TaskQueueProvider, TaskStatus } from '../../task-queue/index.js';
+import { setupIntegrationTest } from '../../testing/index.js';
+import { timeout } from '../../utils/timing.js';
+describe('Fan-Out Spawning', () => {
+    let injector;
+    let queue;
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
+    });
+    beforeEach(() => {
+        const queueProvider = injector.resolve(TaskQueueProvider);
+        const queueName = `fan-out-queue-${Date.now()}-${Math.random()}`;
+        queue = queueProvider.get(queueName, {
+            visibilityTimeout: 1000,
+        });
+    });
+    afterEach(async () => {
+        await queue.clear();
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    it('should transition parent to Waiting when spawning children during execution', async () => {
+        const parent = await queue.enqueue('parent', {});
+        const dParent = await queue.dequeue();
+        expect(dParent?.id).toBe(parent.id);
+        // Parent spawns a child
+        const [child] = await queue.enqueueMany([{ type: 'child', data: {}, parentId: parent.id }], { returnTasks: true });
+        // Complete parent
+        await queue.complete(dParent);
+        // Parent should be Waiting for child
+        const uParent = await queue.getTask(parent.id);
+        expect(uParent?.status).toBe(TaskStatus.WaitingChildren);
+        expect(uParent?.unresolvedCompleteDependencies).toBe(1);
+        // Complete child
+        const dChild = await queue.dequeue();
+        await queue.complete(dChild);
+        // Parent should now be Completed
+        const fParent = await queue.getTask(parent.id);
+        expect(fParent?.status).toBe(TaskStatus.Completed);
+    });
+    it('should NOT transition parent to Waiting if waitForCompletion is false', async () => {
+        const parent = await queue.enqueue('parent', {});
+        const dParent = await queue.dequeue();
+        // Spawn child with waitForCompletion: false
+        await queue.enqueueMany([{ type: 'child', data: {}, parentId: parent.id, waitForCompletion: false }], { returnTasks: true });
+        await queue.complete(dParent);
+        const uParent = await queue.getTask(parent.id);
+        expect(uParent?.status).toBe(TaskStatus.Completed); // Finished immediately
+        expect(uParent?.unresolvedCompleteDependencies).toBe(0);
+    });
+});

package/task-queue/tests/idempotent-replacement.test.d.ts

@@ -0,0 +1 @@
+export {};

package/task-queue/tests/idempotent-replacement.test.js

@@ -0,0 +1,61 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { TaskQueueProvider, TaskStatus } from '../../task-queue/index.js';
+import { setupIntegrationTest } from '../../testing/index.js';
+import { timeout } from '../../utils/timing.js';
+describe('Idempotent Replacement', () => {
+    let injector;
+    let queue;
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
+    });
+    beforeEach(() => {
+        const queueProvider = injector.resolve(TaskQueueProvider);
+        const queueName = `idempotent-queue-${Date.now()}-${Math.random()}`;
+        queue = queueProvider.get(queueName, {
+            visibilityTimeout: 1000,
+        });
+    });
+    afterEach(async () => {
+        await queue.clear();
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    it('should NOT be affected by "ghost" dependencies after replacement', async () => {
+        const depA = await queue.enqueue('depA', {});
+        const depB = await queue.enqueue('depB', {});
+        const depC = await queue.enqueue('depC', {});
+        const idempotencyKey = 'my-idempotent-task';
+        // 1. Initial enqueue with A and B
+        const taskV1 = await queue.enqueue('main', { version: 1 }, {
+            idempotencyKey,
+            scheduleAfter: [depA.id, depB.id],
+        });
+        expect(taskV1.status).toBe(TaskStatus.Waiting);
+        expect(taskV1.unresolvedScheduleDependencies).toBe(2);
+        // 2. Replacement enqueue with only C
+        const taskV2 = await queue.enqueue('main', { version: 2 }, {
+            idempotencyKey,
+            scheduleAfter: [depC.id],
+            replace: true,
+        });
+        expect(taskV2.id).toBe(taskV1.id);
+        expect(taskV2.unresolvedScheduleDependencies).toBe(1);
+        expect(taskV2.data).toEqual({ version: 2 });
+        // 3. Complete an OLD dependency (depA)
+        const dDepA = await queue.dequeue({ types: ['depA'] });
+        await queue.complete(dDepA);
+        // Give it a moment to process background dependency resolution if any
+        await timeout(100);
+        // 4. Verify main task is STILL waiting for depC
+        const uTask = await queue.getTask(taskV1.id);
+        expect(uTask?.status).toBe(TaskStatus.Waiting);
+        expect(uTask?.unresolvedScheduleDependencies).toBe(1);
+        // 5. Complete NEW dependency (depC)
+        const dDepC = await queue.dequeue({ types: ['depC'] });
+        await queue.complete(dDepC);
+        // 6. Verify main task is now Pending
+        const fTask = await queue.getTask(taskV1.id);
+        expect(fTask?.status).toBe(TaskStatus.Pending);
+    });
+});

package/task-queue/tests/missing-idempotent-tasks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/task-queue/tests/missing-idempotent-tasks.test.js

@@ -0,0 +1,38 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { TaskQueueProvider } from '../../task-queue/index.js';
+import { setupIntegrationTest } from '../../testing/index.js';
+describe('Missing Idempotent Tasks Bug', () => {
+    let injector;
+    let queue;
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
+    });
+    beforeEach(() => {
+        const queueProvider = injector.resolve(TaskQueueProvider);
+        const queueName = `missing-idem-queue-${Date.now()}-${Math.random()}`;
+        queue = queueProvider.get(queueName, {
+            visibilityTimeout: 1000,
+        });
+    });
+    afterEach(async () => {
+        await queue.clear();
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    it('should NOT crash when enqueuing duplicate idempotent tasks with dependencies and returnTasks: false', async () => {
+        const key = 'idem-key';
+        const dep = await queue.enqueue('dep', {});
+        // 1. Initial enqueue
+        await queue.enqueue('main', {}, { idempotencyKey: key });
+        // 2. Second enqueue with same key and a dependency, returnTasks: false
+        // This should NOT crash.
+        // It should ideally either:
+        // a) Ignore the new dependency because it's a duplicate and replace=false
+        // b) Add the dependency to the existing task (though replace=false usually means ignore)
+        // The current bug is that it CRASHES with TypeError.
+        await expect(queue.enqueueMany([
+            { type: 'main', data: {}, idempotencyKey: key, scheduleAfter: [dep.id] }
+        ], { replace: false, returnTasks: false })).resolves.toBeUndefined();
+    });
+});