@tstdl/base 0.93.140 → 0.93.142

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

@@ -1,14 +1,17 @@
+import { eq, or } from 'drizzle-orm';
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
 import { CancellationToken } from '../../cancellation/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;
-    const queueName = `test-queue-${Date.now()}`;
     // Helper to verify state in DB
     async function assertTaskStatus(id, state, message) {
         const task = await queue.getTask(id);
@@ -16,10 +19,10 @@ describe('Queue Integration Tests', () => {
     }
     beforeAll(async () => {
         ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
-        // Use the QueueProvider to Create/Retrieve the queue.
-        // This is the cleanest way to get a configured queue instance without
-        // messing with `injectArgument` manually in the test body.
+    });
+    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
@@ -32,7 +35,9 @@ describe('Queue Integration Tests', () => {
     });
     afterAll(async () => {
         try {
-            await queue.clear();
+            if (isDefined(queue)) {
+                await queue.clear();
+            }
             await injector.dispose();
         }
         catch (error) {
@@ -68,7 +73,7 @@ describe('Queue Integration Tests', () => {
         await queue.complete(second);
     });
     it('Deduplication (Idempotency Keys)', async () => {
-        const key = `unique-${Date.now()}`;
+        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
@@ -76,9 +81,9 @@ describe('Queue Integration Tests', () => {
         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 AND new ID
+        // 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, 'New ID if replaced').not.toBe(t1.id);
+        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');
@@ -90,6 +95,8 @@ describe('Queue Integration Tests', () => {
         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
@@ -129,12 +136,14 @@ describe('Queue Integration Tests', () => {
 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-${Date.now()}-${Math.random()}`;
+        const queueName = `pg-test-queue-${crypto.randomUUID()}`;
         queue = queueProvider.get(queueName, {
             visibilityTimeout: 50, // Short timeout for testing
             retryDelayMinimum: 50,
@@ -172,11 +181,96 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
             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.Pending);
+            expect(updated?.status).toBe(TaskStatus.Retrying);
             expect(updated?.tries).toBe(1);
             expect(updated?.error).toBeDefined();
         });
     });
+    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, waitForCompletion: 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,
+                waitForCompletion: 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 waitForCompletion: true (Bug 6-2)', async () => {
+            const parent = await queue.enqueue('parent', {});
+            expect(parent.unresolvedCompleteDependencies).toBe(0);
+            await queue.enqueue('child', {}, { parentId: parent.id, waitForCompletion: 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 });
@@ -200,24 +294,18 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
         });
     });
     describe('Concurrency Control', () => {
-        it('should respect global concurrency limits', async () => {
-            const queueProvider = injector.resolve(TaskQueueProvider);
-            const limitedQueue = queueProvider.get(`limit-test-${Date.now()}`, { globalConcurrency: 2 });
-            await limitedQueue.enqueueMany([
-                { type: 'foo', data: { foo: '1' } },
-                { type: 'foo', data: { foo: '2' } },
-                { type: 'foo', data: { foo: '3' } },
-            ]);
-            const t1 = await limitedQueue.dequeue();
-            const t2 = await limitedQueue.dequeue();
-            const t3 = await limitedQueue.dequeue();
-            expect(t1).toBeDefined();
-            expect(t2).toBeDefined();
-            expect(t3).toBeUndefined(); // Limit reached
-            await limitedQueue.complete(t1);
-            const t3Retry = await limitedQueue.dequeue();
-            expect(t3Retry).toBeDefined(); // Slot opened
-            await limitedQueue.clear();
+        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', () => {
@@ -255,21 +343,21 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
             await timeout(100);
             await queue.maintenance();
             const recovered = await queue.getTask(task.id);
-            expect(recovered?.status).toBe(TaskStatus.Pending);
+            expect(recovered?.status).toBe(TaskStatus.Retrying);
             expect(recovered?.tries).toBe(1);
             expect(recovered?.token).toBeNull();
         });
         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-${Date.now()}`, { maxExecutionTime: 50 });
+            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.Dead);
-            expect(updated?.error?.message).toContain('Hard Execution Timeout');
+            expect(updated?.status).toBe(TaskStatus.TimedOut);
+            expect(updated?.error?.code).toBe('MaxTimeExceeded');
             await shortQueue.clear();
         });
         it('should touch a task to extend token', async () => {
@@ -278,7 +366,7 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
             const initialLock = dequeued.visibilityDeadline;
             await timeout(20);
             const touched = await queue.touch(dequeued);
-            expect(touched?.visibilityDeadline > initialLock).toBe(true);
+            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' });
@@ -292,6 +380,46 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
             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 () => {
@@ -307,6 +435,62 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
             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 () => {
@@ -320,6 +504,15 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
             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 () => {
@@ -419,27 +612,79 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
             expect(result.cancelled).toBe(false);
         });
         it('should wait for parent task to reach finalized state after child completion', async () => {
-            const childTag = `child-of-${crypto.randomUUID()}`;
-            const parent = await queue.enqueue('test', { value: 'parent' }, { completeAfterTags: [childTag] });
-            const dParent = await queue.dequeue();
+            const parent = await queue.enqueue('parent', { value: 'parent' });
+            const dParent = await queue.dequeue({ types: ['parent'] });
+            expect(dParent).toBeDefined();
             // Spawn a child
-            await queue.enqueueMany([{ type: 'test', data: { value: 'child' }, parentId: parent.id, tags: [childTag] }], { transaction: undefined });
-            // Complete parent (it will move to Waiting because of completeAfterTags)
-            await queue.complete(dParent);
-            const checkParent = await queue.getTask(parent.id);
-            expect(checkParent?.status).toBe(TaskStatus.Waiting);
+            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();
-                if (dChild) {
-                    await queue.complete(dChild);
-                }
-                // Manual fan-in processing since we are in a test environment and might want immediate result
-                await queue.processPendingFanIn();
+                const dChild = await queue.dequeue({ types: ['child'] });
+                await queue.complete(dChild);
             })();
-            await queue.waitForTasks([parent.id], { timeout: 2000 });
-            const finalParent = await queue.getTask(parent.id);
+            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();
+        });
+    });
 });

package/task-queue/tests/shutdown.test.d.ts

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

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

@@ -0,0 +1,41 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { CancellationSignal } from '../../cancellation/token.js';
+import { DeferredPromise } from '../../promise/deferred-promise.js';
+import { TaskProcessResult, TaskQueueProvider } from '../../task-queue/index.js';
+import { setupIntegrationTest } from '../../testing/index.js';
+import { timeout } from '../../utils/timing.js';
+describe('Graceful Worker Shutdown', () => {
+    let injector;
+    let queue;
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
+        const queueProvider = injector.resolve(TaskQueueProvider);
+        queue = queueProvider.get(`shutdown-queue-${crypto.randomUUID()}`);
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    it('should wait for active handler to finish on disposal', async () => {
+        const cancellationSignal = injector.resolve(CancellationSignal);
+        await queue.enqueue('shutdown-test', {});
+        let handlerFinished = false;
+        const handlerStarted = new DeferredPromise();
+        queue.process({ cancellationSignal }, async () => {
+            handlerStarted.resolve();
+            await timeout(300); // simulate work
+            handlerFinished = true;
+            return TaskProcessResult.Complete();
+        });
+        queue.notify();
+        // Wait for worker to pick it up
+        await handlerStarted;
+        // Call disposal
+        const disposePromise = injector.dispose();
+        // Check that disposal waits for the handler
+        expect(handlerFinished).toBe(false);
+        await disposePromise;
+        expect(handlerFinished).toBe(true);
+        // Note: We can't call queue.getTask here because pool is closed.
+        // But handlerFinished = true and successful disposePromise already prove it waited.
+    });
+});

package/task-queue/tests/transactions.test.d.ts

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

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

@@ -0,0 +1,47 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { TaskQueueProvider, TaskStatus } from '../../task-queue/index.js';
+import { setupIntegrationTest } from '../../testing/index.js';
+describe('Task Queue Transactions', () => {
+    let injector;
+    let queue;
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
+        const queueProvider = injector.resolve(TaskQueueProvider);
+        queue = queueProvider.get(`tx-queue-${crypto.randomUUID()}`);
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    it('should respect transaction rollbacks', async () => {
+        let taskId;
+        await queue.transaction(async (tx) => {
+            const task = await queue.enqueue('tx-task', { foo: 'bar' }, { transaction: tx });
+            taskId = task.id;
+            const hasTask = await queue.has(taskId, { transaction: tx });
+            expect(hasTask).toBe(true);
+            await tx.rollback();
+        });
+        const hasTaskAfterRollback = await queue.has(taskId);
+        expect(hasTaskAfterRollback).toBe(false);
+    });
+    it('should participate in external transaction (commit)', async () => {
+        let taskId;
+        await queue.transaction(async (tx) => {
+            const task = await queue.enqueue('tx-commit', { foo: 'bar' }, { transaction: tx });
+            taskId = task.id;
+        });
+        const hasTaskAfterCommit = await queue.has(taskId);
+        expect(hasTaskAfterCommit).toBe(true);
+    });
+    it('should handle multiple operations in one transaction', async () => {
+        await queue.transaction(async (tx) => {
+            const t1 = await queue.enqueue('t1', {}, { transaction: tx });
+            const t2 = await queue.enqueue('t2', {}, { transaction: tx });
+            await queue.cancel(t1.id, { transaction: tx });
+            const u1 = await queue.getTask(t1.id, { transaction: tx });
+            expect(u1?.status).toBe(TaskStatus.Cancelled);
+            const u2 = await queue.getTask(t2.id, { transaction: tx });
+            expect(u2?.status).toBe(TaskStatus.Pending);
+        });
+    });
+});