@tstdl/base 0.93.182 → 0.93.183

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

@@ -1,756 +0,0 @@
-import { eq, or } from 'drizzle-orm';
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
-import { CancellationToken } from '../../cancellation/index.js';
-import { CircuitBreaker, CircuitBreakerState } from '../../circuit-breaker/index.js';
-import { Database } from '../../orm/server/index.js';
-import { TaskQueueProvider, TaskStatus } from '../../task-queue/index.js';
-import { task as taskTable } from '../../task-queue/postgres/schemas.js';
-import { setupIntegrationTest } from '../../testing/index.js';
-import { currentTimestamp } from '../../utils/date-time.js';
-import { Timer } from '../../utils/timer.js';
-import { timeout } from '../../utils/timing.js';
-import { isDefined } from '../../utils/type-guards.js';
-describe('Queue Integration Tests', () => {
-    let injector;
-    let queue;
-    // Helper to verify state in DB
-    async function assertTaskStatus(id, state, message) {
-        const task = await queue.getTask(id);
-        expect(task?.status, message).toBe(state);
-    }
-    beforeAll(async () => {
-        ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
-    });
-    beforeEach(async () => {
-        const queueProvider = injector.resolve(TaskQueueProvider);
-        const queueName = `test-queue-${crypto.randomUUID()}`;
-        queue = queueProvider.get(queueName, {
-            visibilityTimeout: 5000,
-            retryDelayMinimum: 100, // Fast retries for testing
-            retryDelayGrowth: 1, // Linear/No growth for predictable tests
-        });
-    });
-    afterEach(async () => {
-        // Drain the queue to prevent state leakage between tests
-        await queue.clear();
-    });
-    afterAll(async () => {
-        try {
-            if (isDefined(queue)) {
-                await queue.clear();
-            }
-            await injector.dispose();
-        }
-        catch (error) {
-            // Ignore known double-dispose issue from MessageBus interaction
-            if (error instanceof Error && error.message === 'MessageBus is disposed.') {
-                return;
-            }
-            throw error;
-        }
-    });
-    it('Basic FIFO Flow', async () => {
-        const t1 = await queue.enqueue('test', { value: 'first' });
-        const t2 = await queue.enqueue('test', { value: 'second' });
-        const d1 = await queue.dequeue();
-        expect(d1?.id).toBe(t1.id);
-        expect((d1?.data)['value']).toBe('first');
-        await queue.complete(d1, { result: { success: true } });
-        await assertTaskStatus(t1.id, TaskStatus.Completed, 'Task 1 completed');
-        const d2 = await queue.dequeue();
-        expect(d2?.id).toBe(t2.id);
-        await queue.complete(d2, { result: { success: true } });
-    });
-    it('Priorities', async () => {
-        // Priority 1000 (default)
-        const low = await queue.enqueue('test', { value: 'low' });
-        // Priority 1
-        const high = await queue.enqueue('test', { value: 'high' }, { priority: 1 });
-        const first = await queue.dequeue();
-        expect(first?.id).toBe(high.id);
-        await queue.complete(first);
-        const second = await queue.dequeue();
-        expect(second?.id).toBe(low.id);
-        await queue.complete(second);
-    });
-    it('Deduplication (Idempotency Keys)', async () => {
-        const key = `unique-${crypto.randomUUID()}`;
-        // 1. Initial Insert
-        const t1 = await queue.enqueue('test', { value: 'original' }, { idempotencyKey: key });
-        // 2. Default Strategy (replace: false): Should return existing task, ignore new data
-        const t2 = await queue.enqueue('test', { value: 'ignored' }, { idempotencyKey: key });
-        expect(t2.id, 'Same ID if not replaced').toBe(t1.id);
-        const check1 = await queue.getTask(t1.id);
-        expect((check1?.data)['value']).toBe('original');
-        // 3. Replace Strategy: Should replace existing task with new data. ID stays the same to avoid foreign key violations.
-        const t3 = await queue.enqueueMany([{ type: 'test', data: { value: 'updated' }, idempotencyKey: key }], { replace: true, returnTasks: true });
-        expect(t3[0].id, 'Same ID if replaced').toBe(t1.id);
-        // New task should have new data
-        const checkNew = await queue.getTask(t3[0].id);
-        expect((checkNew?.data)['value']).toBe('updated');
-        expect(checkNew?.tries).toBe(0);
-    });
-    it('Retries and Failures', async () => {
-        const task = await queue.enqueue('test', { value: 'fail-me' });
-        // Try 1
-        const attempt1 = await queue.dequeue();
-        expect(attempt1?.id).toBe(task.id);
-        await queue.fail(attempt1, { message: 'oops' });
-        // Verify Retrying status
-        await assertTaskStatus(task.id, TaskStatus.Retrying, 'Task enters Retrying status after failure');
-        // Force reschedule to now to bypass retryDelay
-        await queue.reschedule(task.id, currentTimestamp());
-        // Try 2
-        const attempt2 = await queue.dequeue();
-        expect(attempt2?.id).toBe(task.id);
-        expect(attempt2?.tries).toBe(2);
-        // Fail fatally
-        await queue.fail(attempt2, { message: 'fatal error' }, { fatal: true });
-        await assertTaskStatus(task.id, TaskStatus.Dead, 'Task is Dead after fatal error');
-    });
-    it('Hierarchy (Parent/Child)', async () => {
-        // A. Create Parent
-        const p = await queue.enqueue('test', { value: 'parent-manual' });
-        // B. Dequeue Parent
-        const pTask = await queue.dequeue();
-        expect(pTask?.id).toBe(p.id);
-        // C. Parent spawns child
-        const child = await queue.enqueue('test', { value: 'child-manual' }, { parentId: p.id });
-        // D. "Finish" Parent execution.
-        await queue.complete(pTask);
-        // await assertTaskStatus(p.id, TaskStatus.Waiting, 'Parent entered WAITING state'); // Depends on implementation details of auto-waiting
-    });
-    it('Batching', async () => {
-        const batch = queue.batch();
-        for (let i = 0; i < 5; i++) {
-            batch.add('test', { value: `batch-${i}` });
-        }
-        const tasks = await batch.enqueue({ returnTasks: true });
-        expect(tasks.length).toBe(5);
-        const dequeuedBatch = await queue.dequeueMany(5);
-        expect(dequeuedBatch.length).toBe(5);
-        await queue.completeMany(dequeuedBatch);
-        const leftover = await queue.dequeue();
-        expect(leftover).toBeUndefined();
-    });
-});
-describe('PostgresQueue (Distributed Task Orchestration)', () => {
-    let injector;
-    let queue;
-    let database;
-    beforeAll(async () => {
-        ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
-        database = injector.resolve(Database);
-    });
-    beforeEach(() => {
-        const queueProvider = injector.resolve(TaskQueueProvider);
-        const queueName = `pg-test-queue-${crypto.randomUUID()}`;
-        queue = queueProvider.get(queueName, {
-            visibilityTimeout: 50, // Short timeout for testing
-            retryDelayMinimum: 50,
-            retryDelayGrowth: 1,
-            circuitBreakerThreshold: 2,
-            circuitBreakerResetTimeout: 50,
-        });
-    });
-    afterEach(async () => {
-        await queue.clear();
-    });
-    afterAll(async () => {
-        await injector?.dispose();
-    });
-    describe('Basic Lifecycle', () => {
-        it('should enqueue and dequeue a task', async () => {
-            await queue.enqueue('foo', { foo: 'bar' });
-            const task = await queue.dequeue();
-            expect(task).toBeDefined();
-            expect(task?.data).toEqual({ foo: 'bar' });
-            expect(task?.status).toBe(TaskStatus.Running);
-            expect(task?.tries).toBe(1);
-        });
-        it('should complete a task successfully', async () => {
-            const task = await queue.enqueue('foo', { foo: 'bar' });
-            const dequeued = await queue.dequeue();
-            await queue.complete(dequeued, { result: { result: true } });
-            const updated = await queue.getTask(task.id);
-            expect(updated?.status).toBe(TaskStatus.Completed);
-            expect(updated?.result).toEqual({ result: true });
-            expect(updated.completeTimestamp > 0).toBe(true);
-        });
-        it('should fail a task and increment tries', async () => {
-            const task = await queue.enqueue('foo', { foo: 'bar' });
-            const dequeued = await queue.dequeue();
-            await queue.fail(dequeued, new Error('temp failure'));
-            const updated = await queue.getTask(task.id);
-            expect(updated?.status).toBe(TaskStatus.Retrying);
-            expect(updated?.tries).toBe(1);
-            expect(updated?.errors).toHaveLength(1);
-        });
-        it('should NOT clear startTimestamp when transitioning to terminal or retry states', async () => {
-            // Re-create queue with high circuit breaker threshold for this test
-            const q = injector.resolve(TaskQueueProvider).get(`start-timestamp-${crypto.randomUUID()}`, {
-                circuitBreakerThreshold: 10,
-            });
-            const task = await q.enqueue('foo', { foo: 'bar' });
-            // 1. Dequeue to start it (sets startTimestamp)
-            const dequeued = await q.dequeue();
-            expect(dequeued?.startTimestamp).not.toBeNull();
-            const startTimestamp = dequeued.startTimestamp;
-            // 2. Fail it (transitions to Retrying)
-            await q.fail(dequeued, new Error('temp failure'));
-            const retryingTask = await q.getTask(task.id);
-            expect(retryingTask?.status).toBe(TaskStatus.Retrying);
-            expect(retryingTask?.startTimestamp).toBe(startTimestamp);
-            // 3. Dequeue again (updates startTimestamp)
-            await q.reschedule(task.id, currentTimestamp());
-            const dequeued2 = await q.dequeue();
-            expect(dequeued2?.startTimestamp).not.toBe(startTimestamp);
-            const startTimestamp2 = dequeued2.startTimestamp;
-            // 4. Fail fatally (transitions to Dead)
-            await q.fail(dequeued2, new Error('fatal failure'), { fatal: true });
-            const deadTask = await q.getTask(task.id);
-            expect(deadTask?.status).toBe(TaskStatus.Dead);
-            expect(deadTask?.startTimestamp).toBe(startTimestamp2);
-            // 5. Success (transitions to Completed)
-            const task2 = await q.enqueue('foo', { foo: 'bar2' });
-            const dequeued3 = await q.dequeue();
-            expect(dequeued3).toBeDefined();
-            const startTimestamp3 = dequeued3.startTimestamp;
-            await q.complete(dequeued3);
-            const completedTask = await q.getTask(task2.id);
-            expect(completedTask?.status).toBe(TaskStatus.Completed);
-            expect(completedTask?.startTimestamp).toBe(startTimestamp3);
-            await q.clear();
-        });
-    });
-    describe('Hierarchy and Cross-Namespace', () => {
-        it('should correctly increment parent unresolved dependencies when a child is spawned in a different namespace', async () => {
-            const queueProvider = injector.resolve(TaskQueueProvider);
-            const nameA = `QueueA-${crypto.randomUUID()}`;
-            const nameB = `QueueB-${crypto.randomUUID()}`;
-            const queueA = queueProvider.get(nameA);
-            const queueB = queueProvider.get(nameB);
-            const parent = await queueA.enqueue('test', { value: 'parent' });
-            expect(parent.unresolvedCompleteDependencies).toBe(0);
-            await queueB.enqueue('test', { value: 'child' }, { parentId: parent.id, parentRequires: true });
-            const updatedParent = await queueA.getTask(parent.id);
-            expect(updatedParent?.unresolvedCompleteDependencies).toBe(1);
-            await database.update(taskTable).set({ parentId: null }).where(or(eq(taskTable.namespace, nameA), eq(taskTable.namespace, nameB)));
-            await queueB.clear();
-            await queueA.clear();
-        });
-        it('should recursively cancel the entire task tree spanning multiple namespaces', async () => {
-            const queueProvider = injector.resolve(TaskQueueProvider);
-            const nameA = `NamespaceA-${crypto.randomUUID()}`;
-            const nameB = `NamespaceB-${crypto.randomUUID()}`;
-            const queueA = queueProvider.get(nameA);
-            const queueB = queueProvider.get(nameB);
-            const parent = await queueA.enqueue('test', { value: 'parent' });
-            const child = await queueB.enqueue('test', { value: 'child' }, { parentId: parent.id });
-            const grandchild = await queueA.enqueue('test', { value: 'grandchild' }, { parentId: child.id });
-            await queueA.cancel(parent.id);
-            await queueB.waitForTasks([child.id], { statuses: [TaskStatus.Cancelled] });
-            await queueA.waitForTasks([grandchild.id], { statuses: [TaskStatus.Cancelled] });
-            const updatedChild = await queueB.getTask(child.id);
-            const updatedGrandchild = await queueA.getTask(grandchild.id);
-            expect(updatedChild?.status).toBe(TaskStatus.Cancelled);
-            expect(updatedGrandchild?.status).toBe(TaskStatus.Cancelled);
-            await database.update(taskTable).set({ parentId: null }).where(or(eq(taskTable.namespace, nameA), eq(taskTable.namespace, nameB)));
-            await queueB.clear();
-            await queueA.clear();
-        });
-        it('should successfully cancel tasks from other namespaces (Bug 4)', async () => {
-            const queueProvider = injector.resolve(TaskQueueProvider);
-            const nameA = `QueueA-${crypto.randomUUID()}`;
-            const nameB = `QueueB-${crypto.randomUUID()}`;
-            const queueA = queueProvider.get(nameA);
-            const queueB = queueProvider.get(nameB);
-            // 1. Enqueue task in queueB
-            const taskB = await queueB.enqueue('test', {});
-            expect(taskB.status).toBe(TaskStatus.Pending);
-            // 2. Cancel task in queueA (using taskB.id which is from other namespace)
-            await queueA.cancel(taskB.id);
-            // 3. Verify taskB IS cancelled (because ID is global)
-            const updatedB = await queueB.getTask(taskB.id);
-            expect(updatedB?.status).toBe(TaskStatus.Cancelled);
-            await database.update(taskTable).set({ parentId: null }).where(or(eq(taskTable.namespace, nameA), eq(taskTable.namespace, nameB)));
-            await queueB.clear();
-            await queueA.clear();
-        });
-        it('should complete parent task if idempotent child is already completed (Bug 6)', async () => {
-            const q = injector.resolve(TaskQueueProvider).get(`q-${crypto.randomUUID()}`);
-            // 1. Enqueue and complete child task with idempotency key
-            const idempotencyKey = 'child-idempotency-key';
-            const child = await q.enqueue('test', {}, { idempotencyKey });
-            const dequeuedChild = await q.dequeue();
-            await q.complete(dequeuedChild);
-            const finishedChild = await q.getTask(child.id);
-            expect(finishedChild?.status).toBe(TaskStatus.Completed);
-            // 2. Enqueue parent task that spawns the same child (via idempotency key)
-            const parent = await q.enqueue('test', {});
-            await q.enqueue('test', {}, {
-                idempotencyKey,
-                parentId: parent.id,
-                parentRequires: true,
-            });
-            // Dequeue and complete parent
-            const dequeuedParent = await q.dequeue();
-            await q.complete(dequeuedParent);
-            const updatedParent = await q.getTask(parent.id);
-            expect(updatedParent?.status).toBe(TaskStatus.Completed);
-            await q.clear();
-        });
-        it('should increment unresolvedCompleteDependencies for children with parentRequires: true (Bug 6-2)', async () => {
-            const parent = await queue.enqueue('parent', {});
-            expect(parent.unresolvedCompleteDependencies).toBe(0);
-            await queue.enqueue('child', {}, { parentId: parent.id, parentRequires: true });
-            const updatedParent = await queue.getTask(parent.id);
-            expect(updatedParent?.unresolvedCompleteDependencies).toBe(1);
-        });
-    });
-    describe('Priority and Scheduling', () => {
-        it('should dequeue tasks in priority order (lower number first)', async () => {
-            await queue.enqueue('foo', { foo: 'low' }, { priority: 2000 });
-            await queue.enqueue('foo', { foo: 'high' }, { priority: 10 });
-            await queue.enqueue('foo', { foo: 'mid' }, { priority: 1000 });
-            const t1 = await queue.dequeue();
-            const t2 = await queue.dequeue();
-            const t3 = await queue.dequeue();
-            expect((t1?.data)['foo']).toBe('high');
-            expect((t2?.data)['foo']).toBe('mid');
-            expect((t3?.data)['foo']).toBe('low');
-        });
-        it('should not dequeue a task scheduled in the future', async () => {
-            const future = currentTimestamp() + 100;
-            await queue.enqueue('foo', { foo: 'future' }, { scheduleTimestamp: future });
-            const task = await queue.dequeue();
-            expect(task).toBeUndefined();
-            await timeout(150);
-            const taskLater = await queue.dequeue();
-            expect(taskLater).toBeDefined();
-        });
-    });
-    describe('Concurrency Control', () => {
-        it('should refund the rate limiter tokens when dequeueMany retrieves fewer tasks than requested', async () => {
-            const q = injector.resolve(TaskQueueProvider).get(`q-${crypto.randomUUID()}`, {
-                rateLimit: 5,
-                rateInterval: 60000,
-            });
-            await q.enqueue('test', { value: '1' });
-            const tasks1 = await q.dequeueMany(5); // Consumes 5, gets 1, refunds 4.
-            expect(tasks1).toHaveLength(1);
-            await q.enqueue('test', { value: '2' });
-            const tasks2 = await q.dequeueMany(4); // Should be allowed because of refund.
-            expect(tasks2).toHaveLength(1);
-            await q.clear();
-        });
-    });
-    describe('Circuit Breaker', () => {
-        it('should trip the breaker after threshold failures', async () => {
-            // Config: circuitBreakerThreshold: 2 (set in beforeEach)
-            await queue.enqueue('foo', { foo: '1' });
-            await queue.enqueue('foo', { foo: '2' });
-            await queue.enqueue('foo', { foo: '3' });
-            await queue.fail((await queue.dequeue()), 'err');
-            await queue.fail((await queue.dequeue()), 'err');
-            // Breaker should be Open
-            const t3Attempt = await queue.dequeue();
-            expect(t3Attempt).toBeUndefined();
-        });
-        it('should only allow a single active task in Half-Open state', async () => {
-            await queue.enqueueMany([
-                { type: 'foo', data: { foo: '1' } },
-                { type: 'foo', data: { foo: '2' } },
-            ]);
-            await queue.fail((await queue.dequeue()), 'err');
-            await queue.fail((await queue.dequeue()), 'err');
-            // Breaker is Open. Wait for reset timeout (50ms)
-            await timeout(75);
-            const probe = await queue.dequeue();
-            expect(probe).toBeDefined();
-            const secondAttempt = await queue.dequeue();
-            expect(secondAttempt).toBeUndefined(); // Only 1 task allowed to RUN in Half-Open
-        });
-        it('should not stall forever when circuit breaker is Half-Open and no tasks are found', async () => {
-            // 1. Trip the breaker
-            await queue.enqueue('foo', { foo: '1' });
-            await queue.enqueue('foo', { foo: '2' });
-            await queue.fail((await queue.dequeue()), 'err', { fatal: true });
-            await queue.fail((await queue.dequeue()), 'err', { fatal: true });
-            const cb = injector.resolve(CircuitBreaker, queue.namespace);
-            let status = await cb.check();
-            expect(status.state).toBe(CircuitBreakerState.Open);
-            expect(status.allowed).toBe(false);
-            // 2. Wait for timeout (50ms)
-            await timeout(75);
-            // 3. First dequeue - should be the probe, but find nothing (we enqueued and failed the only task)
-            const tasks1 = await queue.dequeueMany(1);
-            expect(tasks1).toHaveLength(0);
-            status = await cb.check();
-            expect(status.state).toBe(CircuitBreakerState.HalfOpen);
-            // 4. Second dequeue - should still be allowed (but find nothing)
-            const tasks2 = await queue.dequeueMany(1);
-            expect(tasks2).toHaveLength(0);
-            // 5. Add a task
-            await queue.enqueue('foo', { foo: 'new' });
-            // 6. Third dequeue - should find the task now!
-            const tasks3 = await queue.dequeueMany(1);
-            expect(tasks3).toHaveLength(1);
-        });
-    });
-    describe('Timeouts and Maintenance (Pruning)', () => {
-        it('should recover "Zombie" tasks (crashed workers) and preserve startTimestamp', async () => {
-            const task = await queue.enqueue('foo', { foo: 'zombie' });
-            const dequeued = await queue.dequeue(); // Task is now Running with a token
-            expect(dequeued?.startTimestamp).not.toBeNull();
-            const startTimestamp = dequeued.startTimestamp;
-            // processTimeout is 50ms. Wait for it to expire.
-            await timeout(100);
-            await queue.maintenance();
-            const recovered = await queue.getTask(task.id);
-            expect(recovered?.status).toBe(TaskStatus.Retrying);
-            expect(recovered?.tries).toBe(1);
-            expect(recovered?.token).toBeNull();
-            expect(recovered?.startTimestamp).toBe(startTimestamp);
-        });
-        it('should fail tasks that exceed Hard Execution Timeout via prune', async () => {
-            // Re-configure queue with very short execution timeout
-            const queueProvider = injector.resolve(TaskQueueProvider);
-            const shortQueue = queueProvider.get(`prune-test-${crypto.randomUUID()}`, { maxExecutionTime: 50 });
-            const task = await shortQueue.enqueue('foo', { foo: 'long-running' });
-            await shortQueue.dequeue();
-            await timeout(75);
-            await shortQueue.maintenance();
-            const updated = await shortQueue.getTask(task.id);
-            expect(updated?.status).toBe(TaskStatus.TimedOut);
-            expect(updated?.errors[0]?.code).toBe('MaxTimeExceeded');
-            await shortQueue.clear();
-        });
-        it('should touch a task to extend token', async () => {
-            const task = await queue.enqueue('foo', { foo: 'work' });
-            const dequeued = await queue.dequeue();
-            const initialLock = dequeued.visibilityDeadline;
-            await timeout(20);
-            const touched = await queue.touch(dequeued);
-            expect(touched.visibilityDeadline > initialLock).toBe(true);
-        });
-        it('should prevent touching if token is lost (stolen by another worker)', async () => {
-            await queue.enqueue('foo', { foo: 'work' });
-            const dequeued = await queue.dequeue();
-            expect(dequeued).toBeDefined();
-            // processTimeout is 50ms. Wait for it to expire.
-            await timeout(100);
-            await queue.maintenance();
-            await queue.dequeue(); // Stolen by another worker (tries=2)
-            // Original worker tries to touch
-            const touchResult = await queue.touch(dequeued);
-            expect(touchResult).toBeUndefined();
-        });
-        it('should correctly identify and transition zombie tasks to Orphaned after max retries', async () => {
-            const q = injector.resolve(TaskQueueProvider).get(`q-${crypto.randomUUID()}`, { maxTries: 1 });
-            const task = await q.enqueue('test', { value: 'zombie' });
-            // Dequeue to start it
-            await q.dequeue();
-            // Manually make it a zombie
-            await database
-                .update(taskTable)
-                .set({ visibilityDeadline: currentTimestamp() - 1000 })
-                .where(eq(taskTable.id, task.id));
-            await q.maintenance();
-            const updated = await q.getTask(task.id);
-            expect(updated?.status).toBe(TaskStatus.Orphaned);
-            await q.clear();
-        });
-        it('should age priority correctly', async () => {
-            const q = injector.resolve(TaskQueueProvider).get(`q-${crypto.randomUUID()}`, {
-                priorityAgingInterval: 0,
-                priorityAgingStep: 10,
-            });
-            const task = await q.enqueue('test', { value: 'aging' }, { priority: 100 });
-            // Manually backdate priorityAgeTimestamp
-            await database
-                .update(taskTable)
-                .set({ priorityAgeTimestamp: currentTimestamp() - 1000 })
-                .where(eq(taskTable.id, task.id));
-            await q.maintenance();
-            const updated = await q.getTask(task.id);
-            expect(updated?.priority).toBe(90);
-            await q.clear();
-        });
-        it('clear() should NOT throw foreign key violations', async () => {
-            const queueProvider = injector.resolve(TaskQueueProvider);
-            const otherQueue = queueProvider.get('other-namespace', {});
-            const parent = await queue.enqueue('parent', {});
-            await otherQueue.enqueue('child', {}, { parentId: parent.id });
-            // Clearing the queue containing the parent should NOT throw even if other-namespace has a child pointing to it.
-            await otherQueue.clear();
-            await expect(queue.clear()).resolves.toBeUndefined();
-        });
-    });
-    describe('Batch Operations', () => {
-        it('should complete many tasks efficiently', async () => {
-            const tasks = await queue.enqueueMany([
-                { type: 'foo', data: { foo: '1' } },
-                { type: 'foo', data: { foo: '2' } },
-            ], { returnTasks: true });
-            const d1 = await queue.dequeue();
-            const d2 = await queue.dequeue();
-            await queue.completeMany([d1, d2]);
-            const t1 = await queue.getTask(tasks[0].id);
-            const t2 = await queue.getTask(tasks[1].id);
-            expect(t1?.status).toBe(TaskStatus.Completed);
-            expect(t2?.status).toBe(TaskStatus.Completed);
-        });
-        it('should successfully completeMany tasks that have a NULL token', async () => {
-            const q = injector.resolve(TaskQueueProvider).get(`q-${crypto.randomUUID()}`);
-            const t1 = await q.enqueue('test', { value: '1' });
-            const t2 = await q.enqueue('test', { value: '2' });
-            expect(t1.token).toBeNull();
-            expect(t2.token).toBeNull();
-            await q.completeMany([t1, t2]);
-            const ut1 = await q.getTask(t1.id);
-            const ut2 = await q.getTask(t2.id);
-            expect(ut1?.status).toBe(TaskStatus.Completed);
-            expect(ut2?.status).toBe(TaskStatus.Completed);
-            await q.clear();
-        });
-        it('should successfully failMany tasks that have a NULL token', async () => {
-            const q = injector.resolve(TaskQueueProvider).get(`q-${crypto.randomUUID()}`, { maxTries: 0 });
-            const t1 = await q.enqueue('test', { value: '1' });
-            await q.failMany([t1], [new Error('fail')]);
-            const ut1 = await q.getTask(t1.id);
-            expect(ut1?.status).toBe(TaskStatus.Dead);
-            await q.clear();
-        });
-        it('should successfully touchMany tasks with missing or NULL states', async () => {
-            const q = injector.resolve(TaskQueueProvider).get(`q-${crypto.randomUUID()}`);
-            const t1 = await q.enqueue('test', { value: '1' });
-            const t2 = await q.enqueue('test', { value: '2' });
-            const d1 = await q.dequeue();
-            const d2 = await q.dequeue();
-            await q.touchMany([d1, d2], {
-                progresses: [0.5, 0.8],
-                states: [{ step: 'halfway' }, undefined],
-            });
-            const ut1 = await q.getTask(t1.id);
-            const ut2 = await q.getTask(t2.id);
-            expect(ut1?.progress).toBe(0.5);
-            expect(ut1?.state).toEqual({ step: 'halfway' });
-            expect(ut2?.progress).toBe(0.8);
-            expect(ut2?.state).toBeNull();
-            await q.clear();
-        });
-        it('should reject bulk updates (completeMany/failMany) if the provided token does not match the database', async () => {
-            const q = injector.resolve(TaskQueueProvider).get(`q-${crypto.randomUUID()}`);
-            const t1 = await q.enqueue('test', { value: '1' });
-            // Task is Pending, token is NULL.
-            // Try to complete with a fake token.
-            await q.completeMany([{ ...t1, token: crypto.randomUUID() }]);
-            const ut1 = await q.getTask(t1.id);
-            expect(ut1?.status).toBe(TaskStatus.Pending); // Should still be Pending
-            // Dequeue to get a real token
-            const d1 = await q.dequeue();
-            expect(d1?.token).toBeDefined();
-            // Try to complete with NULL token
-            await q.completeMany([{ ...d1, token: null }]);
-            const ut2 = await q.getTask(t1.id);
-            expect(ut2?.status).toBe(TaskStatus.Running); // Should still be Running
-            await q.clear();
-        });
-    });
-    describe('Rescheduling', () => {
-        it('should reschedule and refund tries if running', async () => {
-            const task = await queue.enqueue('foo', { foo: 'reschedule-me' });
-            const dequeued = await queue.dequeue();
-            expect(dequeued?.tries).toBe(1);
-            const inFuture = currentTimestamp() + 1000;
-            await queue.reschedule(dequeued.id, inFuture);
-            const updated = await queue.getTask(task.id);
-            expect(updated?.status).toBe(TaskStatus.Pending);
-            expect(updated?.tries).toBe(0); // Refunded
-            expect(updated?.scheduleTimestamp).toBe(inFuture);
-        });
-        it('rescheduling should NOT bypass dependency constraints (Bug 7)', async () => {
-            const dep = await queue.enqueue('dep', {});
-            const main = await queue.enqueue('main', {}, { scheduleAfter: [dep.id] });
-            expect(main.status).toBe(TaskStatus.Waiting);
-            expect(main.unresolvedScheduleDependencies).toBe(1);
-            await queue.reschedule(main.id, currentTimestamp());
-            const updatedMain = await queue.getTask(main.id);
-            expect(updatedMain?.status).toBe(TaskStatus.Waiting);
-        });
-    });
-    describe('TaskContext (Worker DX)', () => {
-        it('checkpoint() should update progress and handle token loss', async () => {
-            const task = await queue.enqueue('foo', { foo: 'progress' });
-            const dequeued = await queue.dequeue();
-            // In real scenarios TaskContext wraps the queue logic.
-            // Here we just verify touch/checkpoint effects on the DB.
-            await queue.touch(dequeued, { progress: 0.5, state: { step: 1 } });
-            const updated = await queue.getTask(task.id);
-            expect(updated?.progress).toBe(0.5);
-            expect(updated?.state).toEqual({ step: 1 });
-        });
-    });
-    describe('waitForTasks', () => {
-        it('should wait for multiple tasks to reach finalized state', async () => {
-            const t1 = await queue.enqueue('foo', { foo: 'wait-1' });
-            const t2 = await queue.enqueue('foo', { foo: 'wait-2' });
-            void (async () => {
-                await timeout(100);
-                const d1 = await queue.dequeue();
-                await queue.complete(d1);
-                await timeout(100);
-                const d2 = await queue.dequeue();
-                await queue.complete(d2);
-            })();
-            const result = await queue.waitForTasks([t1.id, t2.id], { timeout: 2000 });
-            expect(result.cancelled).toBe(false);
-            const check1 = await queue.getTask(t1.id);
-            const check2 = await queue.getTask(t2.id);
-            expect(check1?.status).toBe(TaskStatus.Completed);
-            expect(check2?.status).toBe(TaskStatus.Completed);
-        });
-        it('should throw TimeoutError on timeout', async () => {
-            const t1 = await queue.enqueue('foo', { foo: 'timeout' });
-            await expect(queue.waitForTasks([t1.id], { timeout: 100 })).rejects.toThrow('Timeout while waiting for tasks to complete');
-        });
-        it('should wait for Cancelled and Dead states', async () => {
-            const t1 = await queue.enqueue('foo', { foo: 'cancel' });
-            const t2 = await queue.enqueue('foo', { foo: 'dead' });
-            void (async () => {
-                await timeout(50);
-                const d1 = await queue.dequeue();
-                if (d1)
-                    await queue.cancel(d1.id);
-                const d2 = await queue.dequeue();
-                if (d2)
-                    await queue.fail(d2, new Error('fatal'), { fatal: true });
-                queue.notify();
-            })();
-            const result = await queue.waitForTasks([t1.id, t2.id], { timeout: 2000 });
-            expect(result.cancelled).toBe(false);
-            const c1 = await queue.getTask(t1.id);
-            const c2 = await queue.getTask(t2.id);
-            expect(c1?.status).toBe(TaskStatus.Cancelled);
-            expect(c2?.status).toBe(TaskStatus.Dead);
-        });
-        it('should handle cancellationSignal', async () => {
-            const t1 = await queue.enqueue('foo', { foo: 'long' });
-            const signal = new CancellationToken();
-            void timeout(100).then(() => signal.set());
-            const result = await queue.waitForTasks([t1.id], { cancellationSignal: signal, timeout: 5000 });
-            expect(result.cancelled).toBe(true);
-        });
-        it('should return immediately for non-existent tasks', async () => {
-            const result = await queue.waitForTasks([crypto.randomUUID()], { timeout: 1000 });
-            expect(result.cancelled).toBe(false);
-        });
-        it('should return immediately if all tasks are already finalized', async () => {
-            const t1 = await queue.enqueue('foo', { foo: 'immediate' });
-            const d1 = await queue.dequeue();
-            await queue.complete(d1);
-            const timer = Timer.startNew();
-            const result = await queue.waitForTasks([t1.id], { timeout: 1000 });
-            expect(result.cancelled).toBe(false);
-            expect(timer.milliseconds).toBeLessThan(100);
-        });
-        it('should handle a mix of active and archived tasks', async () => {
-            const queueProvider = injector.resolve(TaskQueueProvider);
-            const archiveQueue = queueProvider.get(`archive-test-${crypto.randomUUID()}`, {
-                retention: 0, // Archive immediately
-            });
-            const t1 = await archiveQueue.enqueue('foo', { foo: 'archived' });
-            const d1 = await archiveQueue.dequeue();
-            await archiveQueue.complete(d1);
-            // Run maintenance to move to archive
-            await archiveQueue.maintenance();
-            const t2 = await archiveQueue.enqueue('foo', { foo: 'active' });
-            const d2 = await archiveQueue.dequeue();
-            await archiveQueue.complete(d2);
-            // t1 is archived, t2 is completed (active)
-            const result = await archiveQueue.waitForTasks([t1.id, t2.id], { timeout: 1000 });
-            expect(result.cancelled).toBe(false);
-            await archiveQueue.clear();
-        });
-        it('should return immediately for empty ids array', async () => {
-            const result = await queue.waitForTasks([], { timeout: 1000 });
-            expect(result.cancelled).toBe(false);
-        });
-        it('should wait for parent task to reach finalized state after child completion', async () => {
-            const parent = await queue.enqueue('parent', { value: 'parent' });
-            const dParent = await queue.dequeue({ types: ['parent'] });
-            expect(dParent).toBeDefined();
-            // Spawn a child
-            const [child] = await queue.enqueueMany([{ type: 'child', data: { value: 'child' }, parentId: parent.id, completeAfter: [] }], { returnTasks: true });
-            expect(child).toBeDefined();
-            // Re-enqueuing with dependency:
-            const parentWithDep = await queue.enqueue('parent-dep', { value: 'parent' }, { completeAfter: [child.id] });
-            let dParent2;
-            for (let i = 0; i < 10; i++) {
-                dParent2 = await queue.dequeue({ types: ['parent-dep'] });
-                if (dParent2)
-                    break;
-                await timeout(50);
-            }
-            expect(dParent2?.id).toBe(parentWithDep.id);
-            // Complete parent (it will move to Waiting because of completeAfter)
-            await queue.complete(dParent2);
-            const checkParent = await queue.getTask(parentWithDep.id);
-            expect(checkParent?.status).toBe(TaskStatus.WaitingChildren);
-            void (async () => {
-                await timeout(100);
-                const dChild = await queue.dequeue({ types: ['child'] });
-                await queue.complete(dChild);
-            })();
-            await queue.waitForTasks([parentWithDep.id], { timeout: 2000 });
-            const finalParent = await queue.getTask(parentWithDep.id);
-            expect(finalParent?.status).toBe(TaskStatus.Completed);
-        });
-    });
-    describe('Bugs and Edge Cases', () => {
-        it('should NOT overwrite terminal states during cancellation (Bug 3)', async () => {
-            const q = injector.resolve(TaskQueueProvider).get(`q-${crypto.randomUUID()}`);
-            // 1. Enqueue parent and two children
-            const parent = await q.enqueue('parent', {});
-            const child1 = await q.enqueue('child', {}, { parentId: parent.id });
-            const child2 = await q.enqueue('child', {}, { parentId: parent.id });
-            // 2. Complete child1
-            const dequeued1 = await q.dequeue({ types: ['child'] });
-            await q.complete(dequeued1);
-            const finished1 = await q.getTask(child1.id);
-            expect(finished1?.status).toBe(TaskStatus.Completed);
-            // 3. Cancel parent tree
-            await q.cancel(parent.id);
-            // 4. Verify child1 is STILL Completed, not Cancelled
-            const updated1 = await q.getTask(child1.id);
-            expect(updated1?.status).toBe(TaskStatus.Completed);
-            // 5. Verify parent and child2 ARE Cancelled
-            const updatedParent = await q.getTask(parent.id);
-            const updated2 = await q.getTask(child2.id);
-            expect(updatedParent?.status).toBe(TaskStatus.Cancelled);
-            expect(updated2?.status).toBe(TaskStatus.Cancelled);
-            await q.clear();
-        });
-        it('should expire tasks in Waiting status (Bug 5)', async () => {
-            const q = injector.resolve(TaskQueueProvider).get(`q-${crypto.randomUUID()}`);
-            // 1. Enqueue task A (will never complete)
-            const taskA = await q.enqueue('test', {});
-            // 2. Enqueue task B with scheduleAfter: [A.id] and short TTL
-            const taskB = await q.enqueue('test', {}, {
-                scheduleAfter: [taskA.id],
-                timeToLive: 100, // 100ms
-            });
-            expect(taskB.status).toBe(TaskStatus.Waiting);
-            // 3. Wait for TTL to pass
-            await timeout(200);
-            // 4. Run maintenance
-            await q.maintenance();
-            // 5. Verify task B is Expired
-            await q.waitForTasks([taskB.id]);
-            const updatedB = await q.getTask(taskB.id);
-            expect(updatedB?.status).toBe(TaskStatus.Expired);
-            await q.clear();
-        });
-    });
-});