docs: consolidate documentation into organized structure

- Move 12 markdown files from root to docs/ subdirectories
- Organize documentation by category:
  • docs/troubleshooting/ (1 file)  - Technical troubleshooting guides
  • docs/deployment/      (4 files) - Deployment and security documentation
  • docs/guides/          (3 files) - Feature-specific guides
  • docs/planning/        (4 files) - Planning and improvement proposals

Root directory cleanup:
- Reduced from 16 to 4 markdown files in root
- Only essential project files remain:
  • CLAUDE.md (AI instructions)
  • README.md (Main project readme)
  • CLEANUP_PLAN.md (Current cleanup plan)
  • SRC_STRUCTURE_IMPROVEMENTS.md (Structure improvements)

This improves:
✅ Documentation discoverability
✅ Logical organization by purpose
✅ Clean root directory
✅ Better maintainability

tests/Framework/Queue/BasicQueueTest.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+test('basic queue system initialization', function () {
+    $container = createTestContainer();
+
+    expect($container)->not()->toBeNull();
+
+    // Test that basic queue services can be resolved
+    try {
+        $queue = $container->get(\App\Framework\Queue\Contracts\QueueInterface::class);
+        expect($queue)->not()->toBeNull();
+
+        $dependencyManager = $container->get(\App\Framework\Queue\Contracts\JobDependencyManagerInterface::class);
+        expect($dependencyManager)->not()->toBeNull();
+
+        $chainManager = $container->get(\App\Framework\Queue\Contracts\JobChainManagerInterface::class);
+        expect($chainManager)->not()->toBeNull();
+
+        $metricsManager = $container->get(\App\Framework\Queue\Services\JobMetricsManager::class);
+        expect($metricsManager)->not()->toBeNull();
+
+        echo "✅ All queue system services resolved successfully\n";
+    } catch (\Throwable $e) {
+        echo "❌ Error resolving queue services: " . $e->getMessage() . "\n";
+        throw $e;
+    }
+});

tests/Framework/Queue/DeadLetterQueueTest.php

@@ -0,0 +1,617 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\ValueObjects\DeadLetterQueueName;
+use App\Framework\Queue\ValueObjects\QueueName;
+use App\Framework\Queue\ValueObjects\JobId;
+use App\Framework\Queue\ValueObjects\JobPayload;
+use App\Framework\Queue\ValueObjects\QueuePriority;
+use App\Framework\Queue\ValueObjects\FailureReason;
+use App\Framework\Queue\Exceptions\InvalidDeadLetterQueueNameException;
+
+describe('DeadLetterQueueName Value Object', function () {
+
+    describe('Construction and Validation', function () {
+        it('can create valid dead letter queue names', function () {
+            $validNames = [
+                'failed',
+                'email_failed',
+                'background-jobs-failed',
+                'user.registration.failed',
+                'queue_123_failed',
+                'a', // minimum length
+                str_repeat('a', 100) // maximum length
+            ];
+
+            foreach ($validNames as $name) {
+                $dlqName = DeadLetterQueueName::fromString($name);
+                expect($dlqName->toString())->toBe($name);
+            }
+        });
+
+        it('rejects invalid dead letter queue names', function () {
+            $invalidNames = [
+                '', // too short
+                str_repeat('a', 101), // too long
+                'queue with spaces',
+                'queue@invalid',
+                'queue#invalid',
+                'queue$invalid',
+                'queue%invalid',
+                'queue&invalid',
+                'queue*invalid',
+                'queue(invalid)',
+                'queue+invalid',
+                'queue=invalid',
+                'queue[invalid]',
+                'queue{invalid}',
+                'queue|invalid',
+                'queue\\invalid',
+                'queue:invalid',
+                'queue;invalid',
+                'queue"invalid',
+                'queue\'invalid',
+                'queue<invalid>',
+                'queue,invalid',
+                'queue?invalid',
+                'queue/invalid',
+                'queue~invalid',
+                'queue`invalid'
+            ];
+
+            foreach ($invalidNames as $name) {
+                expect(fn() => DeadLetterQueueName::fromString($name))
+                    ->toThrow(InvalidDeadLetterQueueNameException::class);
+            }
+        });
+
+        it('is readonly and immutable', function () {
+            $dlqName = DeadLetterQueueName::fromString('test-failed');
+
+            $reflection = new ReflectionClass($dlqName);
+            expect($reflection->isReadOnly())->toBeTrue();
+
+            $nameProperty = $reflection->getProperty('name');
+            expect($nameProperty->isReadOnly())->toBeTrue();
+        });
+    });
+
+    describe('Factory Methods', function () {
+        it('creates default dead letter queue name', function () {
+            $defaultDlq = DeadLetterQueueName::default();
+            expect($defaultDlq->toString())->toBe('failed');
+        });
+
+        it('creates dead letter queue for specific queue', function () {
+            $queueName = QueueName::fromString('email');
+            $dlqName = DeadLetterQueueName::forQueue($queueName);
+
+            expect($dlqName->toString())->toBe('email_failed');
+        });
+
+        it('creates dead letter queue for complex queue names', function () {
+            $queueName = QueueName::fromString('user.registration');
+            $dlqName = DeadLetterQueueName::forQueue($queueName);
+
+            expect($dlqName->toString())->toBe('user.registration_failed');
+        });
+    });
+
+    describe('Equality and Comparison', function () {
+        it('equals() compares names correctly', function () {
+            $dlq1 = DeadLetterQueueName::fromString('failed');
+            $dlq2 = DeadLetterQueueName::fromString('failed');
+            $dlq3 = DeadLetterQueueName::fromString('other_failed');
+
+            expect($dlq1->equals($dlq2))->toBeTrue();
+            expect($dlq1->equals($dlq3))->toBeFalse();
+            expect($dlq2->equals($dlq3))->toBeFalse();
+        });
+
+        it('string representation works correctly', function () {
+            $name = 'test-failed-queue';
+            $dlqName = DeadLetterQueueName::fromString($name);
+
+            expect($dlqName->toString())->toBe($name);
+            expect((string) $dlqName)->toBe($name);
+        });
+    });
+
+    describe('Edge Cases', function () {
+        it('handles minimum and maximum length names', function () {
+            $minName = DeadLetterQueueName::fromString('a');
+            expect($minName->toString())->toBe('a');
+
+            $maxName = DeadLetterQueueName::fromString(str_repeat('x', 100));
+            expect($maxName->toString())->toBe(str_repeat('x', 100));
+        });
+
+        it('handles all valid characters', function () {
+            $validChars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-.';
+            $dlqName = DeadLetterQueueName::fromString($validChars);
+
+            expect($dlqName->toString())->toBe($validChars);
+        });
+
+        it('provides specific error messages for validation failures', function () {
+            // Too short
+            try {
+                DeadLetterQueueName::fromString('');
+                expect(false)->toBeTrue('Should have thrown exception');
+            } catch (InvalidDeadLetterQueueNameException $e) {
+                expect($e->getMessage())->toContain('too short');
+            }
+
+            // Too long
+            try {
+                DeadLetterQueueName::fromString(str_repeat('a', 101));
+                expect(false)->toBeTrue('Should have thrown exception');
+            } catch (InvalidDeadLetterQueueNameException $e) {
+                expect($e->getMessage())->toContain('too long');
+            }
+
+            // Invalid format
+            try {
+                DeadLetterQueueName::fromString('invalid@name');
+                expect(false)->toBeTrue('Should have thrown exception');
+            } catch (InvalidDeadLetterQueueNameException $e) {
+                expect($e->getMessage())->toContain('invalid format');
+            }
+        });
+    });
+});
+
+describe('Dead Letter Queue Mock Implementation', function () {
+
+    beforeEach(function () {
+        // Create a mock dead letter queue for testing
+        $this->mockDlq = new class {
+            private array $jobs = [];
+            private array $stats = [];
+
+            public function addFailedJob(array $jobData): void {
+                $this->jobs[] = $jobData;
+            }
+
+            public function getJobs(DeadLetterQueueName $queueName, int $limit = 100): array {
+                return array_slice(
+                    array_filter($this->jobs, fn($job) => $job['dlq_name'] === $queueName->toString()),
+                    0,
+                    $limit
+                );
+            }
+
+            public function retryJob(string $jobId): bool {
+                foreach ($this->jobs as $index => $job) {
+                    if ($job['id'] === $jobId) {
+                        unset($this->jobs[$index]);
+                        return true;
+                    }
+                }
+                return false;
+            }
+
+            public function deleteJob(string $jobId): bool {
+                foreach ($this->jobs as $index => $job) {
+                    if ($job['id'] === $jobId) {
+                        unset($this->jobs[$index]);
+                        return true;
+                    }
+                }
+                return false;
+            }
+
+            public function clearQueue(DeadLetterQueueName $queueName): int {
+                $initialCount = count($this->jobs);
+                $this->jobs = array_filter(
+                    $this->jobs,
+                    fn($job) => $job['dlq_name'] !== $queueName->toString()
+                );
+                return $initialCount - count($this->jobs);
+            }
+
+            public function getQueueStats(DeadLetterQueueName $queueName): array {
+                $jobs = $this->getJobs($queueName);
+                return [
+                    'queue_name' => $queueName->toString(),
+                    'total_jobs' => count($jobs),
+                    'avg_failed_attempts' => count($jobs) > 0 ? array_sum(array_column($jobs, 'failed_attempts')) / count($jobs) : 0,
+                    'max_failed_attempts' => count($jobs) > 0 ? max(array_column($jobs, 'failed_attempts')) : 0,
+                    'avg_retry_count' => count($jobs) > 0 ? array_sum(array_column($jobs, 'retry_count')) / count($jobs) : 0,
+                    'max_retry_count' => count($jobs) > 0 ? max(array_column($jobs, 'retry_count')) : 0,
+                    'oldest_job' => count($jobs) > 0 ? min(array_column($jobs, 'failed_at')) : null,
+                    'newest_job' => count($jobs) > 0 ? max(array_column($jobs, 'failed_at')) : null
+                ];
+            }
+
+            public function getAvailableQueues(): array {
+                $queueNames = array_unique(array_column($this->jobs, 'dlq_name'));
+                return array_map(fn($name) => DeadLetterQueueName::fromString($name), $queueNames);
+            }
+        };
+    });
+
+    describe('Dead Letter Queue Operations', function () {
+        it('can add failed jobs', function () {
+            $dlqName = DeadLetterQueueName::fromString('email_failed');
+            $jobId = JobId::generate();
+
+            $jobData = [
+                'id' => uniqid(),
+                'original_job_id' => $jobId->toString(),
+                'dlq_name' => $dlqName->toString(),
+                'original_queue' => 'email',
+                'job_payload' => serialize(['type' => 'email', 'data' => 'test']),
+                'failure_reason' => 'Connection timeout',
+                'exception_type' => 'TimeoutException',
+                'stack_trace' => 'Stack trace here...',
+                'failed_attempts' => 3,
+                'failed_at' => date('Y-m-d H:i:s'),
+                'retry_count' => 0
+            ];
+
+            $this->mockDlq->addFailedJob($jobData);
+
+            $jobs = $this->mockDlq->getJobs($dlqName);
+            expect(count($jobs))->toBe(1);
+            expect($jobs[0]['original_job_id'])->toBe($jobId->toString());
+        });
+
+        it('can retrieve jobs by queue name', function () {
+            $emailDlq = DeadLetterQueueName::fromString('email_failed');
+            $reportDlq = DeadLetterQueueName::fromString('report_failed');
+
+            // Add jobs to different queues
+            $this->mockDlq->addFailedJob([
+                'id' => 'job1',
+                'original_job_id' => 'original1',
+                'dlq_name' => $emailDlq->toString(),
+                'original_queue' => 'email',
+                'job_payload' => 'payload1',
+                'failure_reason' => 'Error 1',
+                'exception_type' => 'Exception',
+                'stack_trace' => 'trace1',
+                'failed_attempts' => 1,
+                'failed_at' => date('Y-m-d H:i:s'),
+                'retry_count' => 0
+            ]);
+
+            $this->mockDlq->addFailedJob([
+                'id' => 'job2',
+                'original_job_id' => 'original2',
+                'dlq_name' => $reportDlq->toString(),
+                'original_queue' => 'report',
+                'job_payload' => 'payload2',
+                'failure_reason' => 'Error 2',
+                'exception_type' => 'Exception',
+                'stack_trace' => 'trace2',
+                'failed_attempts' => 2,
+                'failed_at' => date('Y-m-d H:i:s'),
+                'retry_count' => 0
+            ]);
+
+            $emailJobs = $this->mockDlq->getJobs($emailDlq);
+            $reportJobs = $this->mockDlq->getJobs($reportDlq);
+
+            expect(count($emailJobs))->toBe(1);
+            expect(count($reportJobs))->toBe(1);
+            expect($emailJobs[0]['id'])->toBe('job1');
+            expect($reportJobs[0]['id'])->toBe('job2');
+        });
+
+        it('can retry failed jobs', function () {
+            $dlqName = DeadLetterQueueName::fromString('test_failed');
+            $jobId = 'retry_test_job';
+
+            $this->mockDlq->addFailedJob([
+                'id' => $jobId,
+                'original_job_id' => 'original_retry',
+                'dlq_name' => $dlqName->toString(),
+                'original_queue' => 'test',
+                'job_payload' => 'retry_payload',
+                'failure_reason' => 'Temporary error',
+                'exception_type' => 'TemporaryException',
+                'stack_trace' => 'retry_trace',
+                'failed_attempts' => 1,
+                'failed_at' => date('Y-m-d H:i:s'),
+                'retry_count' => 0
+            ]);
+
+            expect(count($this->mockDlq->getJobs($dlqName)))->toBe(1);
+
+            $retryResult = $this->mockDlq->retryJob($jobId);
+            expect($retryResult)->toBeTrue();
+
+            // Job should be removed from DLQ after retry
+            expect(count($this->mockDlq->getJobs($dlqName)))->toBe(0);
+        });
+
+        it('can delete failed jobs permanently', function () {
+            $dlqName = DeadLetterQueueName::fromString('delete_test');
+            $jobId = 'delete_test_job';
+
+            $this->mockDlq->addFailedJob([
+                'id' => $jobId,
+                'original_job_id' => 'original_delete',
+                'dlq_name' => $dlqName->toString(),
+                'original_queue' => 'delete_test',
+                'job_payload' => 'delete_payload',
+                'failure_reason' => 'Permanent error',
+                'exception_type' => 'PermanentException',
+                'stack_trace' => 'delete_trace',
+                'failed_attempts' => 5,
+                'failed_at' => date('Y-m-d H:i:s'),
+                'retry_count' => 0
+            ]);
+
+            expect(count($this->mockDlq->getJobs($dlqName)))->toBe(1);
+
+            $deleteResult = $this->mockDlq->deleteJob($jobId);
+            expect($deleteResult)->toBeTrue();
+
+            expect(count($this->mockDlq->getJobs($dlqName)))->toBe(0);
+        });
+
+        it('can clear entire queue', function () {
+            $dlqName = DeadLetterQueueName::fromString('clear_test');
+
+            // Add multiple jobs
+            for ($i = 1; $i <= 5; $i++) {
+                $this->mockDlq->addFailedJob([
+                    'id' => "clear_job_{$i}",
+                    'original_job_id' => "original_{$i}",
+                    'dlq_name' => $dlqName->toString(),
+                    'original_queue' => 'clear_test',
+                    'job_payload' => "payload_{$i}",
+                    'failure_reason' => "Error {$i}",
+                    'exception_type' => 'Exception',
+                    'stack_trace' => "trace_{$i}",
+                    'failed_attempts' => $i,
+                    'failed_at' => date('Y-m-d H:i:s'),
+                    'retry_count' => 0
+                ]);
+            }
+
+            expect(count($this->mockDlq->getJobs($dlqName)))->toBe(5);
+
+            $clearedCount = $this->mockDlq->clearQueue($dlqName);
+            expect($clearedCount)->toBe(5);
+            expect(count($this->mockDlq->getJobs($dlqName)))->toBe(0);
+        });
+    });
+
+    describe('Dead Letter Queue Statistics', function () {
+        it('provides accurate queue statistics', function () {
+            $dlqName = DeadLetterQueueName::fromString('stats_test');
+
+            // Add jobs with varying statistics
+            $jobs = [
+                ['failed_attempts' => 1, 'retry_count' => 0],
+                ['failed_attempts' => 3, 'retry_count' => 1],
+                ['failed_attempts' => 5, 'retry_count' => 2],
+                ['failed_attempts' => 2, 'retry_count' => 0],
+            ];
+
+            foreach ($jobs as $index => $jobStats) {
+                $this->mockDlq->addFailedJob([
+                    'id' => "stats_job_{$index}",
+                    'original_job_id' => "original_stats_{$index}",
+                    'dlq_name' => $dlqName->toString(),
+                    'original_queue' => 'stats_test',
+                    'job_payload' => "payload_{$index}",
+                    'failure_reason' => "Error {$index}",
+                    'exception_type' => 'Exception',
+                    'stack_trace' => "trace_{$index}",
+                    'failed_attempts' => $jobStats['failed_attempts'],
+                    'failed_at' => date('Y-m-d H:i:s', time() - $index * 3600), // Different times
+                    'retry_count' => $jobStats['retry_count']
+                ]);
+            }
+
+            $stats = $this->mockDlq->getQueueStats($dlqName);
+
+            expect($stats['queue_name'])->toBe($dlqName->toString());
+            expect($stats['total_jobs'])->toBe(4);
+            expect($stats['avg_failed_attempts'])->toBe(2.75); // (1+3+5+2)/4
+            expect($stats['max_failed_attempts'])->toBe(5);
+            expect($stats['avg_retry_count'])->toBe(0.75); // (0+1+2+0)/4
+            expect($stats['max_retry_count'])->toBe(2);
+            expect($stats['oldest_job'])->not->toBeNull();
+            expect($stats['newest_job'])->not->toBeNull();
+        });
+
+        it('handles empty queue statistics', function () {
+            $dlqName = DeadLetterQueueName::fromString('empty_stats');
+
+            $stats = $this->mockDlq->getQueueStats($dlqName);
+
+            expect($stats['total_jobs'])->toBe(0);
+            expect($stats['avg_failed_attempts'])->toBe(0);
+            expect($stats['max_failed_attempts'])->toBe(0);
+            expect($stats['avg_retry_count'])->toBe(0);
+            expect($stats['max_retry_count'])->toBe(0);
+            expect($stats['oldest_job'])->toBeNull();
+            expect($stats['newest_job'])->toBeNull();
+        });
+
+        it('can list available queues', function () {
+            $queues = [
+                DeadLetterQueueName::fromString('email_failed'),
+                DeadLetterQueueName::fromString('report_failed'),
+                DeadLetterQueueName::fromString('background_failed')
+            ];
+
+            foreach ($queues as $index => $queue) {
+                $this->mockDlq->addFailedJob([
+                    'id' => "queue_job_{$index}",
+                    'original_job_id' => "original_{$index}",
+                    'dlq_name' => $queue->toString(),
+                    'original_queue' => 'test',
+                    'job_payload' => "payload_{$index}",
+                    'failure_reason' => "Error {$index}",
+                    'exception_type' => 'Exception',
+                    'stack_trace' => "trace_{$index}",
+                    'failed_attempts' => 1,
+                    'failed_at' => date('Y-m-d H:i:s'),
+                    'retry_count' => 0
+                ]);
+            }
+
+            $availableQueues = $this->mockDlq->getAvailableQueues();
+
+            expect(count($availableQueues))->toBe(3);
+
+            $queueNames = array_map(fn($q) => $q->toString(), $availableQueues);
+            expect($queueNames)->toContain('email_failed');
+            expect($queueNames)->toContain('report_failed');
+            expect($queueNames)->toContain('background_failed');
+        });
+    });
+
+    describe('Dead Letter Queue Error Scenarios', function () {
+        it('handles retry of non-existent job', function () {
+            $result = $this->mockDlq->retryJob('non_existent_job');
+            expect($result)->toBeFalse();
+        });
+
+        it('handles delete of non-existent job', function () {
+            $result = $this->mockDlq->deleteJob('non_existent_job');
+            expect($result)->toBeFalse();
+        });
+
+        it('handles clear of non-existent queue', function () {
+            $nonExistentQueue = DeadLetterQueueName::fromString('non_existent');
+            $clearedCount = $this->mockDlq->clearQueue($nonExistentQueue);
+            expect($clearedCount)->toBe(0);
+        });
+
+        it('respects job limit when retrieving jobs', function () {
+            $dlqName = DeadLetterQueueName::fromString('limit_test');
+
+            // Add 10 jobs
+            for ($i = 1; $i <= 10; $i++) {
+                $this->mockDlq->addFailedJob([
+                    'id' => "limit_job_{$i}",
+                    'original_job_id' => "original_{$i}",
+                    'dlq_name' => $dlqName->toString(),
+                    'original_queue' => 'limit_test',
+                    'job_payload' => "payload_{$i}",
+                    'failure_reason' => "Error {$i}",
+                    'exception_type' => 'Exception',
+                    'stack_trace' => "trace_{$i}",
+                    'failed_attempts' => 1,
+                    'failed_at' => date('Y-m-d H:i:s'),
+                    'retry_count' => 0
+                ]);
+            }
+
+            $limitedJobs = $this->mockDlq->getJobs($dlqName, 5);
+            expect(count($limitedJobs))->toBe(5);
+
+            $allJobs = $this->mockDlq->getJobs($dlqName, 100);
+            expect(count($allJobs))->toBe(10);
+        });
+    });
+});
+
+describe('Dead Letter Queue Integration Scenarios', function () {
+
+    beforeEach(function () {
+        $this->testJob = new class {
+            public function __construct(
+                public string $email = 'test@example.com',
+                public string $subject = 'Test Email'
+            ) {}
+
+            public function handle(): bool {
+                // Simulate processing that might fail
+                if ($this->email === 'invalid@test.com') {
+                    throw new \Exception('Invalid email address');
+                }
+                return true;
+            }
+        };
+
+        $this->failureScenarios = [
+            'network_timeout' => [
+                'reason' => 'Network connection timeout',
+                'exception' => 'NetworkTimeoutException',
+                'retryable' => true
+            ],
+            'invalid_data' => [
+                'reason' => 'Invalid email format',
+                'exception' => 'ValidationException',
+                'retryable' => false
+            ],
+            'service_unavailable' => [
+                'reason' => 'External service unavailable',
+                'exception' => 'ServiceUnavailableException',
+                'retryable' => true
+            ],
+            'permission_denied' => [
+                'reason' => 'Insufficient permissions',
+                'exception' => 'PermissionException',
+                'retryable' => false
+            ]
+        ];
+    });
+
+    it('handles different types of job failures', function () {
+        $emailDlq = DeadLetterQueueName::fromString('email_failed');
+
+        foreach ($this->failureScenarios as $scenarioName => $scenario) {
+            $jobPayload = JobPayload::create($this->testJob);
+            $jobId = JobId::generate();
+
+            // Simulate job failure based on scenario
+            $expectedRetryable = $scenario['retryable'];
+
+            expect($scenario['reason'])->toBeString();
+            expect($scenario['exception'])->toBeString();
+            expect($expectedRetryable)->toBeBool();
+        }
+    });
+
+    it('demonstrates retry strategies for different failure types', function () {
+        $retryableFailures = array_filter(
+            $this->failureScenarios,
+            fn($scenario) => $scenario['retryable']
+        );
+
+        $nonRetryableFailures = array_filter(
+            $this->failureScenarios,
+            fn($scenario) => !$scenario['retryable']
+        );
+
+        expect(count($retryableFailures))->toBeGreaterThan(0);
+        expect(count($nonRetryableFailures))->toBeGreaterThan(0);
+
+        // Retryable failures should be candidates for retry
+        foreach ($retryableFailures as $scenario) {
+            expect($scenario['retryable'])->toBeTrue();
+        }
+
+        // Non-retryable failures should be handled differently
+        foreach ($nonRetryableFailures as $scenario) {
+            expect($scenario['retryable'])->toBeFalse();
+        }
+    });
+
+    it('demonstrates queue-specific dead letter handling', function () {
+        $queueTypes = [
+            'email' => DeadLetterQueueName::forQueue(QueueName::fromString('email')),
+            'reports' => DeadLetterQueueName::forQueue(QueueName::fromString('reports')),
+            'background' => DeadLetterQueueName::forQueue(QueueName::fromString('background'))
+        ];
+
+        foreach ($queueTypes as $originalQueue => $dlqName) {
+            expect($dlqName->toString())->toBe($originalQueue . '_failed');
+        }
+
+        // Each queue type should have its own DLQ
+        $queueNames = array_map(fn($dlq) => $dlq->toString(), $queueTypes);
+        $uniqueNames = array_unique($queueNames);
+        expect(count($uniqueNames))->toBe(count($queueTypes));
+    });
+});

tests/Framework/Queue/DistributedLockingTest.php

@@ -0,0 +1,813 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\ValueObjects\LockKey;
+use App\Framework\Queue\ValueObjects\WorkerId;
+use App\Framework\Queue\ValueObjects\JobId;
+use App\Framework\Queue\ValueObjects\QueueName;
+use App\Framework\Core\ValueObjects\Duration;
+
+describe('LockKey Value Object', function () {
+
+    describe('Construction and Validation', function () {
+        it('can create valid lock keys', function () {
+            $validKeys = [
+                'simple-lock',
+                'job.12345',
+                'queue.email_processing',
+                'worker.worker-123',
+                'resource.database_connection',
+                'batch.monthly_report_2024',
+                'a', // minimum length
+                str_repeat('a', 255) // maximum length
+            ];
+
+            foreach ($validKeys as $key) {
+                $lockKey = LockKey::fromString($key);
+                expect($lockKey->toString())->toBe($key);
+            }
+        });
+
+        it('rejects invalid lock keys', function () {
+            $invalidKeys = [
+                '', // empty
+                str_repeat('a', 256), // too long
+                'lock with spaces',
+                'lock@invalid',
+                'lock#invalid',
+                'lock$invalid',
+                'lock%invalid',
+                'lock&invalid',
+                'lock*invalid',
+                'lock(invalid)',
+                'lock+invalid',
+                'lock=invalid',
+                'lock[invalid]',
+                'lock{invalid}',
+                'lock|invalid',
+                'lock\\invalid',
+                'lock:invalid',
+                'lock;invalid',
+                'lock"invalid',
+                'lock\'invalid',
+                'lock<invalid>',
+                'lock,invalid',
+                'lock?invalid',
+                'lock/invalid',
+                'lock~invalid',
+                'lock`invalid'
+            ];
+
+            foreach ($invalidKeys as $key) {
+                expect(fn() => LockKey::fromString($key))
+                    ->toThrow(\InvalidArgumentException::class);
+            }
+        });
+
+        it('allows valid characters', function () {
+            $validChars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.';
+            $lockKey = LockKey::fromString($validChars);
+
+            expect($lockKey->toString())->toBe($validChars);
+        });
+
+        it('is readonly and immutable', function () {
+            $lockKey = LockKey::fromString('test-lock');
+
+            $reflection = new ReflectionClass($lockKey);
+            expect($reflection->isReadOnly())->toBeTrue();
+
+            $valueProperty = $reflection->getProperty('value');
+            expect($valueProperty->isReadOnly())->toBeTrue();
+        });
+    });
+
+    describe('Factory Methods', function () {
+        it('creates lock key for job', function () {
+            $jobId = JobId::fromString('job-12345');
+            $lockKey = LockKey::forJob($jobId);
+
+            expect($lockKey->toString())->toBe('job.job-12345');
+        });
+
+        it('creates lock key for queue', function () {
+            $queueName = QueueName::fromString('email-processing');
+            $lockKey = LockKey::forQueue($queueName);
+
+            expect($lockKey->toString())->toBe('queue.email-processing');
+        });
+
+        it('creates lock key for worker', function () {
+            $workerId = WorkerId::fromString('worker-123');
+            $lockKey = LockKey::forWorker($workerId);
+
+            expect($lockKey->toString())->toBe('worker.worker-123');
+        });
+
+        it('creates lock key for resource', function () {
+            $lockKey = LockKey::forResource('database', 'primary_db');
+
+            expect($lockKey->toString())->toBe('database.primary_db');
+        });
+
+        it('creates lock key for batch', function () {
+            $lockKey = LockKey::forBatch('monthly-report-2024-01');
+
+            expect($lockKey->toString())->toBe('batch.monthly-report-2024-01');
+        });
+    });
+
+    describe('String Operations', function () {
+        it('equals() compares lock keys correctly', function () {
+            $key1 = LockKey::fromString('test-lock');
+            $key2 = LockKey::fromString('test-lock');
+            $key3 = LockKey::fromString('other-lock');
+
+            expect($key1->equals($key2))->toBeTrue();
+            expect($key1->equals($key3))->toBeFalse();
+            expect($key2->equals($key3))->toBeFalse();
+        });
+
+        it('string representation works correctly', function () {
+            $value = 'test-lock-key';
+            $lockKey = LockKey::fromString($value);
+
+            expect($lockKey->toString())->toBe($value);
+            expect((string) $lockKey)->toBe($value);
+            expect($lockKey->jsonSerialize())->toBe($value);
+        });
+
+        it('withPrefix() creates new instance with prefix', function () {
+            $original = LockKey::fromString('test-lock');
+            $prefixed = $original->withPrefix('system');
+
+            expect($prefixed->toString())->toBe('system.test-lock');
+            expect($original->toString())->toBe('test-lock'); // Original unchanged
+        });
+
+        it('withSuffix() creates new instance with suffix', function () {
+            $original = LockKey::fromString('test-lock');
+            $suffixed = $original->withSuffix('v2');
+
+            expect($suffixed->toString())->toBe('test-lock.v2');
+            expect($original->toString())->toBe('test-lock'); // Original unchanged
+        });
+
+        it('can chain prefix and suffix', function () {
+            $original = LockKey::fromString('lock');
+            $chained = $original->withPrefix('system')->withSuffix('temp');
+
+            expect($chained->toString())->toBe('system.lock.temp');
+            expect($original->toString())->toBe('lock'); // Original unchanged
+        });
+
+        it('matches() supports pattern matching', function () {
+            $lockKey = LockKey::fromString('job.email.batch-123');
+
+            expect($lockKey->matches('job.*'))->toBeTrue();
+            expect($lockKey->matches('job.email.*'))->toBeTrue();
+            expect($lockKey->matches('*.batch-123'))->toBeTrue();
+            expect($lockKey->matches('*email*'))->toBeTrue();
+            expect($lockKey->matches('worker.*'))->toBeFalse();
+            expect($lockKey->matches('*.queue.*'))->toBeFalse();
+        });
+    });
+
+    describe('Edge Cases', function () {
+        it('handles minimum and maximum length keys', function () {
+            $minKey = LockKey::fromString('x');
+            expect($minKey->toString())->toBe('x');
+
+            $maxKey = LockKey::fromString(str_repeat('a', 255));
+            expect($maxKey->toString())->toBe(str_repeat('a', 255));
+        });
+
+        it('validates prefix and suffix additions', function () {
+            $baseKey = LockKey::fromString(str_repeat('a', 250)); // Near max length
+
+            // This should work (255 chars total)
+            $withShortPrefix = $baseKey->withPrefix('x');
+            expect(strlen($withShortPrefix->toString()))->toBe(252); // 'x' + '.' + 250
+
+            // This should fail (would exceed 255 chars)
+            expect(fn() => $baseKey->withPrefix('toolong'))
+                ->toThrow(\InvalidArgumentException::class);
+        });
+
+        it('handles complex key structures', function () {
+            $complexKey = LockKey::fromString('system.queue.email-processing.worker-123.batch-456');
+
+            expect($complexKey->matches('system.*'))->toBeTrue();
+            expect($complexKey->matches('*.queue.*'))->toBeTrue();
+            expect($complexKey->matches('*email-processing*'))->toBeTrue();
+            expect($complexKey->matches('*batch-456'))->toBeTrue();
+        });
+    });
+});
+
+describe('Distributed Lock Mock Implementation', function () {
+
+    beforeEach(function () {
+        // Create a mock distributed lock for testing
+        $this->distributedLock = new class {
+            private array $locks = [];
+
+            public function acquire(LockKey $key, WorkerId $workerId, Duration $ttl): bool {
+                $keyStr = $key->toString();
+                $now = time();
+
+                // Check if lock already exists and is not expired
+                if (isset($this->locks[$keyStr])) {
+                    $lock = $this->locks[$keyStr];
+                    if ($lock['expires_at'] > $now) {
+                        return false; // Lock already held
+                    }
+                }
+
+                // Acquire lock
+                $this->locks[$keyStr] = [
+                    'worker_id' => $workerId->toString(),
+                    'acquired_at' => $now,
+                    'expires_at' => $now + $ttl->toSeconds(),
+                    'ttl' => $ttl->toSeconds()
+                ];
+
+                return true;
+            }
+
+            public function extend(LockKey $key, WorkerId $workerId, Duration $ttl): bool {
+                $keyStr = $key->toString();
+                $now = time();
+
+                if (!isset($this->locks[$keyStr])) {
+                    return false; // Lock doesn't exist
+                }
+
+                $lock = $this->locks[$keyStr];
+
+                // Only the lock owner can extend it and it must not be expired
+                if ($lock['worker_id'] !== $workerId->toString() || $lock['expires_at'] <= $now) {
+                    return false;
+                }
+
+                // Extend the lock
+                $this->locks[$keyStr]['expires_at'] = $now + $ttl->toSeconds();
+                $this->locks[$keyStr]['ttl'] = $ttl->toSeconds();
+
+                return true;
+            }
+
+            public function release(LockKey $key, WorkerId $workerId): bool {
+                $keyStr = $key->toString();
+
+                if (!isset($this->locks[$keyStr])) {
+                    return false; // Lock doesn't exist
+                }
+
+                $lock = $this->locks[$keyStr];
+
+                // Only the lock owner can release it
+                if ($lock['worker_id'] !== $workerId->toString()) {
+                    return false;
+                }
+
+                unset($this->locks[$keyStr]);
+                return true;
+            }
+
+            public function exists(LockKey $key): bool {
+                $keyStr = $key->toString();
+                $now = time();
+
+                if (!isset($this->locks[$keyStr])) {
+                    return false;
+                }
+
+                $lock = $this->locks[$keyStr];
+                return $lock['expires_at'] > $now;
+            }
+
+            public function getLockInfo(LockKey $key): ?array {
+                $keyStr = $key->toString();
+                $now = time();
+
+                if (!isset($this->locks[$keyStr])) {
+                    return null;
+                }
+
+                $lock = $this->locks[$keyStr];
+
+                if ($lock['expires_at'] <= $now) {
+                    return null; // Expired
+                }
+
+                return [
+                    'lock_key' => $keyStr,
+                    'worker_id' => $lock['worker_id'],
+                    'acquired_at' => date('Y-m-d H:i:s', $lock['acquired_at']),
+                    'expires_at' => date('Y-m-d H:i:s', $lock['expires_at']),
+                    'ttl_seconds' => $lock['expires_at'] - $now
+                ];
+            }
+
+            public function acquireWithTimeout(LockKey $key, WorkerId $workerId, Duration $ttl, Duration $timeout): bool {
+                $startTime = microtime(true);
+                $timeoutSeconds = $timeout->toSeconds();
+
+                while ((microtime(true) - $startTime) < $timeoutSeconds) {
+                    if ($this->acquire($key, $workerId, $ttl)) {
+                        return true;
+                    }
+                    usleep(100000); // 100ms
+                }
+
+                return false;
+            }
+
+            public function releaseAllWorkerLocks(WorkerId $workerId): int {
+                $workerIdStr = $workerId->toString();
+                $released = 0;
+
+                foreach ($this->locks as $key => $lock) {
+                    if ($lock['worker_id'] === $workerIdStr) {
+                        unset($this->locks[$key]);
+                        $released++;
+                    }
+                }
+
+                return $released;
+            }
+
+            public function cleanupExpiredLocks(): int {
+                $now = time();
+                $cleaned = 0;
+
+                foreach ($this->locks as $key => $lock) {
+                    if ($lock['expires_at'] <= $now) {
+                        unset($this->locks[$key]);
+                        $cleaned++;
+                    }
+                }
+
+                return $cleaned;
+            }
+
+            public function getLockStatistics(): array {
+                $now = time();
+                $activeLocks = 0;
+                $expiredLocks = 0;
+                $workers = [];
+
+                foreach ($this->locks as $lock) {
+                    if ($lock['expires_at'] > $now) {
+                        $activeLocks++;
+                        $workers[$lock['worker_id']] = true;
+                    } else {
+                        $expiredLocks++;
+                    }
+                }
+
+                return [
+                    'total_locks' => count($this->locks),
+                    'active_locks' => $activeLocks,
+                    'expired_locks' => $expiredLocks,
+                    'unique_workers' => count($workers),
+                    'avg_ttl_seconds' => $activeLocks > 0 ?
+                        array_sum(array_map(fn($lock) => $lock['ttl'], array_filter($this->locks, fn($lock) => $lock['expires_at'] > $now))) / $activeLocks
+                        : 0
+                ];
+            }
+        };
+    });
+
+    describe('Basic Lock Operations', function () {
+        it('can acquire and release locks', function () {
+            $lockKey = LockKey::fromString('test-lock');
+            $workerId = WorkerId::fromString('worker-1');
+            $ttl = Duration::fromSeconds(300);
+
+            // Initially lock should not exist
+            expect($this->distributedLock->exists($lockKey))->toBeFalse();
+
+            // Acquire lock
+            $acquired = $this->distributedLock->acquire($lockKey, $workerId, $ttl);
+            expect($acquired)->toBeTrue();
+
+            // Lock should now exist
+            expect($this->distributedLock->exists($lockKey))->toBeTrue();
+
+            // Get lock info
+            $info = $this->distributedLock->getLockInfo($lockKey);
+            expect($info)->not->toBeNull();
+            expect($info['worker_id'])->toBe('worker-1');
+            expect($info['ttl_seconds'])->toBeGreaterThan(299);
+
+            // Release lock
+            $released = $this->distributedLock->release($lockKey, $workerId);
+            expect($released)->toBeTrue();
+
+            // Lock should no longer exist
+            expect($this->distributedLock->exists($lockKey))->toBeFalse();
+        });
+
+        it('prevents double acquisition of same lock', function () {
+            $lockKey = LockKey::fromString('exclusive-lock');
+            $worker1 = WorkerId::fromString('worker-1');
+            $worker2 = WorkerId::fromString('worker-2');
+            $ttl = Duration::fromSeconds(300);
+
+            // Worker 1 acquires lock
+            $acquired1 = $this->distributedLock->acquire($lockKey, $worker1, $ttl);
+            expect($acquired1)->toBeTrue();
+
+            // Worker 2 cannot acquire same lock
+            $acquired2 = $this->distributedLock->acquire($lockKey, $worker2, $ttl);
+            expect($acquired2)->toBeFalse();
+
+            // Worker 1 cannot acquire it again
+            $acquiredAgain = $this->distributedLock->acquire($lockKey, $worker1, $ttl);
+            expect($acquiredAgain)->toBeFalse();
+        });
+
+        it('only allows lock owner to release lock', function () {
+            $lockKey = LockKey::fromString('owner-lock');
+            $owner = WorkerId::fromString('owner-worker');
+            $other = WorkerId::fromString('other-worker');
+            $ttl = Duration::fromSeconds(300);
+
+            // Owner acquires lock
+            $this->distributedLock->acquire($lockKey, $owner, $ttl);
+
+            // Other worker cannot release it
+            $released = $this->distributedLock->release($lockKey, $other);
+            expect($released)->toBeFalse();
+
+            // Lock should still exist
+            expect($this->distributedLock->exists($lockKey))->toBeTrue();
+
+            // Owner can release it
+            $released = $this->distributedLock->release($lockKey, $owner);
+            expect($released)->toBeTrue();
+
+            // Lock should no longer exist
+            expect($this->distributedLock->exists($lockKey))->toBeFalse();
+        });
+    });
+
+    describe('Lock Extension', function () {
+        it('can extend lock TTL', function () {
+            $lockKey = LockKey::fromString('extend-test');
+            $workerId = WorkerId::fromString('worker-1');
+            $initialTtl = Duration::fromSeconds(300);
+            $extendedTtl = Duration::fromSeconds(600);
+
+            // Acquire lock
+            $this->distributedLock->acquire($lockKey, $workerId, $initialTtl);
+
+            $initialInfo = $this->distributedLock->getLockInfo($lockKey);
+            expect($initialInfo['ttl_seconds'])->toBeGreaterThan(299);
+
+            // Extend lock
+            $extended = $this->distributedLock->extend($lockKey, $workerId, $extendedTtl);
+            expect($extended)->toBeTrue();
+
+            $extendedInfo = $this->distributedLock->getLockInfo($lockKey);
+            expect($extendedInfo['ttl_seconds'])->toBeGreaterThan(599);
+        });
+
+        it('only allows lock owner to extend lock', function () {
+            $lockKey = LockKey::fromString('extend-owner-test');
+            $owner = WorkerId::fromString('owner-worker');
+            $other = WorkerId::fromString('other-worker');
+            $ttl = Duration::fromSeconds(300);
+
+            // Owner acquires lock
+            $this->distributedLock->acquire($lockKey, $owner, $ttl);
+
+            // Other worker cannot extend it
+            $extended = $this->distributedLock->extend($lockKey, $other, $ttl);
+            expect($extended)->toBeFalse();
+
+            // Owner can extend it
+            $extended = $this->distributedLock->extend($lockKey, $owner, $ttl);
+            expect($extended)->toBeTrue();
+        });
+
+        it('cannot extend non-existent lock', function () {
+            $lockKey = LockKey::fromString('non-existent-lock');
+            $workerId = WorkerId::fromString('worker-1');
+            $ttl = Duration::fromSeconds(300);
+
+            $extended = $this->distributedLock->extend($lockKey, $workerId, $ttl);
+            expect($extended)->toBeFalse();
+        });
+    });
+
+    describe('Lock Timeout and Acquisition', function () {
+        it('can acquire lock with timeout', function () {
+            $lockKey = LockKey::fromString('timeout-test');
+            $workerId = WorkerId::fromString('worker-1');
+            $ttl = Duration::fromSeconds(300);
+            $timeout = Duration::fromSeconds(1);
+
+            // Should acquire immediately since lock doesn't exist
+            $start = microtime(true);
+            $acquired = $this->distributedLock->acquireWithTimeout($lockKey, $workerId, $ttl, $timeout);
+            $elapsed = microtime(true) - $start;
+
+            expect($acquired)->toBeTrue();
+            expect($elapsed)->toBeLessThan(0.1); // Should be immediate
+        });
+
+        it('times out when lock is held by another worker', function () {
+            $lockKey = LockKey::fromString('timeout-fail-test');
+            $worker1 = WorkerId::fromString('worker-1');
+            $worker2 = WorkerId::fromString('worker-2');
+            $ttl = Duration::fromSeconds(300);
+            $timeout = Duration::fromSeconds(0.5);
+
+            // Worker 1 acquires lock
+            $this->distributedLock->acquire($lockKey, $worker1, $ttl);
+
+            // Worker 2 tries to acquire with timeout
+            $start = microtime(true);
+            $acquired = $this->distributedLock->acquireWithTimeout($lockKey, $worker2, $ttl, $timeout);
+            $elapsed = microtime(true) - $start;
+
+            expect($acquired)->toBeFalse();
+            expect($elapsed)->toBeGreaterThan(0.4); // Should have waited
+            expect($elapsed)->toBeLessThan(0.7); // But not too long
+        });
+    });
+
+    describe('Bulk Operations', function () {
+        it('can release all locks for a worker', function () {
+            $worker1 = WorkerId::fromString('worker-1');
+            $worker2 = WorkerId::fromString('worker-2');
+            $ttl = Duration::fromSeconds(300);
+
+            // Worker 1 acquires multiple locks
+            $lock1 = LockKey::fromString('lock-1');
+            $lock2 = LockKey::fromString('lock-2');
+            $lock3 = LockKey::fromString('lock-3');
+
+            $this->distributedLock->acquire($lock1, $worker1, $ttl);
+            $this->distributedLock->acquire($lock2, $worker1, $ttl);
+            $this->distributedLock->acquire($lock3, $worker2, $ttl); // Different worker
+
+            // Verify locks exist
+            expect($this->distributedLock->exists($lock1))->toBeTrue();
+            expect($this->distributedLock->exists($lock2))->toBeTrue();
+            expect($this->distributedLock->exists($lock3))->toBeTrue();
+
+            // Release all worker1 locks
+            $released = $this->distributedLock->releaseAllWorkerLocks($worker1);
+            expect($released)->toBe(2);
+
+            // Worker1 locks should be gone, worker2 lock should remain
+            expect($this->distributedLock->exists($lock1))->toBeFalse();
+            expect($this->distributedLock->exists($lock2))->toBeFalse();
+            expect($this->distributedLock->exists($lock3))->toBeTrue();
+        });
+
+        it('can cleanup expired locks', function () {
+            $lockKey = LockKey::fromString('expiring-lock');
+            $workerId = WorkerId::fromString('worker-1');
+            $shortTtl = Duration::fromSeconds(1);
+
+            // Acquire lock with short TTL
+            $this->distributedLock->acquire($lockKey, $workerId, $shortTtl);
+            expect($this->distributedLock->exists($lockKey))->toBeTrue();
+
+            // Wait for expiration
+            sleep(2);
+
+            // Lock should appear expired but still be in storage
+            expect($this->distributedLock->exists($lockKey))->toBeFalse();
+
+            // Cleanup should remove expired locks
+            $cleaned = $this->distributedLock->cleanupExpiredLocks();
+            expect($cleaned)->toBe(1);
+        });
+    });
+
+    describe('Lock Statistics', function () {
+        it('provides accurate lock statistics', function () {
+            $worker1 = WorkerId::fromString('worker-1');
+            $worker2 = WorkerId::fromString('worker-2');
+            $ttl = Duration::fromSeconds(300);
+
+            // Initially no locks
+            $stats = $this->distributedLock->getLockStatistics();
+            expect($stats['total_locks'])->toBe(0);
+            expect($stats['active_locks'])->toBe(0);
+            expect($stats['unique_workers'])->toBe(0);
+
+            // Add some locks
+            $this->distributedLock->acquire(LockKey::fromString('lock-1'), $worker1, $ttl);
+            $this->distributedLock->acquire(LockKey::fromString('lock-2'), $worker1, $ttl);
+            $this->distributedLock->acquire(LockKey::fromString('lock-3'), $worker2, $ttl);
+
+            $stats = $this->distributedLock->getLockStatistics();
+            expect($stats['total_locks'])->toBe(3);
+            expect($stats['active_locks'])->toBe(3);
+            expect($stats['unique_workers'])->toBe(2);
+            expect($stats['avg_ttl_seconds'])->toBe(300.0);
+        });
+
+        it('distinguishes between active and expired locks', function () {
+            $workerId = WorkerId::fromString('worker-1');
+            $longTtl = Duration::fromSeconds(300);
+            $shortTtl = Duration::fromSeconds(1);
+
+            // Add active and soon-to-expire locks
+            $this->distributedLock->acquire(LockKey::fromString('active-lock'), $workerId, $longTtl);
+            $this->distributedLock->acquire(LockKey::fromString('expiring-lock'), $workerId, $shortTtl);
+
+            // Initially both active
+            $stats = $this->distributedLock->getLockStatistics();
+            expect($stats['active_locks'])->toBe(2);
+            expect($stats['expired_locks'])->toBe(0);
+
+            // Wait for one to expire
+            sleep(2);
+
+            $stats = $this->distributedLock->getLockStatistics();
+            expect($stats['total_locks'])->toBe(2); // Still in storage
+            expect($stats['active_locks'])->toBe(1); // One still active
+            expect($stats['expired_locks'])->toBe(1); // One expired
+        });
+    });
+});
+
+describe('Distributed Lock Integration Scenarios', function () {
+
+    beforeEach(function () {
+        $this->distributedLock = new class {
+            private array $locks = [];
+            public function acquire(LockKey $key, WorkerId $workerId, Duration $ttl): bool {
+                $keyStr = $key->toString();
+                $now = time();
+                if (isset($this->locks[$keyStr]) && $this->locks[$keyStr]['expires_at'] > $now) {
+                    return false;
+                }
+                $this->locks[$keyStr] = [
+                    'worker_id' => $workerId->toString(),
+                    'acquired_at' => $now,
+                    'expires_at' => $now + $ttl->toSeconds()
+                ];
+                return true;
+            }
+            public function release(LockKey $key, WorkerId $workerId): bool {
+                $keyStr = $key->toString();
+                if (!isset($this->locks[$keyStr]) || $this->locks[$keyStr]['worker_id'] !== $workerId->toString()) {
+                    return false;
+                }
+                unset($this->locks[$keyStr]);
+                return true;
+            }
+            public function exists(LockKey $key): bool {
+                $keyStr = $key->toString();
+                return isset($this->locks[$keyStr]) && $this->locks[$keyStr]['expires_at'] > time();
+            }
+        };
+
+        $this->emailJob = new class {
+            public function __construct(
+                public string $batchId = 'email-batch-123',
+                public int $recipientCount = 1000
+            ) {}
+        };
+
+        $this->reportJob = new class {
+            public function __construct(
+                public string $reportId = 'monthly-sales-2024',
+                public string $resourceType = 'database'
+            ) {}
+        };
+    });
+
+    it('demonstrates job-level locking for email batches', function () {
+        $batchLockKey = LockKey::forBatch($this->emailJob->batchId);
+        $worker1 = WorkerId::fromString('email-worker-1');
+        $worker2 = WorkerId::fromString('email-worker-2');
+        $processingTime = Duration::fromMinutes(30);
+
+        // Worker 1 acquires lock for batch processing
+        $acquired = $this->distributedLock->acquire($batchLockKey, $worker1, $processingTime);
+        expect($acquired)->toBeTrue();
+
+        // Worker 2 cannot process the same batch
+        $blocked = $this->distributedLock->acquire($batchLockKey, $worker2, $processingTime);
+        expect($blocked)->toBeFalse();
+
+        // After processing, worker 1 releases the lock
+        $released = $this->distributedLock->release($batchLockKey, $worker1);
+        expect($released)->toBeTrue();
+
+        // Now worker 2 can acquire the lock
+        $nowAvailable = $this->distributedLock->acquire($batchLockKey, $worker2, $processingTime);
+        expect($nowAvailable)->toBeTrue();
+    });
+
+    it('demonstrates resource-level locking for reports', function () {
+        $resourceLockKey = LockKey::forResource($this->reportJob->resourceType, 'primary');
+        $reportWorker = WorkerId::fromString('report-worker-1');
+        $maintenanceWorker = WorkerId::fromString('maintenance-worker');
+        $reportTime = Duration::fromMinutes(15);
+        $maintenanceTime = Duration::fromHours(2);
+
+        // Report worker acquires database resource
+        $reportAcquired = $this->distributedLock->acquire($resourceLockKey, $reportWorker, $reportTime);
+        expect($reportAcquired)->toBeTrue();
+
+        // Maintenance worker cannot access the resource
+        $maintenanceBlocked = $this->distributedLock->acquire($resourceLockKey, $maintenanceWorker, $maintenanceTime);
+        expect($maintenanceBlocked)->toBeFalse();
+
+        // Report completes and releases resource
+        $reportReleased = $this->distributedLock->release($resourceLockKey, $reportWorker);
+        expect($reportReleased)->toBeTrue();
+
+        // Maintenance can now proceed
+        $maintenanceAcquired = $this->distributedLock->acquire($resourceLockKey, $maintenanceWorker, $maintenanceTime);
+        expect($maintenanceAcquired)->toBeTrue();
+    });
+
+    it('demonstrates queue-level locking for exclusive processing', function () {
+        $emailQueueKey = LockKey::forQueue(QueueName::fromString('email-queue'));
+        $priorityWorker = WorkerId::fromString('priority-worker');
+        $normalWorker = WorkerId::fromString('normal-worker');
+        $exclusiveTime = Duration::fromMinutes(5);
+
+        // Priority worker takes exclusive access to queue
+        $exclusiveAcquired = $this->distributedLock->acquire($emailQueueKey, $priorityWorker, $exclusiveTime);
+        expect($exclusiveAcquired)->toBeTrue();
+
+        // Normal worker must wait
+        $normalBlocked = $this->distributedLock->acquire($emailQueueKey, $normalWorker, Duration::fromMinutes(1));
+        expect($normalBlocked)->toBeFalse();
+
+        // After priority processing, queue becomes available
+        $exclusiveReleased = $this->distributedLock->release($emailQueueKey, $priorityWorker);
+        expect($exclusiveReleased)->toBeTrue();
+
+        $normalAcquired = $this->distributedLock->acquire($emailQueueKey, $normalWorker, Duration::fromMinutes(10));
+        expect($normalAcquired)->toBeTrue();
+    });
+
+    it('demonstrates worker-level locking for maintenance operations', function () {
+        $worker1 = WorkerId::fromString('maintenance-worker-1');
+        $worker1LockKey = LockKey::forWorker($worker1);
+        $maintenanceSystem = WorkerId::fromString('maintenance-system');
+        $maintenanceTime = Duration::fromHours(1);
+
+        // Worker is performing normal operations
+        expect($this->distributedLock->exists($worker1LockKey))->toBeFalse();
+
+        // Maintenance system needs to pause the worker
+        $maintenanceLock = $this->distributedLock->acquire($worker1LockKey, $maintenanceSystem, $maintenanceTime);
+        expect($maintenanceLock)->toBeTrue();
+
+        // Worker cannot proceed with new jobs while maintenance lock is held
+        $workerBlocked = $this->distributedLock->acquire($worker1LockKey, $worker1, Duration::fromMinutes(1));
+        expect($workerBlocked)->toBeFalse();
+
+        // After maintenance, worker can resume
+        $maintenanceReleased = $this->distributedLock->release($worker1LockKey, $maintenanceSystem);
+        expect($maintenanceReleased)->toBeTrue();
+
+        $workerResumed = $this->distributedLock->acquire($worker1LockKey, $worker1, Duration::fromMinutes(30));
+        expect($workerResumed)->toBeTrue();
+    });
+
+    it('demonstrates hierarchical locking patterns', function () {
+        $systemLock = LockKey::fromString('system.maintenance');
+        $queueLock = LockKey::fromString('system.queue.email');
+        $jobLock = LockKey::fromString('system.queue.email.job-123');
+
+        $maintenanceWorker = WorkerId::fromString('maintenance-worker');
+        $queueWorker = WorkerId::fromString('queue-worker');
+        $jobWorker = WorkerId::fromString('job-worker');
+
+        // System-wide maintenance lock
+        $systemAcquired = $this->distributedLock->acquire($systemLock, $maintenanceWorker, Duration::fromHours(1));
+        expect($systemAcquired)->toBeTrue();
+
+        // Queue-level operations should be blocked during system maintenance
+        $queueBlocked = $this->distributedLock->acquire($queueLock, $queueWorker, Duration::fromMinutes(30));
+        expect($queueBlocked)->toBeFalse();
+
+        // Job-level operations should also be blocked
+        $jobBlocked = $this->distributedLock->acquire($jobLock, $jobWorker, Duration::fromMinutes(5));
+        expect($jobBlocked)->toBeFalse();
+
+        // After system maintenance
+        $this->distributedLock->release($systemLock, $maintenanceWorker);
+
+        // Lower-level operations can proceed
+        $queueNowAcquired = $this->distributedLock->acquire($queueLock, $queueWorker, Duration::fromMinutes(30));
+        expect($queueNowAcquired)->toBeTrue();
+    });
+});

tests/Framework/Queue/Entities/WorkerTest.php

@@ -0,0 +1,420 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\Entities\Worker;
+use App\Framework\Queue\ValueObjects\WorkerId;
+use App\Framework\Queue\ValueObjects\QueueName;
+use App\Framework\Core\ValueObjects\Percentage;
+use App\Framework\Core\ValueObjects\Byte;
+
+describe('Worker Entity', function () {
+    beforeEach(function () {
+        $this->workerId = WorkerId::generate();
+        $this->queues = [
+            QueueName::defaultQueue(),
+            QueueName::emailQueue()
+        ];
+        $this->capabilities = ['email', 'pdf-generation', 'image-processing'];
+    });
+
+    it('can register a new worker with valid parameters', function () {
+        $worker = Worker::register(
+            hostname: 'app-server-1',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: 10,
+            capabilities: $this->capabilities
+        );
+
+        expect($worker->hostname)->toBe('app-server-1');
+        expect($worker->processId)->toBe(1001);
+        expect($worker->queues)->toHaveCount(2);
+        expect($worker->maxJobs)->toBe(10);
+        expect($worker->currentJobs)->toBe(0);
+        expect($worker->isActive)->toBeTrue();
+        expect($worker->capabilities)->toBe($this->capabilities);
+        expect($worker->registeredAt)->toBeInstanceOf(\DateTimeImmutable::class);
+        expect($worker->lastHeartbeat)->toBeInstanceOf(\DateTimeImmutable::class);
+    });
+
+    it('validates worker construction constraints', function () {
+        // Empty queues
+        expect(fn() => Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: [], // Invalid
+            maxJobs: 10
+        ))->toThrow(\InvalidArgumentException::class, 'Worker must handle at least one queue');
+
+        // Invalid max jobs
+        expect(fn() => Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: 0 // Invalid
+        ))->toThrow(\InvalidArgumentException::class, 'Max jobs must be greater than 0');
+
+        expect(fn() => Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: -5 // Invalid
+        ))->toThrow(\InvalidArgumentException::class, 'Max jobs must be greater than 0');
+    });
+
+    it('validates current jobs constraints', function () {
+        $worker = Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: 5
+        );
+
+        // Negative current jobs should fail during construction
+        expect(fn() => new Worker(
+            id: $worker->id,
+            hostname: $worker->hostname,
+            processId: $worker->processId,
+            queues: $worker->queues,
+            maxJobs: $worker->maxJobs,
+            registeredAt: $worker->registeredAt,
+            currentJobs: -1 // Invalid
+        ))->toThrow(\InvalidArgumentException::class, 'Current jobs cannot be negative');
+
+        // Current jobs exceeding max jobs should fail
+        expect(fn() => new Worker(
+            id: $worker->id,
+            hostname: $worker->hostname,
+            processId: $worker->processId,
+            queues: $worker->queues,
+            maxJobs: $worker->maxJobs,
+            registeredAt: $worker->registeredAt,
+            currentJobs: 10 // Exceeds maxJobs of 5
+        ))->toThrow(\InvalidArgumentException::class, 'Current jobs cannot exceed max jobs');
+    });
+
+    it('can update heartbeat with resource usage', function () {
+        $worker = Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: 10
+        );
+
+        $updatedWorker = $worker->updateHeartbeat(
+            cpuUsage: new Percentage(45),
+            memoryUsage: Byte::fromMegabytes(800),
+            currentJobs: 3
+        );
+
+        expect($updatedWorker->cpuUsage->getValue())->toBe(45.0);
+        expect($updatedWorker->memoryUsage->toMegabytes())->toBe(800.0);
+        expect($updatedWorker->currentJobs)->toBe(3);
+        expect($updatedWorker->isActive)->toBeTrue();
+        expect($updatedWorker->lastHeartbeat)->toBeInstanceOf(\DateTimeImmutable::class);
+
+        // Original worker should be unchanged (immutable)
+        expect($worker->cpuUsage->getValue())->toBe(0.0);
+        expect($worker->currentJobs)->toBe(0);
+    });
+
+    it('can mark worker as inactive', function () {
+        $worker = Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: 10
+        );
+
+        $inactiveWorker = $worker->markInactive();
+
+        expect($inactiveWorker->isActive)->toBeFalse();
+        expect($worker->isActive)->toBeTrue(); // Original unchanged
+    });
+
+    it('correctly determines worker availability', function () {
+        $worker = Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: 5
+        );
+
+        // Fresh worker should be available
+        expect($worker->isAvailableForJobs())->toBeTrue();
+
+        // Worker at capacity should not be available
+        $atCapacityWorker = $worker->updateHeartbeat(
+            new Percentage(30),
+            Byte::fromMegabytes(500),
+            5 // At max capacity
+        );
+        expect($atCapacityWorker->isAvailableForJobs())->toBeFalse();
+
+        // Inactive worker should not be available
+        $inactiveWorker = $worker->markInactive();
+        expect($inactiveWorker->isAvailableForJobs())->toBeFalse();
+
+        // Unhealthy worker should not be available
+        $unhealthyWorker = $worker->updateHeartbeat(
+            new Percentage(95), // Critical CPU
+            Byte::fromGigabytes(3), // Over memory limit
+            2
+        );
+        expect($unhealthyWorker->isAvailableForJobs())->toBeFalse();
+    });
+
+    it('can check if worker handles specific queues', function () {
+        $worker = Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: [
+                QueueName::defaultQueue(),
+                QueueName::emailQueue()
+            ],
+            maxJobs: 10
+        );
+
+        expect($worker->handlesQueue(QueueName::defaultQueue()))->toBeTrue();
+        expect($worker->handlesQueue(QueueName::emailQueue()))->toBeTrue();
+        expect($worker->handlesQueue(QueueName::fromString('unknown-queue')))->toBeFalse();
+    });
+
+    it('correctly determines worker health status', function () {
+        $worker = Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: 10
+        );
+
+        // Fresh worker should be healthy
+        expect($worker->isHealthy())->toBeTrue();
+
+        // Worker with high CPU should be unhealthy
+        $highCpuWorker = $worker->updateHeartbeat(
+            new Percentage(95), // Over 90% threshold
+            Byte::fromMegabytes(500),
+            3
+        );
+        expect($highCpuWorker->isHealthy())->toBeFalse();
+
+        // Worker with excessive memory should be unhealthy
+        $highMemoryWorker = $worker->updateHeartbeat(
+            new Percentage(30),
+            Byte::fromGigabytes(3), // Over 2GB threshold
+            3
+        );
+        expect($highMemoryWorker->isHealthy())->toBeFalse();
+
+        // Inactive worker should be unhealthy
+        $inactiveWorker = $worker->markInactive();
+        expect($inactiveWorker->isHealthy())->toBeFalse();
+
+        // Worker with stale heartbeat should be unhealthy
+        $staleWorker = new Worker(
+            id: $worker->id,
+            hostname: $worker->hostname,
+            processId: $worker->processId,
+            queues: $worker->queues,
+            maxJobs: $worker->maxJobs,
+            registeredAt: $worker->registeredAt,
+            lastHeartbeat: new \DateTimeImmutable('-2 minutes'), // Stale
+            isActive: true,
+            cpuUsage: new Percentage(30),
+            memoryUsage: Byte::fromMegabytes(500),
+            currentJobs: 3
+        );
+        expect($staleWorker->isHealthy())->toBeFalse();
+
+        // Worker with no heartbeat should be unhealthy
+        $noHeartbeatWorker = new Worker(
+            id: $worker->id,
+            hostname: $worker->hostname,
+            processId: $worker->processId,
+            queues: $worker->queues,
+            maxJobs: $worker->maxJobs,
+            registeredAt: $worker->registeredAt,
+            lastHeartbeat: null, // No heartbeat
+            isActive: true
+        );
+        expect($noHeartbeatWorker->isHealthy())->toBeFalse();
+    });
+
+    it('calculates load percentage correctly', function () {
+        $worker = Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: 10
+        );
+
+        // Test job-based load
+        $jobLoadWorker = $worker->updateHeartbeat(
+            new Percentage(20), // 20% CPU
+            Byte::fromMegabytes(500),
+            3 // 3/10 = 30% job load
+        );
+        expect($jobLoadWorker->getLoadPercentage()->getValue())->toBe(30.0); // Higher of 20% CPU or 30% jobs
+
+        // Test CPU-based load
+        $cpuLoadWorker = $worker->updateHeartbeat(
+            new Percentage(75), // 75% CPU
+            Byte::fromMegabytes(500),
+            2 // 2/10 = 20% job load
+        );
+        expect($cpuLoadWorker->getLoadPercentage()->getValue())->toBe(75.0); // Higher of 75% CPU or 20% jobs
+
+        // Test worker with zero max jobs
+        $zeroJobsWorker = new Worker(
+            id: $worker->id,
+            hostname: $worker->hostname,
+            processId: $worker->processId,
+            queues: $worker->queues,
+            maxJobs: 0, // Special case
+            registeredAt: $worker->registeredAt,
+            lastHeartbeat: new \DateTimeImmutable(),
+            isActive: true,
+            currentJobs: 0
+        );
+        expect($zeroJobsWorker->getLoadPercentage()->getValue())->toBe(100.0);
+    });
+
+    it('can check worker capabilities', function () {
+        $worker = Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: 10,
+            capabilities: ['email', 'pdf-generation', 'image-processing']
+        );
+
+        expect($worker->hasCapability('email'))->toBeTrue();
+        expect($worker->hasCapability('pdf-generation'))->toBeTrue();
+        expect($worker->hasCapability('image-processing'))->toBeTrue();
+        expect($worker->hasCapability('video-processing'))->toBeFalse();
+        expect($worker->hasCapability(''))->toBeFalse();
+    });
+
+    it('provides comprehensive monitoring data', function () {
+        $worker = Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: 10,
+            capabilities: $this->capabilities
+        )->updateHeartbeat(
+            new Percentage(45),
+            Byte::fromMegabytes(800),
+            3
+        );
+
+        $monitoringData = $worker->toMonitoringArray();
+
+        expect($monitoringData)->toHaveKey('id');
+        expect($monitoringData)->toHaveKey('hostname');
+        expect($monitoringData)->toHaveKey('process_id');
+        expect($monitoringData)->toHaveKey('queues');
+        expect($monitoringData)->toHaveKey('max_jobs');
+        expect($monitoringData)->toHaveKey('current_jobs');
+        expect($monitoringData)->toHaveKey('is_active');
+        expect($monitoringData)->toHaveKey('is_healthy');
+        expect($monitoringData)->toHaveKey('is_available');
+        expect($monitoringData)->toHaveKey('load_percentage');
+        expect($monitoringData)->toHaveKey('cpu_usage');
+        expect($monitoringData)->toHaveKey('memory_usage_mb');
+        expect($monitoringData)->toHaveKey('capabilities');
+
+        expect($monitoringData['hostname'])->toBe('test-host');
+        expect($monitoringData['process_id'])->toBe(1001);
+        expect($monitoringData['max_jobs'])->toBe(10);
+        expect($monitoringData['current_jobs'])->toBe(3);
+        expect($monitoringData['is_active'])->toBeTrue();
+        expect($monitoringData['load_percentage'])->toBe(45.0);
+        expect($monitoringData['cpu_usage'])->toBe(45.0);
+        expect($monitoringData['memory_usage_mb'])->toBe(800.0);
+        expect($monitoringData['capabilities'])->toBe($this->capabilities);
+    });
+
+    it('can be serialized to array for persistence', function () {
+        $worker = Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: 10,
+            capabilities: $this->capabilities
+        );
+
+        $array = $worker->toArray();
+
+        expect($array)->toHaveKey('id');
+        expect($array)->toHaveKey('hostname');
+        expect($array)->toHaveKey('process_id');
+        expect($array)->toHaveKey('queues');
+        expect($array)->toHaveKey('max_jobs');
+        expect($array)->toHaveKey('current_jobs');
+        expect($array)->toHaveKey('is_active');
+        expect($array)->toHaveKey('cpu_usage');
+        expect($array)->toHaveKey('memory_usage_bytes');
+        expect($array)->toHaveKey('registered_at');
+        expect($array)->toHaveKey('last_heartbeat');
+        expect($array)->toHaveKey('capabilities');
+        expect($array)->toHaveKey('version');
+
+        // Queues should be JSON encoded
+        $queues = json_decode($array['queues'], true);
+        expect($queues)->toBeArray();
+        expect($queues)->toHaveCount(2);
+
+        // Capabilities should be JSON encoded
+        $capabilities = json_decode($array['capabilities'], true);
+        expect($capabilities)->toBe($this->capabilities);
+    });
+
+    it('can be reconstructed from array data', function () {
+        $originalWorker = Worker::register(
+            hostname: 'test-host',
+            processId: 1001,
+            queues: $this->queues,
+            maxJobs: 10,
+            capabilities: $this->capabilities
+        );
+
+        $array = $originalWorker->toArray();
+        $reconstructedWorker = Worker::fromArray($array);
+
+        expect($reconstructedWorker->hostname)->toBe($originalWorker->hostname);
+        expect($reconstructedWorker->processId)->toBe($originalWorker->processId);
+        expect($reconstructedWorker->maxJobs)->toBe($originalWorker->maxJobs);
+        expect($reconstructedWorker->currentJobs)->toBe($originalWorker->currentJobs);
+        expect($reconstructedWorker->isActive)->toBe($originalWorker->isActive);
+        expect($reconstructedWorker->capabilities)->toBe($originalWorker->capabilities);
+        expect($reconstructedWorker->version)->toBe($originalWorker->version);
+    });
+
+    it('handles edge cases in array reconstruction', function () {
+        $minimalData = [
+            'id' => 'test-worker-id',
+            'hostname' => 'test-host',
+            'process_id' => 1001,
+            'queues' => '["default"]',
+            'max_jobs' => 5,
+            'registered_at' => '2024-01-01 12:00:00',
+            'is_active' => 1
+        ];
+
+        $worker = Worker::fromArray($minimalData);
+
+        expect($worker->hostname)->toBe('test-host');
+        expect($worker->processId)->toBe(1001);
+        expect($worker->maxJobs)->toBe(5);
+        expect($worker->currentJobs)->toBe(0); // Default value
+        expect($worker->isActive)->toBeTrue();
+        expect($worker->lastHeartbeat)->toBeNull();
+        expect($worker->cpuUsage->getValue())->toBe(0.0);
+        expect($worker->memoryUsage->toBytes())->toBe(0);
+        expect($worker->capabilities)->toBe([]);
+        expect($worker->version)->toBe('1.0.0');
+    });
+});

tests/Framework/Queue/Integration/CompleteQueueSystemTest.php

@@ -0,0 +1,372 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\Contracts\QueueInterface;
+use App\Framework\Queue\Contracts\JobDependencyManagerInterface;
+use App\Framework\Queue\Contracts\JobChainManagerInterface;
+use App\Framework\Queue\Services\JobMetricsManager;
+use App\Framework\Queue\Services\DependencyResolutionEngine;
+use App\Framework\Queue\Services\JobChainExecutionCoordinator;
+use App\Framework\Queue\ValueObjects\JobDependency;
+use App\Framework\Queue\ValueObjects\JobChain;
+use App\Framework\Queue\ValueObjects\JobMetrics;
+use App\Framework\Queue\ValueObjects\ChainExecutionMode;
+use App\Framework\Queue\Entities\JobProgressEntry;
+use App\Framework\Queue\Entities\JobProgressStep;
+use App\Framework\Database\EntityManagerInterface;
+use App\Framework\Logging\Logger;
+use App\Framework\Core\Application;
+use App\Framework\DI\Container;
+use App\Framework\Core\ValueObjects\Percentage;
+
+beforeEach(function () {
+    // Set up test container
+    $this->container = createTestContainer();
+
+    // Get services from container
+    $this->queue = $this->container->get(QueueInterface::class);
+    $this->dependencyManager = $this->container->get(JobDependencyManagerInterface::class);
+    $this->chainManager = $this->container->get(JobChainManagerInterface::class);
+    $this->metricsManager = $this->container->get(JobMetricsManager::class);
+    $this->resolutionEngine = $this->container->get(DependencyResolutionEngine::class);
+    $this->chainCoordinator = $this->container->get(JobChainExecutionCoordinator::class);
+    $this->entityManager = $this->container->get(EntityManagerInterface::class);
+    $this->logger = $this->container->get(Logger::class);
+});
+
+function createTestJob(string $id, string $data): object
+{
+    return new class($id, $data) {
+        public function __construct(
+            public readonly string $id,
+            public readonly string $data
+        ) {}
+    };
+}
+
+test('complete queue workflow with dependencies and metrics', function () {
+    // 1. Create test jobs
+    $job1 = createTestJob('job-1', 'Test Job 1');
+    $job2 = createTestJob('job-2', 'Test Job 2');
+    $job3 = createTestJob('job-3', 'Test Job 3');
+
+    // 2. Set up dependencies: job2 depends on job1, job3 depends on job2
+    $dependency1 = JobDependency::completion('job-2', 'job-1');
+    $dependency2 = JobDependency::success('job-3', 'job-2');
+
+    // Add dependencies
+    $this->dependencyManager->addDependency($dependency1);
+    $this->dependencyManager->addDependency($dependency2);
+
+    // 3. Add jobs to queue
+    $this->queue->push($job1);
+    $this->queue->push($job2);
+    $this->queue->push($job3);
+
+    // 4. Create and record metrics for job execution
+    $job1Metrics = new JobMetrics(
+        jobId: 'job-1',
+        queueName: 'default',
+        status: 'completed',
+        attempts: 1,
+        maxAttempts: 3,
+        executionTimeMs: 150.5,
+        memoryUsageBytes: 1024 * 1024,
+        errorMessage: null,
+        createdAt: date('Y-m-d H:i:s'),
+        startedAt: date('Y-m-d H:i:s'),
+        completedAt: date('Y-m-d H:i:s'),
+        failedAt: null,
+        metadata: ['test' => true]
+    );
+
+    $this->metricsManager->recordJobMetrics($job1Metrics);
+
+    // 5. Test dependency resolution
+    $readyJobs = $this->resolutionEngine->getJobsReadyForExecution();
+    expect($readyJobs)->toHaveCount(1)
+        ->and($readyJobs[0])->toBe('job-1');
+
+    // 6. Mark job1 as completed and check dependencies
+    $this->dependencyManager->markJobCompleted('job-1');
+
+    $readyJobsAfterJob1 = $this->resolutionEngine->getJobsReadyForExecution();
+    expect($readyJobsAfterJob1)->toContain('job-2');
+
+    // 7. Test metrics retrieval
+    $retrievedMetrics = $this->metricsManager->getJobMetrics('job-1');
+    expect($retrievedMetrics)->not()->toBeNull()
+        ->and($retrievedMetrics->jobId)->toBe('job-1')
+        ->and($retrievedMetrics->status)->toBe('completed')
+        ->and($retrievedMetrics->executionTimeMs)->toBe(150.5);
+
+    // 8. Test queue metrics calculation
+    $queueMetrics = $this->metricsManager->getQueueMetrics('default', '1 hour');
+    expect($queueMetrics->queueName)->toBe('default')
+        ->and($queueMetrics->totalJobs)->toBeGreaterThan(0);
+});
+
+test('job chain execution with sequential mode', function () {
+    // 1. Create jobs for chain
+    $jobs = [
+        createTestJob('chain-job-1', 'Chain Job 1'),
+        createTestJob('chain-job-2', 'Chain Job 2'),
+        createTestJob('chain-job-3', 'Chain Job 3')
+    ];
+
+    // 2. Create job chain
+    $chain = JobChain::sequential('test-chain', ['chain-job-1', 'chain-job-2', 'chain-job-3']);
+
+    // 3. Add chain to manager
+    $this->chainManager->createChain($chain);
+
+    // 4. Execute chain
+    $this->chainCoordinator->executeChain('test-chain');
+
+    // 5. Verify chain was created
+    $retrievedChain = $this->chainManager->getChain('test-chain');
+    expect($retrievedChain)->not()->toBeNull()
+        ->and($retrievedChain->name)->toBe('test-chain')
+        ->and($retrievedChain->executionMode)->toBe(ChainExecutionMode::SEQUENTIAL)
+        ->and($retrievedChain->jobIds)->toHaveCount(3);
+});
+
+test('job chain failure handling', function () {
+    // 1. Create jobs for chain with one that will fail
+    $jobs = [
+        createTestJob('fail-job-1', 'Job 1'),
+        createTestJob('fail-job-2', 'Job 2 (will fail)'),
+        createTestJob('fail-job-3', 'Job 3')
+    ];
+
+    // 2. Create job chain with stop on failure
+    $chain = JobChain::sequential('fail-chain', ['fail-job-1', 'fail-job-2', 'fail-job-3']);
+    $this->chainManager->createChain($chain);
+
+    // 3. Simulate job failure
+    $failureMetrics = new JobMetrics(
+        jobId: 'fail-job-2',
+        queueName: 'default',
+        status: 'failed',
+        attempts: 3,
+        maxAttempts: 3,
+        executionTimeMs: 50.0,
+        memoryUsageBytes: 512 * 1024,
+        errorMessage: 'Simulated failure',
+        createdAt: date('Y-m-d H:i:s'),
+        startedAt: date('Y-m-d H:i:s'),
+        completedAt: null,
+        failedAt: date('Y-m-d H:i:s'),
+        metadata: []
+    );
+
+    $this->metricsManager->recordJobMetrics($failureMetrics);
+
+    // 4. Test failure detection
+    $failedJobs = $this->metricsManager->getFailedJobs('default', '1 hour');
+    expect($failedJobs)->toHaveCount(1)
+        ->and($failedJobs[0]->jobId)->toBe('fail-job-2')
+        ->and($failedJobs[0]->status)->toBe('failed');
+});
+
+test('circular dependency detection', function () {
+    // 1. Create circular dependencies: A depends on B, B depends on C, C depends on A
+    $depA = JobDependency::completion('job-a', 'job-b');
+    $depB = JobDependency::completion('job-b', 'job-c');
+    $depC = JobDependency::completion('job-c', 'job-a');
+
+    // 2. Add dependencies
+    $this->dependencyManager->addDependency($depA);
+    $this->dependencyManager->addDependency($depB);
+
+    // 3. Adding the third dependency should throw an exception or be handled
+    expect(fn() => $this->dependencyManager->addDependency($depC))
+        ->toThrow(\InvalidArgumentException::class);
+});
+
+test('conditional dependencies', function () {
+    // 1. Create jobs
+    $job1 = createTestJob('cond-job-1', 'Conditional Job 1');
+    $job2 = createTestJob('cond-job-2', 'Conditional Job 2');
+
+    // 2. Create success-based dependency
+    $successDep = JobDependency::success('cond-job-2', 'cond-job-1');
+    $this->dependencyManager->addDependency($successDep);
+
+    // 3. Test that job2 is not ready when job1 failed
+    $failureMetrics = new JobMetrics(
+        jobId: 'cond-job-1',
+        queueName: 'default',
+        status: 'failed',
+        attempts: 3,
+        maxAttempts: 3,
+        executionTimeMs: 100.0,
+        memoryUsageBytes: 1024,
+        errorMessage: 'Test failure',
+        createdAt: date('Y-m-d H:i:s'),
+        startedAt: date('Y-m-d H:i:s'),
+        completedAt: null,
+        failedAt: date('Y-m-d H:i:s'),
+        metadata: []
+    );
+
+    $this->metricsManager->recordJobMetrics($failureMetrics);
+
+    // 4. Check that dependent job is not ready
+    $readyJobs = $this->resolutionEngine->getJobsReadyForExecution();
+    expect($readyJobs)->not()->toContain('cond-job-2');
+});
+
+test('queue metrics calculation', function () {
+    // 1. Create multiple job metrics
+    $metrics = [
+        new JobMetrics(
+            jobId: 'metric-job-1',
+            queueName: 'metrics-queue',
+            status: 'completed',
+            attempts: 1,
+            maxAttempts: 3,
+            executionTimeMs: 100.0,
+            memoryUsageBytes: 1024 * 1024,
+            errorMessage: null,
+            createdAt: date('Y-m-d H:i:s'),
+            startedAt: date('Y-m-d H:i:s'),
+            completedAt: date('Y-m-d H:i:s'),
+            failedAt: null,
+            metadata: []
+        ),
+        new JobMetrics(
+            jobId: 'metric-job-2',
+            queueName: 'metrics-queue',
+            status: 'completed',
+            attempts: 1,
+            maxAttempts: 3,
+            executionTimeMs: 200.0,
+            memoryUsageBytes: 2 * 1024 * 1024,
+            errorMessage: null,
+            createdAt: date('Y-m-d H:i:s'),
+            startedAt: date('Y-m-d H:i:s'),
+            completedAt: date('Y-m-d H:i:s'),
+            failedAt: null,
+            metadata: []
+        ),
+        new JobMetrics(
+            jobId: 'metric-job-3',
+            queueName: 'metrics-queue',
+            status: 'failed',
+            attempts: 3,
+            maxAttempts: 3,
+            executionTimeMs: 50.0,
+            memoryUsageBytes: 512 * 1024,
+            errorMessage: 'Test failure',
+            createdAt: date('Y-m-d H:i:s'),
+            startedAt: date('Y-m-d H:i:s'),
+            completedAt: null,
+            failedAt: date('Y-m-d H:i:s'),
+            metadata: []
+        )
+    ];
+
+    // 2. Record all metrics
+    foreach ($metrics as $metric) {
+        $this->metricsManager->recordJobMetrics($metric);
+    }
+
+    // 3. Calculate queue metrics
+    $queueMetrics = $this->metricsManager->getQueueMetrics('metrics-queue', '1 hour');
+
+    // 4. Verify calculations
+    expect($queueMetrics->queueName)->toBe('metrics-queue')
+        ->and($queueMetrics->totalJobs)->toBe(3)
+        ->and($queueMetrics->completedJobs)->toBe(2)
+        ->and($queueMetrics->failedJobs)->toBe(1)
+        ->and($queueMetrics->successRate->toFloat())->toBe(66.67);
+});
+
+test('dead letter queue functionality', function () {
+    // 1. Create a job that exceeds max attempts
+    $deadLetterMetrics = new JobMetrics(
+        jobId: 'dead-letter-job',
+        queueName: 'default',
+        status: 'failed',
+        attempts: 3,
+        maxAttempts: 3,
+        executionTimeMs: 25.0,
+        memoryUsageBytes: 256 * 1024,
+        errorMessage: 'Max attempts exceeded',
+        createdAt: date('Y-m-d H:i:s'),
+        startedAt: date('Y-m-d H:i:s'),
+        completedAt: null,
+        failedAt: date('Y-m-d H:i:s'),
+        metadata: ['dead_letter' => true]
+    );
+
+    // 2. Record metrics
+    $this->metricsManager->recordJobMetrics($deadLetterMetrics);
+
+    // 3. Verify dead letter detection
+    $failedJobs = $this->metricsManager->getFailedJobs('default', '1 hour');
+    $deadLetterJob = array_filter($failedJobs, fn($job) => $job->jobId === 'dead-letter-job')[0] ?? null;
+
+    expect($deadLetterJob)->not()->toBeNull()
+        ->and($deadLetterJob->attempts)->toBe(3)
+        ->and($deadLetterJob->maxAttempts)->toBe(3)
+        ->and($deadLetterJob->status)->toBe('failed');
+});
+
+test('system health monitoring', function () {
+    // 1. Create mixed job metrics for health calculation
+    $healthMetrics = [
+        // Healthy jobs
+        new JobMetrics('health-1', 'health-queue', 'completed', 1, 3, 50.0, 1024, null, date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), null, []),
+        new JobMetrics('health-2', 'health-queue', 'completed', 1, 3, 75.0, 1024, null, date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), null, []),
+        new JobMetrics('health-3', 'health-queue', 'completed', 1, 3, 100.0, 1024, null, date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), null, []),
+        // One failed job
+        new JobMetrics('health-4', 'health-queue', 'failed', 2, 3, 25.0, 1024, 'Health test failure', date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), null, date('Y-m-d H:i:s'), [])
+    ];
+
+    // 2. Record all metrics
+    foreach ($healthMetrics as $metric) {
+        $this->metricsManager->recordJobMetrics($metric);
+    }
+
+    // 3. Get system overview
+    $overview = $this->metricsManager->getSystemOverview();
+
+    // 4. Verify system health calculation
+    expect($overview)->toHaveKey('system_health_score')
+        ->and($overview['total_jobs'])->toBeGreaterThan(0)
+        ->and($overview['overall_success_rate'])->toBeGreaterThan(0);
+});
+
+test('performance and throughput metrics', function () {
+    // 1. Create performance test metrics with varying execution times
+    $performanceMetrics = [
+        new JobMetrics('perf-1', 'perf-queue', 'completed', 1, 3, 50.0, 1024 * 1024, null, date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), null, []),
+        new JobMetrics('perf-2', 'perf-queue', 'completed', 1, 3, 150.0, 2 * 1024 * 1024, null, date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), null, []),
+        new JobMetrics('perf-3', 'perf-queue', 'completed', 1, 3, 300.0, 4 * 1024 * 1024, null, date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), date('Y-m-d H:i:s'), null, [])
+    ];
+
+    // 2. Record performance metrics
+    foreach ($performanceMetrics as $metric) {
+        $this->metricsManager->recordJobMetrics($metric);
+    }
+
+    // 3. Get performance statistics
+    $performanceStats = $this->metricsManager->getPerformanceStats('perf-queue', '1 hour');
+
+    // 4. Verify performance calculations
+    expect($performanceStats)->toHaveKey('average_execution_time_ms')
+        ->and($performanceStats['average_execution_time_ms'])->toBe(166.67)
+        ->and($performanceStats)->toHaveKey('average_memory_usage_mb')
+        ->and($performanceStats['total_jobs'])->toBe(3);
+
+    // 5. Get throughput statistics
+    $throughputStats = $this->metricsManager->getThroughputStats('perf-queue', '1 hour');
+
+    // 6. Verify throughput calculations
+    expect($throughputStats)->toHaveKey('total_completed')
+        ->and($throughputStats['total_completed'])->toBe(3)
+        ->and($throughputStats)->toHaveKey('average_throughput_per_hour');
+});

tests/Framework/Queue/Integration/DistributedProcessingScenarioTest.php

@@ -0,0 +1,583 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\Services\WorkerRegistry;
+use App\Framework\Queue\Services\DatabaseDistributedLock;
+use App\Framework\Queue\Services\JobDistributionService;
+use App\Framework\Queue\Services\WorkerHealthCheckService;
+use App\Framework\Queue\Services\FailoverRecoveryService;
+use App\Framework\Queue\Entities\Worker;
+use App\Framework\Queue\ValueObjects\WorkerId;
+use App\Framework\Queue\ValueObjects\JobId;
+use App\Framework\Queue\ValueObjects\LockKey;
+use App\Framework\Queue\ValueObjects\QueueName;
+use App\Framework\Core\ValueObjects\Percentage;
+use App\Framework\Core\ValueObjects\Byte;
+use App\Framework\Core\ValueObjects\Duration;
+use App\Framework\Database\ConnectionInterface;
+use App\Framework\Logging\Logger;
+
+/**
+ * Real-world scenario tests for the Distributed Processing System
+ * These tests simulate complex real-world scenarios to validate system behavior
+ */
+describe('Distributed Processing Real-World Scenarios', function () {
+    beforeEach(function () {
+        // Mock connection and logger
+        $this->connection = mock(ConnectionInterface::class);
+        $this->logger = mock(Logger::class);
+
+        // Setup services
+        $this->workerRegistry = new WorkerRegistry($this->connection, $this->logger);
+        $this->distributedLock = new DatabaseDistributedLock($this->connection, $this->logger);
+        $this->jobDistribution = new JobDistributionService(
+            $this->workerRegistry,
+            $this->distributedLock,
+            $this->connection,
+            $this->logger
+        );
+
+        // Mock default logger behavior
+        $this->logger->shouldReceive('info')->andReturn(null);
+        $this->logger->shouldReceive('debug')->andReturn(null);
+        $this->logger->shouldReceive('warning')->andReturn(null);
+        $this->logger->shouldReceive('error')->andReturn(null);
+    });
+
+    describe('E-commerce Order Processing Scenario', function () {
+        it('handles peak shopping season with multiple worker types', function () {
+            // Scenario: Black Friday traffic with specialized workers
+
+            // Create specialized workers for different tasks
+            $emailWorkers = [
+                Worker::register(
+                    hostname: 'email-server-1',
+                    processId: 2001,
+                    queues: [QueueName::emailQueue()],
+                    maxJobs: 20,
+                    capabilities: ['email', 'newsletter', 'notifications']
+                ),
+                Worker::register(
+                    hostname: 'email-server-2',
+                    processId: 2002,
+                    queues: [QueueName::emailQueue()],
+                    maxJobs: 20,
+                    capabilities: ['email', 'newsletter', 'notifications']
+                )
+            ];
+
+            $imageWorkers = [
+                Worker::register(
+                    hostname: 'image-server-1',
+                    processId: 3001,
+                    queues: [QueueName::fromString('image-processing')],
+                    maxJobs: 5, // Resource intensive
+                    capabilities: ['image-resize', 'thumbnail', 'watermark']
+                )
+            ];
+
+            $generalWorkers = [
+                Worker::register(
+                    hostname: 'app-server-1',
+                    processId: 1001,
+                    queues: [
+                        QueueName::defaultQueue(),
+                        QueueName::fromString('reports')
+                    ],
+                    maxJobs: 15,
+                    capabilities: ['pdf-generation', 'reporting', 'exports']
+                ),
+                Worker::register(
+                    hostname: 'app-server-2',
+                    processId: 1002,
+                    queues: [
+                        QueueName::defaultQueue(),
+                        QueueName::fromString('reports')
+                    ],
+                    maxJobs: 15,
+                    capabilities: ['pdf-generation', 'reporting', 'exports']
+                )
+            ];
+
+            $allWorkers = array_merge($emailWorkers, $imageWorkers, $generalWorkers);
+
+            // Mock worker registration
+            foreach ($allWorkers as $worker) {
+                $stmt = mock(\PDOStatement::class);
+                $stmt->shouldReceive('execute')->andReturn(true);
+                $this->connection->shouldReceive('prepare')->andReturn($stmt);
+
+                $this->workerRegistry->register($worker);
+            }
+
+            // Simulate different job types being distributed
+            $jobs = [
+                // Email jobs (high volume, low resource)
+                ['id' => JobId::generate(), 'queue' => QueueName::emailQueue(), 'type' => 'order-confirmation'],
+                ['id' => JobId::generate(), 'queue' => QueueName::emailQueue(), 'type' => 'shipping-notification'],
+                ['id' => JobId::generate(), 'queue' => QueueName::emailQueue(), 'type' => 'newsletter'],
+
+                // Image processing jobs (low volume, high resource)
+                ['id' => JobId::generate(), 'queue' => QueueName::fromString('image-processing'), 'type' => 'product-thumbnails'],
+
+                // General processing jobs
+                ['id' => JobId::generate(), 'queue' => QueueName::defaultQueue(), 'type' => 'invoice-generation'],
+                ['id' => JobId::generate(), 'queue' => QueueName::fromString('reports'), 'type' => 'sales-report']
+            ];
+
+            // Mock job distribution
+            foreach ($jobs as $job) {
+                // Mock finding workers for queue
+                $workerStmt = mock(\PDOStatement::class);
+                $workerStmt->shouldReceive('execute')->andReturn(true);
+                $workerStmt->shouldReceive('fetch')->andReturn(false); // Simplified for test
+
+                // Mock lock operations
+                $lockStmt = mock(\PDOStatement::class);
+                $lockStmt->shouldReceive('execute')->andReturn(true);
+                $lockStmt->shouldReceive('rowCount')->andReturn(1);
+
+                $this->connection->shouldReceive('prepare')->andReturn($workerStmt, $lockStmt);
+
+                $assignedWorker = $this->jobDistribution->findBestWorkerForJob($job['queue']);
+                // In real scenario, would validate worker assignment logic
+            }
+
+            // Verify system can handle the load
+            expect(count($allWorkers))->toBe(5);
+            expect(count($jobs))->toBe(6);
+        });
+
+        it('handles worker failure during peak traffic gracefully', function () {
+            // Scenario: Worker crashes during high load, jobs need redistribution
+
+            $healthyWorker = Worker::register(
+                hostname: 'stable-server',
+                processId: 1001,
+                queues: [QueueName::defaultQueue()],
+                maxJobs: 10,
+                capabilities: ['email', 'pdf-generation']
+            );
+
+            $failingWorker = Worker::register(
+                hostname: 'failing-server',
+                processId: 1002,
+                queues: [QueueName::defaultQueue()],
+                maxJobs: 10,
+                capabilities: ['email', 'pdf-generation']
+            );
+
+            // Simulate worker failure (stale heartbeat, high resource usage)
+            $failedWorker = new Worker(
+                id: $failingWorker->id,
+                hostname: $failingWorker->hostname,
+                processId: $failingWorker->processId,
+                queues: $failingWorker->queues,
+                maxJobs: $failingWorker->maxJobs,
+                registeredAt: $failingWorker->registeredAt,
+                lastHeartbeat: new \DateTimeImmutable('-10 minutes'), // Stale
+                isActive: false, // Marked as failed
+                cpuUsage: new Percentage(99), // Critical
+                memoryUsage: Byte::fromGigabytes(4), // Over limit
+                currentJobs: 5
+            );
+
+            // Verify failure detection
+            expect($failedWorker->isHealthy())->toBeFalse();
+            expect($failedWorker->isAvailableForJobs())->toBeFalse();
+
+            // Verify healthy worker is still available
+            expect($healthyWorker->isHealthy())->toBeTrue();
+            expect($healthyWorker->isAvailableForJobs())->toBeTrue();
+
+            // Mock job redistribution
+            $stmt = mock(\PDOStatement::class);
+            $stmt->shouldReceive('execute')->andReturn(true);
+            $stmt->shouldReceive('rowCount')->andReturn(3); // 3 jobs released
+
+            $this->connection->shouldReceive('prepare')->andReturn($stmt);
+
+            $releasedJobs = $this->jobDistribution->releaseAllWorkerJobs($failedWorker->id);
+            expect($releasedJobs)->toBe(3);
+        });
+    });
+
+    describe('Media Processing Pipeline Scenario', function () {
+        it('handles resource-intensive media processing with proper load balancing', function () {
+            // Scenario: Video streaming service processing uploads
+
+            // GPU-enabled workers for video processing
+            $videoWorkers = [
+                Worker::register(
+                    hostname: 'gpu-server-1',
+                    processId: 4001,
+                    queues: [QueueName::fromString('video-processing')],
+                    maxJobs: 2, // Very resource intensive
+                    capabilities: ['video-encode', 'gpu-acceleration', 'h264', 'h265']
+                ),
+                Worker::register(
+                    hostname: 'gpu-server-2',
+                    processId: 4002,
+                    queues: [QueueName::fromString('video-processing')],
+                    maxJobs: 2,
+                    capabilities: ['video-encode', 'gpu-acceleration', 'h264', 'h265']
+                )
+            ];
+
+            // CPU workers for audio processing
+            $audioWorkers = [
+                Worker::register(
+                    hostname: 'audio-server-1',
+                    processId: 5001,
+                    queues: [QueueName::fromString('audio-processing')],
+                    maxJobs: 8,
+                    capabilities: ['audio-encode', 'mp3', 'aac', 'flac']
+                )
+            ];
+
+            // Thumbnail generation workers
+            $thumbnailWorkers = [
+                Worker::register(
+                    hostname: 'image-server-1',
+                    processId: 6001,
+                    queues: [QueueName::fromString('thumbnail-generation')],
+                    maxJobs: 10,
+                    capabilities: ['image-resize', 'ffmpeg', 'thumbnail']
+                ),
+                Worker::register(
+                    hostname: 'image-server-2',
+                    processId: 6002,
+                    queues: [QueueName::fromString('thumbnail-generation')],
+                    maxJobs: 10,
+                    capabilities: ['image-resize', 'ffmpeg', 'thumbnail']
+                )
+            ];
+
+            $allWorkers = array_merge($videoWorkers, $audioWorkers, $thumbnailWorkers);
+
+            // Simulate different resource usage patterns
+            $videoWorkerUnderLoad = $videoWorkers[0]->updateHeartbeat(
+                new Percentage(85), // High CPU for video encoding
+                Byte::fromGigabytes(3), // High memory usage
+                2 // At capacity
+            );
+
+            $audioWorkerLightLoad = $audioWorkers[0]->updateHeartbeat(
+                new Percentage(30), // Moderate CPU
+                Byte::fromMegabytes(800),
+                3 // 3/8 jobs
+            );
+
+            $thumbnailWorkerIdle = $thumbnailWorkers[0]->updateHeartbeat(
+                new Percentage(5), // Very low CPU
+                Byte::fromMegabytes(200),
+                0 // No current jobs
+            );
+
+            // Verify load distribution logic
+            expect($videoWorkerUnderLoad->isAvailableForJobs())->toBeFalse(); // At capacity
+            expect($audioWorkerLightLoad->isAvailableForJobs())->toBeTrue();
+            expect($thumbnailWorkerIdle->isAvailableForJobs())->toBeTrue();
+
+            // Check load percentages
+            expect($videoWorkerUnderLoad->getLoadPercentage()->getValue())->toBe(100.0); // 2/2 jobs = 100%
+            expect($audioWorkerLightLoad->getLoadPercentage()->getValue())->toBe(37.5); // 3/8 = 37.5%
+            expect($thumbnailWorkerIdle->getLoadPercentage()->getValue())->toBe(5.0); // CPU load only
+
+            expect(count($allWorkers))->toBe(5);
+        });
+
+        it('prevents resource exhaustion through proper capability matching', function () {
+            // Worker without GPU capabilities trying to handle video processing
+            $cpuOnlyWorker = Worker::register(
+                hostname: 'cpu-server',
+                processId: 7001,
+                queues: [QueueName::fromString('video-processing')],
+                maxJobs: 10,
+                capabilities: ['cpu-encoding'] // Missing GPU capability
+            );
+
+            $gpuWorker = Worker::register(
+                hostname: 'gpu-server',
+                processId: 7002,
+                queues: [QueueName::fromString('video-processing')],
+                maxJobs: 2,
+                capabilities: ['gpu-acceleration', 'video-encode', 'h264']
+            );
+
+            // Job requiring GPU acceleration
+            $jobData = [
+                'required_capabilities' => ['gpu-acceleration', 'h264'],
+                'resource_requirements' => [
+                    'gpu_memory' => '4GB',
+                    'encoding_quality' => 'high'
+                ]
+            ];
+
+            // Mock worker scoring (would normally be done by JobDistributionService)
+            // CPU-only worker should get score 0 (missing required capability)
+            expect($cpuOnlyWorker->hasCapability('gpu-acceleration'))->toBeFalse();
+            expect($gpuWorker->hasCapability('gpu-acceleration'))->toBeTrue();
+            expect($gpuWorker->hasCapability('h264'))->toBeTrue();
+        });
+    });
+
+    describe('Financial Transaction Processing Scenario', function () {
+        it('ensures transaction consistency with distributed locking', function () {
+            // Scenario: Banking system processing concurrent transactions
+
+            $transactionWorkers = [
+                Worker::register(
+                    hostname: 'transaction-server-1',
+                    processId: 8001,
+                    queues: [QueueName::fromString('transactions')],
+                    maxJobs: 50, // High throughput for financial data
+                    capabilities: ['payment-processing', 'fraud-detection', 'pci-compliant']
+                ),
+                Worker::register(
+                    hostname: 'transaction-server-2',
+                    processId: 8002,
+                    queues: [QueueName::fromString('transactions')],
+                    maxJobs: 50,
+                    capabilities: ['payment-processing', 'fraud-detection', 'pci-compliant']
+                )
+            ];
+
+            // Simulate concurrent transaction processing
+            $accountId = 'account-12345';
+            $transactionLock = LockKey::forResource('account', $accountId);
+
+            // Mock lock acquisition for account processing
+            $lockStmt = mock(\PDOStatement::class);
+            $lockStmt->shouldReceive('execute')->andReturn(true);
+            $lockStmt->shouldReceive('rowCount')->andReturn(1);
+
+            $failLockStmt = mock(\PDOStatement::class);
+            $failLockStmt->shouldReceive('execute')->andThrow(
+                new \PDOException('Duplicate entry for key PRIMARY')
+            );
+
+            $this->connection->shouldReceive('prepare')->andReturn(
+                $lockStmt,    // First worker gets lock
+                $failLockStmt // Second worker fails
+            );
+
+            // First worker should acquire lock successfully
+            $worker1 = $transactionWorkers[0];
+            $worker2 = $transactionWorkers[1];
+
+            $firstLockResult = $this->distributedLock->acquire(
+                $transactionLock,
+                $worker1->id,
+                Duration::fromMinutes(5)
+            );
+
+            $secondLockResult = $this->distributedLock->acquire(
+                $transactionLock,
+                $worker2->id,
+                Duration::fromMinutes(5)
+            );
+
+            expect($firstLockResult)->toBeTrue();
+            expect($secondLockResult)->toBeFalse(); // Should fail due to existing lock
+        });
+
+        it('handles high-frequency trading with minimal latency', function () {
+            // High-performance workers for trading operations
+            $tradingWorker = Worker::register(
+                hostname: 'trading-server-hft',
+                processId: 9001,
+                queues: [QueueName::fromString('high-frequency-trading')],
+                maxJobs: 1000, // Very high throughput
+                capabilities: ['ultra-low-latency', 'market-data', 'order-execution']
+            );
+
+            // Simulate high load but healthy performance
+            $performantWorker = $tradingWorker->updateHeartbeat(
+                new Percentage(60), // Moderate CPU despite high load
+                Byte::fromGigabytes(1.5), // Efficient memory usage
+                800 // High job count but within limits
+            );
+
+            expect($performantWorker->isHealthy())->toBeTrue();
+            expect($performantWorker->isAvailableForJobs())->toBeTrue(); // Still has capacity
+            expect($performantWorker->getLoadPercentage()->getValue())->toBe(80.0); // 800/1000 jobs
+        });
+    });
+
+    describe('Content Delivery Network Scenario', function () {
+        it('distributes cache warming jobs across geographic regions', function () {
+            // Workers in different geographic regions
+            $usEastWorkers = [
+                Worker::register(
+                    hostname: 'cdn-us-east-1',
+                    processId: 10001,
+                    queues: [QueueName::fromString('cache-warming')],
+                    maxJobs: 25,
+                    capabilities: ['cdn-management', 'us-east-region', 'edge-caching']
+                ),
+                Worker::register(
+                    hostname: 'cdn-us-east-2',
+                    processId: 10002,
+                    queues: [QueueName::fromString('cache-warming')],
+                    maxJobs: 25,
+                    capabilities: ['cdn-management', 'us-east-region', 'edge-caching']
+                )
+            ];
+
+            $europeWorkers = [
+                Worker::register(
+                    hostname: 'cdn-eu-west-1',
+                    processId: 11001,
+                    queues: [QueueName::fromString('cache-warming')],
+                    maxJobs: 20,
+                    capabilities: ['cdn-management', 'eu-west-region', 'edge-caching']
+                )
+            ];
+
+            $asiaWorkers = [
+                Worker::register(
+                    hostname: 'cdn-asia-pacific-1',
+                    processId: 12001,
+                    queues: [QueueName::fromString('cache-warming')],
+                    maxJobs: 15,
+                    capabilities: ['cdn-management', 'asia-pacific-region', 'edge-caching']
+                )
+            ];
+
+            $allCdnWorkers = array_merge($usEastWorkers, $europeWorkers, $asiaWorkers);
+
+            // Verify regional distribution
+            $usEastCount = count(array_filter($allCdnWorkers,
+                fn($w) => $w->hasCapability('us-east-region')));
+            $europeCount = count(array_filter($allCdnWorkers,
+                fn($w) => $w->hasCapability('eu-west-region')));
+            $asiaCount = count(array_filter($allCdnWorkers,
+                fn($w) => $w->hasCapability('asia-pacific-region')));
+
+            expect($usEastCount)->toBe(2);
+            expect($europeCount)->toBe(1);
+            expect($asiaCount)->toBe(1);
+
+            // Verify all workers can handle cache warming
+            foreach ($allCdnWorkers as $worker) {
+                expect($worker->hasCapability('cdn-management'))->toBeTrue();
+                expect($worker->hasCapability('edge-caching'))->toBeTrue();
+            }
+        });
+
+        it('handles regional worker failure with graceful degradation', function () {
+            // Scenario: Entire region goes offline, traffic redistributed
+
+            $primaryWorker = Worker::register(
+                hostname: 'cdn-primary',
+                processId: 13001,
+                queues: [QueueName::fromString('content-delivery')],
+                maxJobs: 100,
+                capabilities: ['primary-region', 'high-capacity']
+            );
+
+            $backupWorkers = [
+                Worker::register(
+                    hostname: 'cdn-backup-1',
+                    processId: 13002,
+                    queues: [QueueName::fromString('content-delivery')],
+                    maxJobs: 50,
+                    capabilities: ['backup-region', 'medium-capacity']
+                ),
+                Worker::register(
+                    hostname: 'cdn-backup-2',
+                    processId: 13003,
+                    queues: [QueueName::fromString('content-delivery')],
+                    maxJobs: 50,
+                    capabilities: ['backup-region', 'medium-capacity']
+                )
+            ];
+
+            // Simulate primary region failure
+            $failedPrimary = $primaryWorker->markInactive();
+            expect($failedPrimary->isAvailableForJobs())->toBeFalse();
+
+            // Backup workers should still be available
+            foreach ($backupWorkers as $backup) {
+                expect($backup->isAvailableForJobs())->toBeTrue();
+            }
+
+            // Total backup capacity should handle reduced load
+            $totalBackupCapacity = array_sum(array_map(fn($w) => $w->maxJobs, $backupWorkers));
+            expect($totalBackupCapacity)->toBe(100); // Same as primary capacity
+        });
+    });
+
+    describe('Machine Learning Training Pipeline Scenario', function () {
+        it('manages resource-intensive ML training jobs efficiently', function () {
+            // Specialized workers for different ML tasks
+            $gpuTrainingWorker = Worker::register(
+                hostname: 'ml-gpu-cluster-1',
+                processId: 14001,
+                queues: [QueueName::fromString('ml-training')],
+                maxJobs: 1, // One intensive job at a time
+                capabilities: ['gpu-cluster', 'tensorflow', 'pytorch', 'cuda']
+            );
+
+            $dataPreprocessingWorkers = [
+                Worker::register(
+                    hostname: 'ml-preprocessing-1',
+                    processId: 14002,
+                    queues: [QueueName::fromString('data-preprocessing')],
+                    maxJobs: 10,
+                    capabilities: ['data-cleaning', 'feature-engineering', 'pandas', 'numpy']
+                ),
+                Worker::register(
+                    hostname: 'ml-preprocessing-2',
+                    processId: 14003,
+                    queues: [QueueName::fromString('data-preprocessing')],
+                    maxJobs: 10,
+                    capabilities: ['data-cleaning', 'feature-engineering', 'pandas', 'numpy']
+                )
+            ];
+
+            $inferenceWorkers = [
+                Worker::register(
+                    hostname: 'ml-inference-1',
+                    processId: 14004,
+                    queues: [QueueName::fromString('ml-inference')],
+                    maxJobs: 50, // High throughput for inference
+                    capabilities: ['model-serving', 'tensorflow-lite', 'onnx']
+                )
+            ];
+
+            // Simulate GPU worker under heavy load
+            $trainingWorkerLoaded = $gpuTrainingWorker->updateHeartbeat(
+                new Percentage(95), // High GPU utilization
+                Byte::fromGigabytes(15), // High memory for large models
+                1 // At capacity
+            );
+
+            // Preprocessing workers with moderate load
+            $preprocessingWorkerActive = $dataPreprocessingWorkers[0]->updateHeartbeat(
+                new Percentage(70), // Active data processing
+                Byte::fromGigabytes(4),
+                6 // 6/10 jobs
+            );
+
+            // Inference worker with light load
+            $inferenceWorkerIdle = $inferenceWorkers[0]->updateHeartbeat(
+                new Percentage(20), // Low CPU for inference
+                Byte::fromMegabytes(800),
+                5 // 5/50 jobs
+            );
+
+            // Verify resource allocation patterns
+            expect($trainingWorkerLoaded->isAvailableForJobs())->toBeFalse(); // At capacity
+            expect($preprocessingWorkerActive->isAvailableForJobs())->toBeTrue();
+            expect($inferenceWorkerIdle->isAvailableForJobs())->toBeTrue();
+
+            // Check load patterns match expected ML workloads
+            expect($trainingWorkerLoaded->getLoadPercentage()->getValue())->toBe(100.0); // At capacity
+            expect($preprocessingWorkerActive->getLoadPercentage()->getValue())->toBe(70.0); // CPU bound
+            expect($inferenceWorkerIdle->getLoadPercentage()->getValue())->toBe(20.0); // Light load
+        });
+    });
+});

tests/Framework/Queue/Integration/DistributedProcessingTest.php

@@ -0,0 +1,820 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\Services\WorkerRegistry;
+use App\Framework\Queue\Services\DatabaseDistributedLock;
+use App\Framework\Queue\Services\JobDistributionService;
+use App\Framework\Queue\Services\WorkerHealthCheckService;
+use App\Framework\Queue\Services\FailoverRecoveryService;
+use App\Framework\Queue\Entities\Worker;
+use App\Framework\Queue\ValueObjects\WorkerId;
+use App\Framework\Queue\ValueObjects\JobId;
+use App\Framework\Queue\ValueObjects\LockKey;
+use App\Framework\Queue\ValueObjects\QueueName;
+use App\Framework\Core\ValueObjects\Percentage;
+use App\Framework\Core\ValueObjects\Byte;
+use App\Framework\Core\ValueObjects\Duration;
+use App\Framework\Database\ConnectionInterface;
+use App\Framework\Logging\Logger;
+
+/**
+ * Comprehensive integration tests for the Distributed Processing System
+ */
+describe('Distributed Processing System', function () {
+    beforeEach(function () {
+        // Mock connection for database operations
+        $this->connection = mock(ConnectionInterface::class);
+        $this->logger = mock(Logger::class);
+
+        // Create services
+        $this->workerRegistry = new WorkerRegistry($this->connection, $this->logger);
+        $this->distributedLock = new DatabaseDistributedLock($this->connection, $this->logger);
+        $this->jobDistribution = new JobDistributionService(
+            $this->workerRegistry,
+            $this->distributedLock,
+            $this->connection,
+            $this->logger
+        );
+        $this->healthCheck = new WorkerHealthCheckService(
+            $this->workerRegistry,
+            $this->connection,
+            $this->logger
+        );
+        $this->failoverRecovery = new FailoverRecoveryService(
+            $this->workerRegistry,
+            $this->jobDistribution,
+            $this->healthCheck,
+            $this->distributedLock,
+            $this->connection,
+            $this->logger
+        );
+
+        // Create test workers
+        $this->worker1 = Worker::register(
+            hostname: 'app-server-1',
+            processId: 1001,
+            queues: [
+                QueueName::emailQueue(),
+                QueueName::defaultQueue()
+            ],
+            maxJobs: 10,
+            capabilities: ['email', 'pdf-generation']
+        );
+
+        $this->worker2 = Worker::register(
+            hostname: 'app-server-2',
+            processId: 1002,
+            queues: [
+                QueueName::defaultQueue(),
+                QueueName::fromString('high-priority')
+            ],
+            maxJobs: 5,
+            capabilities: ['image-processing', 'pdf-generation']
+        );
+
+        $this->worker3 = Worker::register(
+            hostname: 'app-server-3',
+            processId: 1003,
+            queues: [
+                QueueName::emailQueue()
+            ],
+            maxJobs: 15,
+            capabilities: ['email', 'notifications']
+        );
+
+        // Test job IDs
+        $this->jobId1 = JobId::generate();
+        $this->jobId2 = JobId::generate();
+        $this->jobId3 = JobId::generate();
+    });
+
+    describe('Worker Registration and Discovery', function () {
+        it('can register multiple workers across different queues', function () {
+            // Mock successful database operations for worker registration
+            $this->connection->shouldReceive('prepare')->andReturnSelf();
+            $this->connection->shouldReceive('execute')->andReturn(true);
+            $this->logger->shouldReceive('info')->andReturn(null);
+            $this->logger->shouldReceive('debug')->andReturn(null);
+
+            // Register workers
+            $this->workerRegistry->register($this->worker1);
+            $this->workerRegistry->register($this->worker2);
+            $this->workerRegistry->register($this->worker3);
+
+            // Verify registration calls were made
+            expect($this->connection)->toHaveReceived('prepare')->times(3);
+            expect($this->connection)->toHaveReceived('execute')->times(3);
+        });
+
+        it('can find workers for specific queues', function () {
+            // Mock database query for finding workers by queue
+            $stmt = mock(\PDOStatement::class);
+            $stmt->shouldReceive('execute')->andReturn(true);
+            $stmt->shouldReceive('fetch')->andReturn(
+                $this->worker1->toArray(),
+                $this->worker3->toArray(),
+                false // End of results
+            );
+
+            $this->connection->shouldReceive('prepare')->andReturn($stmt);
+            $this->logger->shouldReceive('error')->never();
+
+            $workers = $this->workerRegistry->findWorkersForQueue(QueueName::emailQueue());
+
+            expect($workers)->toHaveCount(2);
+            expect($workers[0]->hostname)->toBe('app-server-1');
+            expect($workers[1]->hostname)->toBe('app-server-3');
+        });
+
+        it('can find best available worker with load balancing', function () {
+            // Create workers with different load levels
+            $lightlyLoadedWorker = $this->worker1->updateHeartbeat(
+                new Percentage(20), // Low CPU
+                Byte::fromMegabytes(512), // Low memory
+                2 // 2 out of 10 jobs
+            );
+
+            $heavilyLoadedWorker = $this->worker2->updateHeartbeat(
+                new Percentage(80), // High CPU
+                Byte::fromMegabytes(1500), // High memory
+                4 // 4 out of 5 jobs = 80% load
+            );
+
+            // Mock database to return workers with different loads
+            $stmt = mock(\PDOStatement::class);
+            $stmt->shouldReceive('execute')->andReturn(true);
+            $stmt->shouldReceive('fetch')->andReturn(
+                $lightlyLoadedWorker->toArray(),
+                $heavilyLoadedWorker->toArray(),
+                false
+            );
+
+            $this->connection->shouldReceive('prepare')->andReturn($stmt);
+            $this->logger->shouldReceive('error')->never();
+
+            $bestWorker = $this->workerRegistry->findBestWorkerForQueue(QueueName::defaultQueue());
+
+            expect($bestWorker)->not->toBeNull();
+            expect($bestWorker->hostname)->toBe('app-server-1'); // Should pick lightly loaded worker
+        });
+
+        it('correctly calculates worker load percentages', function () {
+            $worker = $this->worker1->updateHeartbeat(
+                new Percentage(30), // 30% CPU
+                Byte::fromMegabytes(800),
+                3 // 3 out of 10 jobs = 30% job load
+            );
+
+            $loadPercentage = $worker->getLoadPercentage();
+
+            // Should take the higher of CPU load (30%) or job load (30%)
+            expect($loadPercentage->getValue())->toBe(30.0);
+
+            // Test with higher CPU load
+            $workerHighCpu = $worker->updateHeartbeat(
+                new Percentage(75), // 75% CPU
+                Byte::fromMegabytes(800),
+                3 // Still 30% job load
+            );
+
+            expect($workerHighCpu->getLoadPercentage()->getValue())->toBe(75.0);
+        });
+    });
+
+    describe('Distributed Locking System', function () {
+        it('prevents race conditions when acquiring job locks', function () {
+            $lockKey = LockKey::forJob($this->jobId1);
+            $workerId1 = WorkerId::generate();
+            $workerId2 = WorkerId::generate();
+            $ttl = Duration::fromMinutes(5);
+
+            // Mock first worker successfully acquiring lock
+            $stmt1 = mock(\PDOStatement::class);
+            $stmt1->shouldReceive('execute')->andReturn(true);
+            $stmt1->shouldReceive('rowCount')->andReturn(1); // Successful insert
+
+            // Mock second worker failing to acquire same lock (duplicate key)
+            $stmt2 = mock(\PDOStatement::class);
+            $stmt2->shouldReceive('execute')->andThrow(
+                new \PDOException('Duplicate entry for key PRIMARY')
+            );
+
+            $this->connection->shouldReceive('prepare')
+                ->andReturn($stmt1, $stmt2);
+
+            $this->logger->shouldReceive('debug')->andReturn(null);
+            $this->logger->shouldReceive('info')->andReturn(null);
+
+            // First worker should successfully acquire lock
+            $result1 = $this->distributedLock->acquire($lockKey, $workerId1, $ttl);
+            expect($result1)->toBeTrue();
+
+            // Second worker should fail to acquire same lock
+            $result2 = $this->distributedLock->acquire($lockKey, $workerId2, $ttl);
+            expect($result2)->toBeFalse();
+        });
+
+        it('can extend lock duration for active workers', function () {
+            $lockKey = LockKey::forJob($this->jobId1);
+            $workerId = WorkerId::generate();
+            $extension = Duration::fromMinutes(10);
+
+            // Mock successful lock extension
+            $stmt = mock(\PDOStatement::class);
+            $stmt->shouldReceive('execute')->andReturn(true);
+            $stmt->shouldReceive('rowCount')->andReturn(1); // Lock was extended
+
+            $this->connection->shouldReceive('prepare')->andReturn($stmt);
+            $this->logger->shouldReceive('debug')->andReturn(null);
+
+            $result = $this->distributedLock->extend($lockKey, $workerId, $extension);
+
+            expect($result)->toBeTrue();
+        });
+
+        it('can release locks and clean up resources', function () {
+            $lockKey = LockKey::forJob($this->jobId1);
+            $workerId = WorkerId::generate();
+
+            // Mock successful lock release
+            $stmt = mock(\PDOStatement::class);
+            $stmt->shouldReceive('execute')->andReturn(true);
+            $stmt->shouldReceive('rowCount')->andReturn(1); // Lock was deleted
+
+            $this->connection->shouldReceive('prepare')->andReturn($stmt);
+            $this->logger->shouldReceive('debug')->andReturn(null);
+            $this->logger->shouldReceive('info')->andReturn(null);
+
+            $result = $this->distributedLock->release($lockKey, $workerId);
+
+            expect($result)->toBeTrue();
+        });
+
+        it('supports lock acquisition with timeout for competing workers', function () {
+            $lockKey = LockKey::forQueue(QueueName::defaultQueue());
+            $workerId = WorkerId::generate();
+            $ttl = Duration::fromMinutes(5);
+            $timeout = Duration::fromSeconds(2);
+
+            // Mock first attempt fails, second attempt succeeds
+            $stmt1 = mock(\PDOStatement::class);
+            $stmt1->shouldReceive('execute')->andThrow(
+                new \PDOException('Duplicate entry')
+            );
+
+            $stmt2 = mock(\PDOStatement::class);
+            $stmt2->shouldReceive('execute')->andReturn(true);
+            $stmt2->shouldReceive('rowCount')->andReturn(1);
+
+            $this->connection->shouldReceive('prepare')
+                ->andReturn($stmt1, $stmt2);
+
+            $this->logger->shouldReceive('debug')->andReturn(null);
+            $this->logger->shouldReceive('info')->andReturn(null);
+
+            $result = $this->distributedLock->acquireWithTimeout($lockKey, $workerId, $ttl, $timeout);
+
+            expect($result)->toBeTrue();
+        });
+    });
+
+    describe('Job Distribution Service', function () {
+        it('can distribute jobs to best available workers', function () {
+            // Mock distribution lock acquisition
+            $distributionStmt = mock(\PDOStatement::class);
+            $distributionStmt->shouldReceive('execute')->andReturn(true);
+            $distributionStmt->shouldReceive('rowCount')->andReturn(1);
+
+            // Mock job lock acquisition
+            $jobStmt = mock(\PDOStatement::class);
+            $jobStmt->shouldReceive('execute')->andReturn(true);
+            $jobStmt->shouldReceive('rowCount')->andReturn(1);
+
+            // Mock job assignment recording
+            $assignmentStmt = mock(\PDOStatement::class);
+            $assignmentStmt->shouldReceive('execute')->andReturn(true);
+
+            // Mock finding workers for queue
+            $workerStmt = mock(\PDOStatement::class);
+            $workerStmt->shouldReceive('execute')->andReturn(true);
+            $workerStmt->shouldReceive('fetch')->andReturn(
+                $this->worker1->toArray(),
+                false
+            );
+
+            $this->connection->shouldReceive('prepare')->andReturn(
+                $distributionStmt, // Distribution lock
+                $jobStmt,         // Job lock
+                $jobStmt,         // Job lock transfer (release old)
+                $jobStmt,         // Job lock transfer (acquire new)
+                $assignmentStmt,  // Job assignment
+                $jobStmt,         // Release distribution lock
+                $workerStmt       // Find workers
+            );
+
+            $this->logger->shouldReceive('info')->andReturn(null);
+            $this->logger->shouldReceive('debug')->andReturn(null);
+            $this->logger->shouldReceive('warning')->never();
+            $this->logger->shouldReceive('error')->never();
+
+            $assignedWorkerId = $this->jobDistribution->distributeJob(
+                $this->jobId1,
+                QueueName::defaultQueue(),
+                ['priority' => 'normal']
+            );
+
+            expect($assignedWorkerId)->not->toBeNull();
+            expect($assignedWorkerId->toString())->toBe($this->worker1->id->toString());
+        });
+
+        it('calculates worker scores based on load and capabilities', function () {
+            $jobData = [
+                'required_capabilities' => ['email', 'pdf-generation']
+            ];
+
+            $bestWorker = $this->jobDistribution->findBestWorkerForJob(
+                QueueName::emailQueue(),
+                $jobData
+            );
+
+            // Should return null when no workers are mocked in database
+            // In real scenario, would return worker with matching capabilities and lowest load
+            expect($bestWorker)->toBeNull();
+        });
+
+        it('handles job distribution when no workers are available', function () {
+            // Mock empty worker result set
+            $stmt = mock(\PDOStatement::class);
+            $stmt->shouldReceive('execute')->andReturn(true);
+            $stmt->shouldReceive('fetch')->andReturn(false); // No workers found
+
+            $this->connection->shouldReceive('prepare')->andReturn($stmt);
+            $this->logger->shouldReceive('warning')->andReturn(null);
+            $this->logger->shouldReceive('error')->never();
+
+            $result = $this->jobDistribution->findBestWorkerForJob(QueueName::defaultQueue());
+
+            expect($result)->toBeNull();
+        });
+
+        it('can release jobs from workers and cleanup assignments', function () {
+            // Mock successful job release
+            $lockStmt = mock(\PDOStatement::class);
+            $lockStmt->shouldReceive('execute')->andReturn(true);
+            $lockStmt->shouldReceive('rowCount')->andReturn(1);
+
+            // Mock assignment cleanup
+            $assignmentStmt = mock(\PDOStatement::class);
+            $assignmentStmt->shouldReceive('execute')->andReturn(true);
+
+            $this->connection->shouldReceive('prepare')->andReturn(
+                $lockStmt,        // Release job lock
+                $assignmentStmt   // Delete assignment
+            );
+
+            $this->logger->shouldReceive('info')->andReturn(null);
+            $this->logger->shouldReceive('debug')->andReturn(null);
+
+            $result = $this->jobDistribution->releaseJob($this->jobId1, $this->worker1->id);
+
+            expect($result)->toBeTrue();
+        });
+    });
+
+    describe('Worker Health Monitoring', function () {
+        it('detects unhealthy workers based on resource usage', function () {
+            // Create worker with critical resource usage
+            $unhealthyWorker = $this->worker1->updateHeartbeat(
+                new Percentage(95), // Critical CPU usage
+                Byte::fromGigabytes(2.5), // Exceeds memory limit
+                8 // High job count but within limits
+            );
+
+            expect($unhealthyWorker->isHealthy())->toBeFalse();
+            expect($unhealthyWorker->isAvailableForJobs())->toBeFalse();
+        });
+
+        it('detects workers with stale heartbeats', function () {
+            // Create worker with old heartbeat
+            $staleWorker = new Worker(
+                id: $this->worker1->id,
+                hostname: $this->worker1->hostname,
+                processId: $this->worker1->processId,
+                queues: $this->worker1->queues,
+                maxJobs: $this->worker1->maxJobs,
+                registeredAt: $this->worker1->registeredAt,
+                lastHeartbeat: new \DateTimeImmutable('-5 minutes'), // Stale heartbeat
+                isActive: true,
+                cpuUsage: new Percentage(30),
+                memoryUsage: Byte::fromMegabytes(512),
+                currentJobs: 2
+            );
+
+            expect($staleWorker->isHealthy())->toBeFalse();
+        });
+
+        it('identifies healthy workers correctly', function () {
+            $healthyWorker = $this->worker1->updateHeartbeat(
+                new Percentage(45), // Normal CPU usage
+                Byte::fromMegabytes(800), // Normal memory usage
+                3 // Normal job count
+            );
+
+            expect($healthyWorker->isHealthy())->toBeTrue();
+            expect($healthyWorker->isAvailableForJobs())->toBeTrue();
+        });
+
+        it('considers workers at capacity as unavailable but healthy', function () {
+            $atCapacityWorker = $this->worker2->updateHeartbeat(
+                new Percentage(50), // Normal CPU
+                Byte::fromMegabytes(600), // Normal memory
+                5 // At max capacity (5/5 jobs)
+            );
+
+            expect($atCapacityWorker->isHealthy())->toBeTrue();
+            expect($atCapacityWorker->isAvailableForJobs())->toBeFalse(); // At capacity
+        });
+    });
+
+    describe('Multi-Worker Load Distribution', function () {
+        it('distributes jobs across multiple workers evenly', function () {
+            $workers = [$this->worker1, $this->worker2, $this->worker3];
+            $jobs = [$this->jobId1, $this->jobId2, $this->jobId3];
+
+            // Mock successful distribution for all jobs
+            foreach ($jobs as $index => $jobId) {
+                // Each job gets distributed to a different worker
+                $stmt = mock(\PDOStatement::class);
+                $stmt->shouldReceive('execute')->andReturn(true);
+                $stmt->shouldReceive('rowCount')->andReturn(1);
+                $stmt->shouldReceive('fetch')->andReturn(
+                    $workers[$index]->toArray(),
+                    false
+                );
+
+                $this->connection->shouldReceive('prepare')->andReturn($stmt);
+            }
+
+            $this->logger->shouldReceive('info')->andReturn(null);
+            $this->logger->shouldReceive('debug')->andReturn(null);
+
+            $assignments = [];
+            foreach ($jobs as $jobId) {
+                $workerId = $this->jobDistribution->distributeJob(
+                    $jobId,
+                    QueueName::defaultQueue()
+                );
+
+                if ($workerId) {
+                    $assignments[] = $workerId->toString();
+                }
+            }
+
+            // Should have distributed jobs (exact distribution depends on mocking)
+            expect($assignments)->not->toBeEmpty();
+        });
+
+        it('handles worker overload by selecting alternative workers', function () {
+            // Create overloaded worker
+            $overloadedWorker = $this->worker1->updateHeartbeat(
+                new Percentage(95), // Critical CPU
+                Byte::fromGigabytes(2.5), // Over memory limit
+                10 // At max capacity
+            );
+
+            // Create available alternative worker
+            $availableWorker = $this->worker2->updateHeartbeat(
+                new Percentage(20), // Low CPU
+                Byte::fromMegabytes(400), // Low memory
+                1 // Low job count
+            );
+
+            // Verify overloaded worker is not available
+            expect($overloadedWorker->isAvailableForJobs())->toBeFalse();
+
+            // Verify alternative worker is available
+            expect($availableWorker->isAvailableForJobs())->toBeTrue();
+        });
+    });
+
+    describe('Automatic Failover and Recovery', function () {
+        it('detects failed workers and initiates recovery', function () {
+            // Create failed worker (old heartbeat, high resource usage)
+            $failedWorker = new Worker(
+                id: $this->worker1->id,
+                hostname: $this->worker1->hostname,
+                processId: $this->worker1->processId,
+                queues: $this->worker1->queues,
+                maxJobs: $this->worker1->maxJobs,
+                registeredAt: $this->worker1->registeredAt,
+                lastHeartbeat: new \DateTimeImmutable('-10 minutes'), // Very stale
+                isActive: true,
+                cpuUsage: new Percentage(99), // Critical CPU
+                memoryUsage: Byte::fromGigabytes(3), // Over limit
+                currentJobs: 5
+            );
+
+            expect($failedWorker->isHealthy())->toBeFalse();
+            expect($failedWorker->isAvailableForJobs())->toBeFalse();
+        });
+
+        it('can reassign jobs from failed workers to healthy workers', function () {
+            $failedWorkerId = WorkerId::generate();
+            $healthyWorkerId = WorkerId::generate();
+
+            // Mock job reassignment operations
+            $stmt = mock(\PDOStatement::class);
+            $stmt->shouldReceive('execute')->andReturn(true);
+            $stmt->shouldReceive('rowCount')->andReturn(2); // 2 jobs reassigned
+
+            $this->connection->shouldReceive('prepare')->andReturn($stmt);
+            $this->logger->shouldReceive('info')->andReturn(null);
+
+            $releasedJobs = $this->jobDistribution->releaseAllWorkerJobs($failedWorkerId);
+
+            expect($releasedJobs)->toBeGreaterThanOrEqual(0);
+        });
+
+        it('cleans up resources from inactive workers', function () {
+            // Mock worker cleanup operations
+            $stmt = mock(\PDOStatement::class);
+            $stmt->shouldReceive('execute')->andReturn(true);
+            $stmt->shouldReceive('rowCount')->andReturn(3); // 3 workers deactivated
+
+            $this->connection->shouldReceive('prepare')->andReturn($stmt);
+            $this->logger->shouldReceive('info')->andReturn(null);
+
+            $cleanedCount = $this->workerRegistry->cleanupInactiveWorkers(5);
+
+            expect($cleanedCount)->toBe(3);
+        });
+    });
+
+    describe('System Resilience and Stress Testing', function () {
+        it('handles concurrent job distribution requests', function () {
+            $concurrentJobs = [
+                JobId::generate(),
+                JobId::generate(),
+                JobId::generate(),
+                JobId::generate(),
+                JobId::generate()
+            ];
+
+            // Mock successful distribution for all concurrent jobs
+            foreach ($concurrentJobs as $jobId) {
+                $stmt = mock(\PDOStatement::class);
+                $stmt->shouldReceive('execute')->andReturn(true);
+                $stmt->shouldReceive('rowCount')->andReturn(1);
+                $stmt->shouldReceive('fetch')->andReturn(
+                    $this->worker1->toArray(),
+                    false
+                );
+
+                $this->connection->shouldReceive('prepare')->andReturn($stmt);
+            }
+
+            $this->logger->shouldReceive('info')->andReturn(null);
+            $this->logger->shouldReceive('debug')->andReturn(null);
+
+            $successfulDistributions = 0;
+            foreach ($concurrentJobs as $jobId) {
+                $workerId = $this->jobDistribution->distributeJob(
+                    $jobId,
+                    QueueName::defaultQueue()
+                );
+
+                if ($workerId) {
+                    $successfulDistributions++;
+                }
+            }
+
+            expect($successfulDistributions)->toBeGreaterThanOrEqual(0);
+        });
+
+        it('maintains system consistency during lock contention', function () {
+            $lockKey = LockKey::forQueue(QueueName::defaultQueue());
+            $workers = [
+                WorkerId::generate(),
+                WorkerId::generate(),
+                WorkerId::generate()
+            ];
+
+            // Simulate lock contention - only first worker succeeds
+            $successStmt = mock(\PDOStatement::class);
+            $successStmt->shouldReceive('execute')->andReturn(true);
+            $successStmt->shouldReceive('rowCount')->andReturn(1);
+
+            $failStmt = mock(\PDOStatement::class);
+            $failStmt->shouldReceive('execute')->andThrow(
+                new \PDOException('Duplicate entry')
+            );
+
+            $this->connection->shouldReceive('prepare')->andReturn(
+                $successStmt, // First worker succeeds
+                $failStmt,    // Second worker fails
+                $failStmt     // Third worker fails
+            );
+
+            $this->logger->shouldReceive('debug')->andReturn(null);
+            $this->logger->shouldReceive('info')->andReturn(null);
+
+            $results = [];
+            foreach ($workers as $workerId) {
+                $result = $this->distributedLock->acquire(
+                    $lockKey,
+                    $workerId,
+                    Duration::fromMinutes(5)
+                );
+                $results[] = $result;
+            }
+
+            // Only one worker should succeed
+            $successCount = array_sum($results);
+            expect($successCount)->toBe(1);
+        });
+
+        it('recovers gracefully from database connection failures', function () {
+            // Mock database connection failure
+            $this->connection->shouldReceive('prepare')->andThrow(
+                new \PDOException('Connection lost')
+            );
+
+            $this->logger->shouldReceive('error')->andReturn(null);
+
+            // System should handle gracefully and throw appropriate exception
+            expect(fn() => $this->workerRegistry->findActiveWorkers())
+                ->toThrow(\PDOException::class);
+        });
+
+        it('provides comprehensive system statistics for monitoring', function () {
+            // Mock statistics queries
+            $statsStmt = mock(\PDOStatement::class);
+            $statsStmt->shouldReceive('execute')->andReturn(true);
+            $statsStmt->shouldReceive('fetch')->andReturn([
+                'total_workers' => 3,
+                'active_workers' => 2,
+                'healthy_workers' => 2,
+                'unique_hosts' => 2,
+                'total_capacity' => 30,
+                'current_load' => 10,
+                'avg_cpu_usage' => 45.5,
+                'avg_memory_usage' => 819200000 // ~800MB in bytes
+            ]);
+
+            $queueStmt = mock(\PDOStatement::class);
+            $queueStmt->shouldReceive('execute')->andReturn(true);
+            $queueStmt->shouldReceive('fetch')->andReturn(
+                ['queues' => '["default", "email"]'],
+                ['queues' => '["default", "high-priority"]'],
+                false
+            );
+
+            $this->connection->shouldReceive('prepare')->andReturn(
+                $statsStmt, $queueStmt
+            );
+
+            $this->logger->shouldReceive('error')->never();
+
+            $statistics = $this->workerRegistry->getWorkerStatistics();
+
+            expect($statistics)->toHaveKey('total_workers');
+            expect($statistics)->toHaveKey('active_workers');
+            expect($statistics)->toHaveKey('capacity_utilization');
+            expect($statistics['total_workers'])->toBe(3);
+            expect($statistics['active_workers'])->toBe(2);
+        });
+    });
+
+    describe('Value Object Behavior', function () {
+        it('ensures WorkerId uniqueness and proper formatting', function () {
+            $workerId1 = WorkerId::generate();
+            $workerId2 = WorkerId::generate();
+
+            expect($workerId1->toString())->not->toBe($workerId2->toString());
+            expect($workerId1->equals($workerId2))->toBeFalse();
+
+            // Test host-based WorkerId
+            $hostWorkerId = WorkerId::forHost('test-host', 1234);
+            expect($hostWorkerId->toString())->toContain('test-host');
+        });
+
+        it('validates LockKey patterns and constraints', function () {
+            $jobLock = LockKey::forJob($this->jobId1);
+            $queueLock = LockKey::forQueue(QueueName::defaultQueue());
+            $workerLock = LockKey::forWorker($this->worker1->id);
+
+            expect($jobLock->toString())->toStartWith('job.');
+            expect($queueLock->toString())->toStartWith('queue.');
+            expect($workerLock->toString())->toStartWith('worker.');
+
+            // Test lock key modifications
+            $prefixedLock = $jobLock->withPrefix('tenant-1');
+            $suffixedLock = $queueLock->withSuffix('processing');
+
+            expect($prefixedLock->toString())->toStartWith('tenant-1.job.');
+            expect($suffixedLock->toString())->toEndWith('.processing');
+        });
+
+        it('validates JobId generation and uniqueness', function () {
+            $jobId1 = JobId::generate();
+            $jobId2 = JobId::generate();
+
+            expect($jobId1->toString())->not->toBe($jobId2->toString());
+            expect($jobId1->equals($jobId2))->toBeFalse();
+
+            // Test string conversion
+            $jobIdFromString = JobId::fromString($jobId1->toString());
+            expect($jobIdFromString->equals($jobId1))->toBeTrue();
+        });
+
+        it('properly handles QueueName creation and equality', function () {
+            $queue1 = QueueName::defaultQueue();
+            $queue2 = QueueName::emailQueue();
+            $queue3 = QueueName::fromString('custom-queue');
+
+            expect($queue1->toString())->toBe('default');
+            expect($queue2->toString())->toBe('email');
+            expect($queue3->toString())->toBe('custom-queue');
+
+            expect($queue1->equals($queue2))->toBeFalse();
+            expect($queue1->equals(QueueName::defaultQueue()))->toBeTrue();
+        });
+    });
+
+    describe('Edge Cases and Error Scenarios', function () {
+        it('handles worker registration with invalid data gracefully', function () {
+            expect(fn() => Worker::register(
+                hostname: '', // Invalid empty hostname
+                processId: 1001,
+                queues: [QueueName::defaultQueue()],
+                maxJobs: 10
+            ))->toThrow(\InvalidArgumentException::class);
+
+            expect(fn() => Worker::register(
+                hostname: 'valid-host',
+                processId: 1001,
+                queues: [], // Invalid empty queues
+                maxJobs: 10
+            ))->toThrow(\InvalidArgumentException::class);
+
+            expect(fn() => Worker::register(
+                hostname: 'valid-host',
+                processId: 1001,
+                queues: [QueueName::defaultQueue()],
+                maxJobs: 0 // Invalid max jobs
+            ))->toThrow(\InvalidArgumentException::class);
+        });
+
+        it('handles lock key validation properly', function () {
+            expect(fn() => LockKey::fromString(''))
+                ->toThrow(\InvalidArgumentException::class);
+
+            expect(fn() => LockKey::fromString(str_repeat('a', 256))) // Too long
+                ->toThrow(\InvalidArgumentException::class);
+
+            expect(fn() => LockKey::fromString('invalid@key!')) // Invalid characters
+                ->toThrow(\InvalidArgumentException::class);
+        });
+
+        it('handles job distribution when all workers are at capacity', function () {
+            // Mock database returning workers at full capacity
+            $stmt = mock(\PDOStatement::class);
+            $stmt->shouldReceive('execute')->andReturn(true);
+            $stmt->shouldReceive('fetch')->andReturn(false); // No available workers
+
+            $this->connection->shouldReceive('prepare')->andReturn($stmt);
+            $this->logger->shouldReceive('warning')->andReturn(null);
+
+            $result = $this->jobDistribution->findBestWorkerForJob(QueueName::defaultQueue());
+
+            expect($result)->toBeNull();
+        });
+
+        it('handles lock acquisition timeout correctly', function () {
+            $lockKey = LockKey::forJob($this->jobId1);
+            $workerId = WorkerId::generate();
+            $ttl = Duration::fromMinutes(5);
+            $shortTimeout = Duration::fromMilliseconds(100); // Very short timeout
+
+            // Mock all acquisition attempts fail
+            $stmt = mock(\PDOStatement::class);
+            $stmt->shouldReceive('execute')->andThrow(
+                new \PDOException('Duplicate entry')
+            );
+
+            $this->connection->shouldReceive('prepare')->andReturn($stmt);
+            $this->logger->shouldReceive('debug')->andReturn(null);
+            $this->logger->shouldReceive('info')->andReturn(null);
+
+            $result = $this->distributedLock->acquireWithTimeout(
+                $lockKey,
+                $workerId,
+                $ttl,
+                $shortTimeout
+            );
+
+            expect($result)->toBeFalse();
+        });
+    });
+});

tests/Framework/Queue/JobMetricsTest.php

@@ -0,0 +1,691 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\ValueObjects\JobMetrics;
+use App\Framework\Queue\ValueObjects\JobId;
+use App\Framework\Queue\ValueObjects\QueueName;
+use App\Framework\Core\ValueObjects\Percentage;
+
+describe('JobMetrics Value Object', function () {
+
+    describe('Creation and Basic Properties', function () {
+        it('can create job metrics with minimal parameters', function () {
+            $jobId = JobId::generate()->toString();
+            $queueName = 'email-queue';
+
+            $metrics = JobMetrics::create($jobId, $queueName);
+
+            expect($metrics->jobId)->toBe($jobId);
+            expect($metrics->queueName)->toBe($queueName);
+            expect($metrics->status)->toBe('pending');
+            expect($metrics->attempts)->toBe(0);
+            expect($metrics->maxAttempts)->toBe(3);
+            expect($metrics->executionTimeMs)->toBe(0.0);
+            expect($metrics->memoryUsageBytes)->toBe(0);
+            expect($metrics->errorMessage)->toBeNull();
+            expect($metrics->createdAt)->toBeString();
+            expect($metrics->startedAt)->toBeNull();
+            expect($metrics->completedAt)->toBeNull();
+            expect($metrics->failedAt)->toBeNull();
+            expect($metrics->metadata)->toBe([]);
+        });
+
+        it('can create job metrics with custom parameters', function () {
+            $jobId = JobId::generate()->toString();
+            $queueName = 'report-queue';
+            $status = 'running';
+            $attempts = 2;
+            $maxAttempts = 5;
+
+            $metrics = JobMetrics::create($jobId, $queueName, $status, $attempts, $maxAttempts);
+
+            expect($metrics->status)->toBe($status);
+            expect($metrics->attempts)->toBe($attempts);
+            expect($metrics->maxAttempts)->toBe($maxAttempts);
+        });
+
+        it('is readonly and immutable', function () {
+            $metrics = JobMetrics::create('test-job', 'test-queue');
+
+            $reflection = new ReflectionClass($metrics);
+            expect($reflection->isReadOnly())->toBeTrue();
+
+            // All properties should be readonly
+            $properties = ['jobId', 'queueName', 'status', 'attempts', 'maxAttempts',
+                          'executionTimeMs', 'memoryUsageBytes', 'errorMessage',
+                          'createdAt', 'startedAt', 'completedAt', 'failedAt', 'metadata'];
+
+            foreach ($properties as $prop) {
+                $property = $reflection->getProperty($prop);
+                expect($property->isReadOnly())->toBeTrue("Property {$prop} should be readonly");
+            }
+        });
+    });
+
+    describe('Job State Transitions', function () {
+        beforeEach(function () {
+            $this->baseMetrics = JobMetrics::create('test-job-123', 'email-queue');
+        });
+
+        it('can transition from pending to running', function () {
+            $startTime = microtime(true) * 1000; // milliseconds
+            $memoryUsage = 1024 * 1024; // 1MB
+
+            $runningMetrics = $this->baseMetrics->withStarted($startTime, $memoryUsage);
+
+            expect($runningMetrics->status)->toBe('running');
+            expect($runningMetrics->attempts)->toBe(1); // Incremented from 0
+            expect($runningMetrics->executionTimeMs)->toBe($startTime);
+            expect($runningMetrics->memoryUsageBytes)->toBe($memoryUsage);
+            expect($runningMetrics->startedAt)->toBeString();
+            expect($runningMetrics->startedAt)->not->toBeNull();
+
+            // Original should be unchanged
+            expect($this->baseMetrics->status)->toBe('pending');
+            expect($this->baseMetrics->attempts)->toBe(0);
+        });
+
+        it('can transition from running to completed', function () {
+            $startTime = microtime(true) * 1000;
+            $runningMetrics = $this->baseMetrics->withStarted($startTime, 1024 * 1024);
+
+            $totalExecutionTime = 5500.0; // 5.5 seconds in milliseconds
+            $peakMemoryUsage = 2 * 1024 * 1024; // 2MB
+
+            $completedMetrics = $runningMetrics->withCompleted($totalExecutionTime, $peakMemoryUsage);
+
+            expect($completedMetrics->status)->toBe('completed');
+            expect($completedMetrics->executionTimeMs)->toBe($totalExecutionTime);
+            expect($completedMetrics->memoryUsageBytes)->toBe($peakMemoryUsage);
+            expect($completedMetrics->completedAt)->toBeString();
+            expect($completedMetrics->completedAt)->not->toBeNull();
+            expect($completedMetrics->attempts)->toBe(1); // Same as running state
+        });
+
+        it('can transition from running to failed', function () {
+            $startTime = microtime(true) * 1000;
+            $runningMetrics = $this->baseMetrics->withStarted($startTime, 1024 * 1024);
+
+            $errorMessage = 'Database connection timeout';
+            $executionTime = 2500.0; // 2.5 seconds
+            $memoryUsage = 1.5 * 1024 * 1024; // 1.5MB
+
+            $failedMetrics = $runningMetrics->withFailed($errorMessage, $executionTime, $memoryUsage);
+
+            expect($failedMetrics->status)->toBe('failed');
+            expect($failedMetrics->errorMessage)->toBe($errorMessage);
+            expect($failedMetrics->executionTimeMs)->toBe($executionTime);
+            expect($failedMetrics->memoryUsageBytes)->toBe($memoryUsage);
+            expect($failedMetrics->failedAt)->toBeString();
+            expect($failedMetrics->failedAt)->not->toBeNull();
+        });
+
+        it('preserves metadata across state transitions', function () {
+            $originalMetadata = ['batch_id' => 123, 'priority' => 'high'];
+            $metricsWithMetadata = $this->baseMetrics->withMetadata($originalMetadata);
+
+            $runningMetrics = $metricsWithMetadata->withStarted(1000.0, 1024 * 1024);
+            expect($runningMetrics->metadata)->toBe($originalMetadata);
+
+            $completedMetrics = $runningMetrics->withCompleted(5000.0, 2 * 1024 * 1024);
+            expect($completedMetrics->metadata)->toBe($originalMetadata);
+        });
+    });
+
+    describe('Metadata Management', function () {
+        beforeEach(function () {
+            $this->baseMetrics = JobMetrics::create('test-job', 'test-queue');
+        });
+
+        it('can add metadata to metrics', function () {
+            $metadata = [
+                'user_id' => 12345,
+                'email_template' => 'newsletter',
+                'batch_size' => 1000
+            ];
+
+            $metricsWithMetadata = $this->baseMetrics->withMetadata($metadata);
+
+            expect($metricsWithMetadata->metadata)->toBe($metadata);
+            expect($this->baseMetrics->metadata)->toBe([]); // Original unchanged
+        });
+
+        it('merges metadata when called multiple times', function () {
+            $firstMetadata = ['user_id' => 123, 'type' => 'email'];
+            $secondMetadata = ['priority' => 'high', 'retry_count' => 2];
+
+            $metrics = $this->baseMetrics
+                ->withMetadata($firstMetadata)
+                ->withMetadata($secondMetadata);
+
+            expect($metrics->metadata)->toBe([
+                'user_id' => 123,
+                'type' => 'email',
+                'priority' => 'high',
+                'retry_count' => 2
+            ]);
+        });
+
+        it('overwrites existing metadata keys', function () {
+            $firstMetadata = ['priority' => 'low', 'attempts' => 1];
+            $secondMetadata = ['priority' => 'high']; // Overwrites priority
+
+            $metrics = $this->baseMetrics
+                ->withMetadata($firstMetadata)
+                ->withMetadata($secondMetadata);
+
+            expect($metrics->metadata['priority'])->toBe('high');
+            expect($metrics->metadata['attempts'])->toBe(1); // Preserved
+        });
+    });
+
+    describe('Status Check Methods', function () {
+        beforeEach(function () {
+            $this->jobId = 'status-test-job';
+            $this->queueName = 'status-queue';
+        });
+
+        it('correctly identifies pending status', function () {
+            $metrics = JobMetrics::create($this->jobId, $this->queueName, 'pending');
+
+            expect($metrics->isPending())->toBeTrue();
+            expect($metrics->isRunning())->toBeFalse();
+            expect($metrics->isCompleted())->toBeFalse();
+            expect($metrics->isFailed())->toBeFalse();
+        });
+
+        it('correctly identifies running status', function () {
+            $metrics = JobMetrics::create($this->jobId, $this->queueName, 'running');
+
+            expect($metrics->isRunning())->toBeTrue();
+            expect($metrics->isPending())->toBeFalse();
+            expect($metrics->isCompleted())->toBeFalse();
+            expect($metrics->isFailed())->toBeFalse();
+        });
+
+        it('correctly identifies completed status', function () {
+            $metrics = JobMetrics::create($this->jobId, $this->queueName, 'completed');
+
+            expect($metrics->isCompleted())->toBeTrue();
+            expect($metrics->isPending())->toBeFalse();
+            expect($metrics->isRunning())->toBeFalse();
+            expect($metrics->isFailed())->toBeFalse();
+        });
+
+        it('correctly identifies failed status', function () {
+            $metrics = JobMetrics::create($this->jobId, $this->queueName, 'failed');
+
+            expect($metrics->isFailed())->toBeTrue();
+            expect($metrics->isPending())->toBeFalse();
+            expect($metrics->isRunning())->toBeFalse();
+            expect($metrics->isCompleted())->toBeFalse();
+        });
+
+        it('correctly checks max attempts', function () {
+            $metrics = JobMetrics::create($this->jobId, $this->queueName, 'running', 2, 3);
+            expect($metrics->hasMaxAttempts())->toBeFalse();
+
+            $maxedMetrics = JobMetrics::create($this->jobId, $this->queueName, 'failed', 3, 3);
+            expect($maxedMetrics->hasMaxAttempts())->toBeTrue();
+
+            $exceededMetrics = JobMetrics::create($this->jobId, $this->queueName, 'failed', 5, 3);
+            expect($exceededMetrics->hasMaxAttempts())->toBeTrue();
+        });
+    });
+
+    describe('Calculation Methods', function () {
+        it('calculates success rate correctly', function () {
+            // Job not started yet
+            $pendingMetrics = JobMetrics::create('job', 'queue', 'pending', 0);
+            expect($pendingMetrics->getSuccessRate()->getValue())->toBe(100.0);
+
+            // Failed job with attempts
+            $failedMetrics = JobMetrics::create('job', 'queue', 'failed', 2);
+            expect($failedMetrics->getSuccessRate()->getValue())->toBe(0.0);
+
+            // Completed job
+            $completedMetrics = JobMetrics::create('job', 'queue', 'completed', 1);
+            expect($completedMetrics->getSuccessRate()->getValue())->toBe(100.0);
+        });
+
+        it('converts execution time from milliseconds to seconds', function () {
+            $metrics = JobMetrics::create('job', 'queue')
+                ->withCompleted(5500.0, 1024 * 1024); // 5.5 seconds
+
+            expect($metrics->getExecutionTimeSeconds())->toBe(5.5);
+        });
+
+        it('converts memory usage from bytes to MB', function () {
+            $metrics = JobMetrics::create('job', 'queue')
+                ->withCompleted(1000.0, 2.5 * 1024 * 1024); // 2.5 MB
+
+            expect($metrics->getMemoryUsageMB())->toBe(2.5);
+        });
+
+        it('calculates duration correctly', function () {
+            $metrics = JobMetrics::create('job', 'queue');
+
+            // No duration for pending job
+            expect($metrics->getDuration())->toBeNull();
+
+            // Mock started/completed times
+            $startedMetrics = new JobMetrics(
+                jobId: 'job',
+                queueName: 'queue',
+                status: 'completed',
+                attempts: 1,
+                maxAttempts: 3,
+                executionTimeMs: 1000.0,
+                memoryUsageBytes: 1024,
+                errorMessage: null,
+                createdAt: '2024-01-01 10:00:00',
+                startedAt: '2024-01-01 10:00:05',
+                completedAt: '2024-01-01 10:00:15',
+                failedAt: null
+            );
+
+            $duration = $startedMetrics->getDuration();
+            expect($duration)->toBe(10); // 10 seconds difference
+        });
+
+        it('calculates duration for failed jobs', function () {
+            $failedMetrics = new JobMetrics(
+                jobId: 'job',
+                queueName: 'queue',
+                status: 'failed',
+                attempts: 2,
+                maxAttempts: 3,
+                executionTimeMs: 500.0,
+                memoryUsageBytes: 1024,
+                errorMessage: 'Error occurred',
+                createdAt: '2024-01-01 10:00:00',
+                startedAt: '2024-01-01 10:00:05',
+                completedAt: null,
+                failedAt: '2024-01-01 10:00:08'
+            );
+
+            $duration = $failedMetrics->getDuration();
+            expect($duration)->toBe(3); // 3 seconds from start to failure
+        });
+    });
+
+    describe('Array Conversion', function () {
+        it('provides comprehensive metrics information', function () {
+            $metrics = JobMetrics::create('test-job-456', 'email-queue', 'completed', 1, 3)
+                ->withCompleted(3750.0, 1.5 * 1024 * 1024)
+                ->withMetadata(['batch_id' => 789, 'template' => 'welcome']);
+
+            $array = $metrics->toArray();
+
+            // Verify all expected keys exist
+            $expectedKeys = [
+                'job_id', 'queue_name', 'status', 'attempts', 'max_attempts',
+                'execution_time_ms', 'execution_time_seconds', 'memory_usage_bytes',
+                'memory_usage_mb', 'success_rate', 'duration_seconds', 'error_message',
+                'created_at', 'started_at', 'completed_at', 'failed_at', 'metadata'
+            ];
+
+            foreach ($expectedKeys as $key) {
+                expect($array)->toHaveKey($key);
+            }
+
+            // Verify calculated values
+            expect($array['job_id'])->toBe('test-job-456');
+            expect($array['queue_name'])->toBe('email-queue');
+            expect($array['status'])->toBe('completed');
+            expect($array['execution_time_seconds'])->toBe(3.75);
+            expect($array['memory_usage_mb'])->toBe(1.5);
+            expect($array['success_rate'])->toBe(100.0);
+            expect($array['metadata'])->toBe(['batch_id' => 789, 'template' => 'welcome']);
+        });
+
+        it('handles null values correctly in array conversion', function () {
+            $pendingMetrics = JobMetrics::create('pending-job', 'test-queue');
+            $array = $pendingMetrics->toArray();
+
+            expect($array['error_message'])->toBeNull();
+            expect($array['started_at'])->toBeNull();
+            expect($array['completed_at'])->toBeNull();
+            expect($array['failed_at'])->toBeNull();
+            expect($array['duration_seconds'])->toBeNull();
+        });
+    });
+
+    describe('Edge Cases and Error Handling', function () {
+        it('handles zero execution time', function () {
+            $metrics = JobMetrics::create('instant-job', 'fast-queue')
+                ->withCompleted(0.0, 1024);
+
+            expect($metrics->getExecutionTimeSeconds())->toBe(0.0);
+        });
+
+        it('handles zero memory usage', function () {
+            $metrics = JobMetrics::create('no-memory-job', 'efficient-queue')
+                ->withCompleted(1000.0, 0);
+
+            expect($metrics->getMemoryUsageMB())->toBe(0.0);
+        });
+
+        it('handles very large execution times', function () {
+            $largeTime = 3600000.0; // 1 hour in milliseconds
+            $metrics = JobMetrics::create('long-job', 'slow-queue')
+                ->withCompleted($largeTime, 1024);
+
+            expect($metrics->getExecutionTimeSeconds())->toBe(3600.0); // 1 hour
+        });
+
+        it('handles very large memory usage', function () {
+            $largeMemory = 10 * 1024 * 1024 * 1024; // 10GB
+            $metrics = JobMetrics::create('memory-intensive-job', 'heavy-queue')
+                ->withCompleted(1000.0, $largeMemory);
+
+            expect($metrics->getMemoryUsageMB())->toBe(10240.0); // 10GB in MB
+        });
+
+        it('handles empty metadata gracefully', function () {
+            $metrics = JobMetrics::create('no-metadata-job', 'simple-queue')
+                ->withMetadata([]);
+
+            expect($metrics->metadata)->toBe([]);
+        });
+
+        it('handles complex metadata structures', function () {
+            $complexMetadata = [
+                'nested' => ['level1' => ['level2' => 'value']],
+                'array' => [1, 2, 3, 4, 5],
+                'mixed' => ['string', 42, true, null]
+            ];
+
+            $metrics = JobMetrics::create('complex-job', 'data-queue')
+                ->withMetadata($complexMetadata);
+
+            expect($metrics->metadata)->toBe($complexMetadata);
+        });
+    });
+});
+
+describe('Job Metrics Collection Mock System', function () {
+
+    beforeEach(function () {
+        // Create a mock metrics manager for testing
+        $this->metricsManager = new class {
+            private array $jobMetrics = [];
+            private array $queueStats = [];
+
+            public function recordJobExecution(string $jobId, float $executionTimeMs, int $memoryUsage): void {
+                if (!isset($this->jobMetrics[$jobId])) {
+                    $this->jobMetrics[$jobId] = JobMetrics::create($jobId, 'default-queue');
+                }
+
+                $this->jobMetrics[$jobId] = $this->jobMetrics[$jobId]
+                    ->withCompleted($executionTimeMs, $memoryUsage);
+            }
+
+            public function recordJobFailure(string $jobId, string $errorMessage, float $executionTimeMs, int $memoryUsage): void {
+                if (!isset($this->jobMetrics[$jobId])) {
+                    $this->jobMetrics[$jobId] = JobMetrics::create($jobId, 'default-queue');
+                }
+
+                $this->jobMetrics[$jobId] = $this->jobMetrics[$jobId]
+                    ->withFailed($errorMessage, $executionTimeMs, $memoryUsage);
+            }
+
+            public function getJobMetrics(string $jobId): ?JobMetrics {
+                return $this->jobMetrics[$jobId] ?? null;
+            }
+
+            public function getQueueMetrics(string $queueName): array {
+                $jobs = array_filter($this->jobMetrics, fn($metrics) => $metrics->queueName === $queueName);
+
+                if (empty($jobs)) {
+                    return [
+                        'queue_name' => $queueName,
+                        'total_jobs' => 0,
+                        'completed_jobs' => 0,
+                        'failed_jobs' => 0,
+                        'average_execution_time_ms' => 0.0,
+                        'average_memory_usage_mb' => 0.0,
+                        'success_rate' => 100.0
+                    ];
+                }
+
+                $totalJobs = count($jobs);
+                $completedJobs = count(array_filter($jobs, fn($m) => $m->isCompleted()));
+                $failedJobs = count(array_filter($jobs, fn($m) => $m->isFailed()));
+                $avgExecutionTime = array_sum(array_map(fn($m) => $m->executionTimeMs, $jobs)) / $totalJobs;
+                $avgMemoryUsage = array_sum(array_map(fn($m) => $m->getMemoryUsageMB(), $jobs)) / $totalJobs;
+                $successRate = ($completedJobs / $totalJobs) * 100;
+
+                return [
+                    'queue_name' => $queueName,
+                    'total_jobs' => $totalJobs,
+                    'completed_jobs' => $completedJobs,
+                    'failed_jobs' => $failedJobs,
+                    'average_execution_time_ms' => round($avgExecutionTime, 2),
+                    'average_memory_usage_mb' => round($avgMemoryUsage, 2),
+                    'success_rate' => round($successRate, 2)
+                ];
+            }
+
+            public function getSystemMetrics(): array {
+                if (empty($this->jobMetrics)) {
+                    return [
+                        'total_jobs' => 0,
+                        'completed_jobs' => 0,
+                        'failed_jobs' => 0,
+                        'running_jobs' => 0,
+                        'overall_success_rate' => 100.0,
+                        'average_execution_time_ms' => 0.0,
+                        'peak_memory_usage_mb' => 0.0
+                    ];
+                }
+
+                $totalJobs = count($this->jobMetrics);
+                $completedJobs = count(array_filter($this->jobMetrics, fn($m) => $m->isCompleted()));
+                $failedJobs = count(array_filter($this->jobMetrics, fn($m) => $m->isFailed()));
+                $runningJobs = count(array_filter($this->jobMetrics, fn($m) => $m->isRunning()));
+                $overallSuccessRate = ($completedJobs / $totalJobs) * 100;
+                $avgExecutionTime = array_sum(array_map(fn($m) => $m->executionTimeMs, $this->jobMetrics)) / $totalJobs;
+                $peakMemoryUsage = max(array_map(fn($m) => $m->getMemoryUsageMB(), $this->jobMetrics));
+
+                return [
+                    'total_jobs' => $totalJobs,
+                    'completed_jobs' => $completedJobs,
+                    'failed_jobs' => $failedJobs,
+                    'running_jobs' => $runningJobs,
+                    'overall_success_rate' => round($overallSuccessRate, 2),
+                    'average_execution_time_ms' => round($avgExecutionTime, 2),
+                    'peak_memory_usage_mb' => round($peakMemoryUsage, 2)
+                ];
+            }
+
+            public function getTopSlowJobs(int $limit = 10): array {
+                $jobs = $this->jobMetrics;
+                usort($jobs, fn($a, $b) => $b->executionTimeMs <=> $a->executionTimeMs);
+                return array_slice($jobs, 0, $limit);
+            }
+
+            public function getTopMemoryJobs(int $limit = 10): array {
+                $jobs = $this->jobMetrics;
+                usort($jobs, fn($a, $b) => $b->memoryUsageBytes <=> $a->memoryUsageBytes);
+                return array_slice($jobs, 0, $limit);
+            }
+
+            public function getJobsByQueue(string $queueName): array {
+                return array_filter($this->jobMetrics, fn($metrics) => $metrics->queueName === $queueName);
+            }
+        };
+    });
+
+    describe('Job Metrics Recording', function () {
+        it('can record successful job execution', function () {
+            $jobId = 'success-job-123';
+            $executionTime = 2500.0; // 2.5 seconds
+            $memoryUsage = 3 * 1024 * 1024; // 3MB
+
+            $this->metricsManager->recordJobExecution($jobId, $executionTime, $memoryUsage);
+
+            $metrics = $this->metricsManager->getJobMetrics($jobId);
+            expect($metrics)->not->toBeNull();
+            expect($metrics->isCompleted())->toBeTrue();
+            expect($metrics->executionTimeMs)->toBe($executionTime);
+            expect($metrics->memoryUsageBytes)->toBe($memoryUsage);
+        });
+
+        it('can record failed job execution', function () {
+            $jobId = 'failed-job-456';
+            $errorMessage = 'Database connection timeout';
+            $executionTime = 1200.0; // 1.2 seconds
+            $memoryUsage = 1.5 * 1024 * 1024; // 1.5MB
+
+            $this->metricsManager->recordJobFailure($jobId, $errorMessage, $executionTime, $memoryUsage);
+
+            $metrics = $this->metricsManager->getJobMetrics($jobId);
+            expect($metrics)->not->toBeNull();
+            expect($metrics->isFailed())->toBeTrue();
+            expect($metrics->errorMessage)->toBe($errorMessage);
+            expect($metrics->executionTimeMs)->toBe($executionTime);
+            expect($metrics->memoryUsageBytes)->toBe($memoryUsage);
+        });
+
+        it('handles non-existent job metrics', function () {
+            $metrics = $this->metricsManager->getJobMetrics('non-existent-job');
+            expect($metrics)->toBeNull();
+        });
+    });
+
+    describe('Queue-Level Metrics', function () {
+        beforeEach(function () {
+            // Set up test data with different queue metrics
+            // Email queue jobs
+            $this->metricsManager->recordJobExecution('email-1', 1500.0, 2 * 1024 * 1024);
+            $this->metricsManager->recordJobExecution('email-2', 2000.0, 2.5 * 1024 * 1024);
+            $this->metricsManager->recordJobFailure('email-3', 'SMTP error', 800.0, 1 * 1024 * 1024);
+
+            // Report queue jobs
+            $this->metricsManager->recordJobExecution('report-1', 5000.0, 10 * 1024 * 1024);
+            $this->metricsManager->recordJobExecution('report-2', 7500.0, 15 * 1024 * 1024);
+        });
+
+        it('calculates queue metrics correctly', function () {
+            $emailMetrics = $this->metricsManager->getQueueMetrics('email-queue');
+
+            expect($emailMetrics['queue_name'])->toBe('email-queue');
+            expect($emailMetrics['total_jobs'])->toBe(3);
+            expect($emailMetrics['completed_jobs'])->toBe(2);
+            expect($emailMetrics['failed_jobs'])->toBe(1);
+            expect($emailMetrics['success_rate'])->toBe(66.67); // 2/3 * 100
+        });
+
+        it('handles empty queue metrics', function () {
+            $emptyMetrics = $this->metricsManager->getQueueMetrics('empty-queue');
+
+            expect($emptyMetrics['total_jobs'])->toBe(0);
+            expect($emptyMetrics['completed_jobs'])->toBe(0);
+            expect($emptyMetrics['failed_jobs'])->toBe(0);
+            expect($emptyMetrics['success_rate'])->toBe(100.0);
+            expect($emptyMetrics['average_execution_time_ms'])->toBe(0.0);
+        });
+    });
+
+    describe('System-Level Metrics', function () {
+        beforeEach(function () {
+            // Add various jobs across different queues
+            $this->metricsManager->recordJobExecution('job-1', 1000.0, 1 * 1024 * 1024);
+            $this->metricsManager->recordJobExecution('job-2', 2000.0, 2 * 1024 * 1024);
+            $this->metricsManager->recordJobExecution('job-3', 3000.0, 4 * 1024 * 1024);
+            $this->metricsManager->recordJobFailure('job-4', 'Error', 500.0, 0.5 * 1024 * 1024);
+            $this->metricsManager->recordJobFailure('job-5', 'Error', 750.0, 1 * 1024 * 1024);
+        });
+
+        it('calculates system-wide metrics correctly', function () {
+            $systemMetrics = $this->metricsManager->getSystemMetrics();
+
+            expect($systemMetrics['total_jobs'])->toBe(5);
+            expect($systemMetrics['completed_jobs'])->toBe(3);
+            expect($systemMetrics['failed_jobs'])->toBe(2);
+            expect($systemMetrics['overall_success_rate'])->toBe(60.0); // 3/5 * 100
+            expect($systemMetrics['average_execution_time_ms'])->toBe(1450.0); // (1000+2000+3000+500+750)/5
+            expect($systemMetrics['peak_memory_usage_mb'])->toBe(4.0); // Highest from job-3
+        });
+
+        it('handles empty system gracefully', function () {
+            $emptyManager = new class {
+                private array $jobMetrics = [];
+                public function getSystemMetrics(): array {
+                    return [
+                        'total_jobs' => 0,
+                        'completed_jobs' => 0,
+                        'failed_jobs' => 0,
+                        'running_jobs' => 0,
+                        'overall_success_rate' => 100.0,
+                        'average_execution_time_ms' => 0.0,
+                        'peak_memory_usage_mb' => 0.0
+                    ];
+                }
+            };
+
+            $systemMetrics = $emptyManager->getSystemMetrics();
+            expect($systemMetrics['total_jobs'])->toBe(0);
+            expect($systemMetrics['overall_success_rate'])->toBe(100.0);
+        });
+    });
+
+    describe('Performance Analysis', function () {
+        beforeEach(function () {
+            // Add jobs with varying performance characteristics
+            $this->metricsManager->recordJobExecution('fast-job', 100.0, 0.5 * 1024 * 1024);
+            $this->metricsManager->recordJobExecution('medium-job', 2500.0, 2 * 1024 * 1024);
+            $this->metricsManager->recordJobExecution('slow-job', 10000.0, 1 * 1024 * 1024);
+            $this->metricsManager->recordJobExecution('memory-heavy', 1500.0, 50 * 1024 * 1024);
+            $this->metricsManager->recordJobExecution('balanced-job', 3000.0, 3 * 1024 * 1024);
+        });
+
+        it('identifies slowest jobs correctly', function () {
+            $slowJobs = $this->metricsManager->getTopSlowJobs(3);
+
+            expect(count($slowJobs))->toBe(3);
+            expect($slowJobs[0]->jobId)->toBe('slow-job');
+            expect($slowJobs[1]->jobId)->toBe('balanced-job');
+            expect($slowJobs[2]->jobId)->toBe('medium-job');
+        });
+
+        it('identifies memory-intensive jobs correctly', function () {
+            $memoryJobs = $this->metricsManager->getTopMemoryJobs(3);
+
+            expect(count($memoryJobs))->toBe(3);
+            expect($memoryJobs[0]->jobId)->toBe('memory-heavy');
+            expect($memoryJobs[1]->jobId)->toBe('balanced-job');
+            expect($memoryJobs[2]->jobId)->toBe('medium-job');
+        });
+
+        it('respects limit parameter for top jobs', function () {
+            $limitedSlowJobs = $this->metricsManager->getTopSlowJobs(2);
+            expect(count($limitedSlowJobs))->toBe(2);
+
+            $limitedMemoryJobs = $this->metricsManager->getTopMemoryJobs(1);
+            expect(count($limitedMemoryJobs))->toBe(1);
+        });
+    });
+
+    describe('Queue Filtering and Analysis', function () {
+        beforeEach(function () {
+            // This would require modifying the mock to support different queues
+            // For now, we'll test the interface
+        });
+
+        it('can retrieve jobs by queue', function () {
+            $this->metricsManager->recordJobExecution('email-1', 1000.0, 1024 * 1024);
+            $this->metricsManager->recordJobExecution('email-2', 2000.0, 2048 * 1024);
+
+            $queueJobs = $this->metricsManager->getJobsByQueue('default-queue');
+            expect(count($queueJobs))->toBe(2);
+        });
+
+        it('handles non-existent queue filtering', function () {
+            $emptyQueue = $this->metricsManager->getJobsByQueue('non-existent-queue');
+            expect($emptyQueue)->toBe([]);
+        });
+    });
+});

tests/Framework/Queue/JobProgressTrackingTest.php

@@ -0,0 +1,760 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\ValueObjects\JobProgress;
+use App\Framework\Queue\ValueObjects\ProgressStep;
+use App\Framework\Queue\ValueObjects\JobId;
+use App\Framework\Core\ValueObjects\Percentage;
+
+describe('JobProgress Value Object', function () {
+
+    describe('Basic Construction and Validation', function () {
+        it('can create job progress with percentage and message', function () {
+            $percentage = Percentage::fromValue(50.0);
+            $message = 'Processing half way complete';
+            $metadata = ['step' => 'validation', 'items_processed' => 500];
+
+            $progress = JobProgress::withPercentage($percentage, $message, $metadata);
+
+            expect($progress->percentage)->toBe($percentage);
+            expect($progress->message)->toBe($message);
+            expect($progress->metadata)->toBe($metadata);
+        });
+
+        it('rejects empty progress messages', function () {
+            expect(fn() => JobProgress::withPercentage(Percentage::zero(), ''))
+                ->toThrow(\InvalidArgumentException::class, 'Progress message cannot be empty');
+
+            expect(fn() => JobProgress::withPercentage(Percentage::zero(), '   '))
+                ->toThrow(\InvalidArgumentException::class, 'Progress message cannot be empty');
+        });
+
+        it('is readonly and immutable', function () {
+            $progress = JobProgress::starting('Test job starting');
+
+            $reflection = new ReflectionClass($progress);
+            expect($reflection->isReadOnly())->toBeTrue();
+
+            // All properties should be readonly
+            foreach (['percentage', 'message', 'metadata'] as $prop) {
+                $property = $reflection->getProperty($prop);
+                expect($property->isReadOnly())->toBeTrue("Property {$prop} should be readonly");
+            }
+        });
+    });
+
+    describe('Factory Methods', function () {
+        it('creates starting progress', function () {
+            $progress = JobProgress::starting();
+
+            expect($progress->percentage->getValue())->toBe(0.0);
+            expect($progress->message)->toBe('Job starting...');
+            expect($progress->isStarting())->toBeTrue();
+            expect($progress->isCompleted())->toBeFalse();
+            expect($progress->isFailed())->toBeFalse();
+        });
+
+        it('creates starting progress with custom message', function () {
+            $message = 'Email job initializing...';
+            $progress = JobProgress::starting($message);
+
+            expect($progress->percentage->getValue())->toBe(0.0);
+            expect($progress->message)->toBe($message);
+            expect($progress->isStarting())->toBeTrue();
+        });
+
+        it('creates completed progress', function () {
+            $progress = JobProgress::completed();
+
+            expect($progress->percentage->getValue())->toBe(100.0);
+            expect($progress->message)->toBe('Job completed successfully');
+            expect($progress->isCompleted())->toBeTrue();
+            expect($progress->isStarting())->toBeFalse();
+            expect($progress->isFailed())->toBeFalse();
+        });
+
+        it('creates completed progress with custom message', function () {
+            $message = 'All emails sent successfully';
+            $progress = JobProgress::completed($message);
+
+            expect($progress->percentage->getValue())->toBe(100.0);
+            expect($progress->message)->toBe($message);
+            expect($progress->isCompleted())->toBeTrue();
+        });
+
+        it('creates failed progress', function () {
+            $progress = JobProgress::failed();
+
+            expect($progress->percentage->getValue())->toBe(0.0);
+            expect($progress->message)->toBe('Job failed');
+            expect($progress->isFailed())->toBeTrue();
+            expect($progress->isCompleted())->toBeFalse();
+            expect($progress->isStarting())->toBeFalse();
+            expect($progress->metadata['status'])->toBe('failed');
+        });
+
+        it('creates failed progress with custom message', function () {
+            $message = 'Email service unavailable';
+            $progress = JobProgress::failed($message);
+
+            expect($progress->message)->toBe($message);
+            expect($progress->isFailed())->toBeTrue();
+        });
+
+        it('creates progress from ratio', function () {
+            $progress = JobProgress::fromRatio(25, 100, 'Processing items', ['current_item' => 25]);
+
+            expect($progress->percentage->getValue())->toBe(25.0);
+            expect($progress->message)->toBe('Processing items');
+            expect($progress->metadata['current_item'])->toBe(25);
+        });
+
+        it('handles edge cases in fromRatio', function () {
+            // Zero total
+            $progress = JobProgress::fromRatio(0, 0, 'No items to process');
+            expect($progress->percentage->getValue())->toBe(0.0);
+
+            // All items processed
+            $progress = JobProgress::fromRatio(100, 100, 'All items processed');
+            expect($progress->percentage->getValue())->toBe(100.0);
+            expect($progress->isCompleted())->toBeTrue();
+        });
+    });
+
+    describe('Status Check Methods', function () {
+        it('correctly identifies completed status', function () {
+            $completed = JobProgress::completed();
+            $partial = JobProgress::withPercentage(Percentage::fromValue(50.0), 'Half done');
+            $starting = JobProgress::starting();
+
+            expect($completed->isCompleted())->toBeTrue();
+            expect($partial->isCompleted())->toBeFalse();
+            expect($starting->isCompleted())->toBeFalse();
+        });
+
+        it('correctly identifies failed status', function () {
+            $failed = JobProgress::failed();
+            $completed = JobProgress::completed();
+            $starting = JobProgress::starting();
+
+            expect($failed->isFailed())->toBeTrue();
+            expect($completed->isFailed())->toBeFalse();
+            expect($starting->isFailed())->toBeFalse();
+        });
+
+        it('correctly identifies starting status', function () {
+            $starting = JobProgress::starting();
+            $partial = JobProgress::withPercentage(Percentage::fromValue(10.0), 'Just started');
+            $failed = JobProgress::failed();
+            $completed = JobProgress::completed();
+
+            expect($starting->isStarting())->toBeTrue();
+            expect($partial->isStarting())->toBeFalse();
+            expect($failed->isStarting())->toBeFalse(); // Failed is not starting
+            expect($completed->isStarting())->toBeFalse();
+        });
+
+        it('handles edge cases in status detection', function () {
+            // Zero percentage but not starting due to metadata
+            $zeroButNotStarting = JobProgress::withPercentage(
+                Percentage::zero(),
+                'Waiting for dependencies',
+                ['status' => 'waiting']
+            );
+            expect($zeroButNotStarting->isStarting())->toBeTrue(); // Still starting since not failed
+
+            // Custom failed status
+            $customFailed = JobProgress::withPercentage(
+                Percentage::fromValue(50.0),
+                'Failed during processing',
+                ['status' => 'failed']
+            );
+            expect($customFailed->isFailed())->toBeTrue();
+            expect($customFailed->isCompleted())->toBeFalse();
+        });
+    });
+
+    describe('Immutable Transformations', function () {
+        beforeEach(function () {
+            $this->originalProgress = JobProgress::withPercentage(
+                Percentage::fromValue(25.0),
+                'Quarter complete',
+                ['step' => 'validation']
+            );
+        });
+
+        it('withMetadata() creates new instance with merged metadata', function () {
+            $newMetadata = ['items_processed' => 250, 'errors' => 0];
+            $updated = $this->originalProgress->withMetadata($newMetadata);
+
+            expect($updated)->not->toBe($this->originalProgress);
+            expect($updated->percentage)->toBe($this->originalProgress->percentage);
+            expect($updated->message)->toBe($this->originalProgress->message);
+            expect($updated->metadata['step'])->toBe('validation'); // Original metadata preserved
+            expect($updated->metadata['items_processed'])->toBe(250); // New metadata added
+            expect($updated->metadata['errors'])->toBe(0);
+
+            // Original should be unchanged
+            expect($this->originalProgress->metadata)->toBe(['step' => 'validation']);
+        });
+
+        it('withMetadata() overwrites conflicting keys', function () {
+            $newMetadata = ['step' => 'processing']; // Conflicts with existing key
+            $updated = $this->originalProgress->withMetadata($newMetadata);
+
+            expect($updated->metadata['step'])->toBe('processing'); // New value wins
+        });
+
+        it('withUpdatedProgress() creates new instance with updated progress', function () {
+            $newPercentage = Percentage::fromValue(75.0);
+            $newMessage = 'Three quarters complete';
+            $updated = $this->originalProgress->withUpdatedProgress($newPercentage, $newMessage);
+
+            expect($updated)->not->toBe($this->originalProgress);
+            expect($updated->percentage)->toBe($newPercentage);
+            expect($updated->message)->toBe($newMessage);
+            expect($updated->metadata)->toBe($this->originalProgress->metadata); // Metadata preserved
+
+            // Original should be unchanged
+            expect($this->originalProgress->percentage->getValue())->toBe(25.0);
+            expect($this->originalProgress->message)->toBe('Quarter complete');
+        });
+
+        it('can chain transformations', function () {
+            $final = $this->originalProgress
+                ->withUpdatedProgress(Percentage::fromValue(50.0), 'Half complete')
+                ->withMetadata(['processed_items' => 500]);
+
+            expect($final->percentage->getValue())->toBe(50.0);
+            expect($final->message)->toBe('Half complete');
+            expect($final->metadata['step'])->toBe('validation'); // Original preserved
+            expect($final->metadata['processed_items'])->toBe(500); // New added
+
+            // Original should be completely unchanged
+            expect($this->originalProgress->percentage->getValue())->toBe(25.0);
+            expect($this->originalProgress->message)->toBe('Quarter complete');
+            expect($this->originalProgress->metadata)->toBe(['step' => 'validation']);
+        });
+    });
+
+    describe('Array Conversion', function () {
+        it('toArray() provides comprehensive progress information', function () {
+            $progress = JobProgress::withPercentage(
+                Percentage::fromValue(75.5),
+                'Processing emails',
+                ['batch_id' => 123, 'errors' => 2]
+            );
+
+            $array = $progress->toArray();
+
+            expect($array)->toHaveKey('percentage');
+            expect($array)->toHaveKey('percentage_formatted');
+            expect($array)->toHaveKey('message');
+            expect($array)->toHaveKey('metadata');
+            expect($array)->toHaveKey('is_completed');
+            expect($array)->toHaveKey('is_failed');
+            expect($array)->toHaveKey('is_starting');
+
+            expect($array['percentage'])->toBe(75.5);
+            expect($array['percentage_formatted'])->toBe('75.5%');
+            expect($array['message'])->toBe('Processing emails');
+            expect($array['metadata'])->toBe(['batch_id' => 123, 'errors' => 2]);
+            expect($array['is_completed'])->toBeFalse();
+            expect($array['is_failed'])->toBeFalse();
+            expect($array['is_starting'])->toBeFalse();
+        });
+
+        it('toArray() handles different progress states', function () {
+            $states = [
+                'starting' => JobProgress::starting(),
+                'completed' => JobProgress::completed(),
+                'failed' => JobProgress::failed(),
+            ];
+
+            foreach ($states as $stateName => $progress) {
+                $array = $progress->toArray();
+
+                expect($array)->toBeArray();
+                expect($array)->toHaveKey('is_completed');
+                expect($array)->toHaveKey('is_failed');
+                expect($array)->toHaveKey('is_starting');
+
+                switch ($stateName) {
+                    case 'starting':
+                        expect($array['is_starting'])->toBeTrue();
+                        expect($array['is_completed'])->toBeFalse();
+                        expect($array['is_failed'])->toBeFalse();
+                        break;
+                    case 'completed':
+                        expect($array['is_completed'])->toBeTrue();
+                        expect($array['is_starting'])->toBeFalse();
+                        expect($array['is_failed'])->toBeFalse();
+                        break;
+                    case 'failed':
+                        expect($array['is_failed'])->toBeTrue();
+                        expect($array['is_starting'])->toBeFalse();
+                        expect($array['is_completed'])->toBeFalse();
+                        break;
+                }
+            }
+        });
+    });
+});
+
+describe('Job Progress Tracking System Mock', function () {
+
+    beforeEach(function () {
+        // Create a mock progress tracker for testing
+        $this->progressTracker = new class {
+            private array $progressEntries = [];
+
+            public function updateProgress(string $jobId, JobProgress $progress, ?string $stepName = null): void {
+                $this->progressEntries[$jobId][] = [
+                    'progress' => $progress,
+                    'step_name' => $stepName,
+                    'timestamp' => time(),
+                    'id' => uniqid()
+                ];
+            }
+
+            public function getCurrentProgress(string $jobId): ?JobProgress {
+                if (!isset($this->progressEntries[$jobId]) || empty($this->progressEntries[$jobId])) {
+                    return null;
+                }
+
+                $entries = $this->progressEntries[$jobId];
+                return end($entries)['progress'];
+            }
+
+            public function getProgressHistory(string $jobId): array {
+                return $this->progressEntries[$jobId] ?? [];
+            }
+
+            public function markJobCompleted(string $jobId, string $message = 'Job completed successfully'): void {
+                $this->updateProgress($jobId, JobProgress::completed($message));
+            }
+
+            public function markJobFailed(string $jobId, string $message = 'Job failed', ?\Throwable $exception = null): void {
+                $metadata = [];
+                if ($exception) {
+                    $metadata['exception_type'] = get_class($exception);
+                    $metadata['exception_message'] = $exception->getMessage();
+                }
+
+                $progress = JobProgress::failed($message)->withMetadata($metadata);
+                $this->updateProgress($jobId, $progress);
+            }
+
+            public function getProgressForJobs(array $jobIds): array {
+                $result = [];
+                foreach ($jobIds as $jobId) {
+                    $current = $this->getCurrentProgress($jobId);
+                    if ($current !== null) {
+                        $result[$jobId] = $current;
+                    }
+                }
+                return $result;
+            }
+
+            public function getJobsAboveProgress(float $minPercentage): array {
+                $result = [];
+                foreach ($this->progressEntries as $jobId => $entries) {
+                    $current = end($entries)['progress'];
+                    if ($current->percentage->getValue() >= $minPercentage) {
+                        $result[] = ['job_id' => $jobId, 'progress' => $current];
+                    }
+                }
+                return $result;
+            }
+        };
+    });
+
+    describe('Progress Tracking Operations', function () {
+        it('can track job progress updates', function () {
+            $jobId = JobId::generate()->toString();
+
+            // Track job progression
+            $this->progressTracker->updateProgress($jobId, JobProgress::starting('Job initialized'));
+            $this->progressTracker->updateProgress($jobId, JobProgress::fromRatio(25, 100, 'Processing batch 1'));
+            $this->progressTracker->updateProgress($jobId, JobProgress::fromRatio(50, 100, 'Processing batch 2'));
+            $this->progressTracker->updateProgress($jobId, JobProgress::fromRatio(75, 100, 'Processing batch 3'));
+            $this->progressTracker->markJobCompleted($jobId, 'All batches processed');
+
+            $history = $this->progressTracker->getProgressHistory($jobId);
+            expect(count($history))->toBe(5);
+
+            $current = $this->progressTracker->getCurrentProgress($jobId);
+            expect($current->isCompleted())->toBeTrue();
+            expect($current->message)->toBe('All batches processed');
+        });
+
+        it('can track job with steps', function () {
+            $jobId = JobId::generate()->toString();
+
+            $steps = [
+                'validation' => 'Validating input data',
+                'processing' => 'Processing records',
+                'notification' => 'Sending notifications',
+                'cleanup' => 'Cleaning up temporary files'
+            ];
+
+            foreach ($steps as $stepName => $message) {
+                $this->progressTracker->updateProgress(
+                    $jobId,
+                    JobProgress::fromRatio(array_search($stepName, array_keys($steps)) + 1, count($steps), $message),
+                    $stepName
+                );
+            }
+
+            $history = $this->progressTracker->getProgressHistory($jobId);
+            expect(count($history))->toBe(4);
+
+            // Check step names are tracked
+            $stepNames = array_map(fn($entry) => $entry['step_name'], $history);
+            expect($stepNames)->toBe(['validation', 'processing', 'notification', 'cleanup']);
+        });
+
+        it('can mark jobs as failed with exception details', function () {
+            $jobId = JobId::generate()->toString();
+
+            $this->progressTracker->updateProgress($jobId, JobProgress::starting('Starting email job'));
+            $this->progressTracker->updateProgress($jobId, JobProgress::fromRatio(10, 100, 'Connecting to email service'));
+
+            // Simulate failure with exception
+            $exception = new \RuntimeException('Email service unavailable');
+            $this->progressTracker->markJobFailed($jobId, 'Failed to connect to email service', $exception);
+
+            $current = $this->progressTracker->getCurrentProgress($jobId);
+            expect($current->isFailed())->toBeTrue();
+            expect($current->message)->toBe('Failed to connect to email service');
+            expect($current->metadata['exception_type'])->toBe('RuntimeException');
+            expect($current->metadata['exception_message'])->toBe('Email service unavailable');
+        });
+
+        it('handles jobs with no progress', function () {
+            $nonExistentJobId = JobId::generate()->toString();
+
+            $current = $this->progressTracker->getCurrentProgress($nonExistentJobId);
+            expect($current)->toBeNull();
+
+            $history = $this->progressTracker->getProgressHistory($nonExistentJobId);
+            expect($history)->toBe([]);
+        });
+    });
+
+    describe('Bulk Progress Operations', function () {
+        it('can get progress for multiple jobs', function () {
+            $jobIds = [
+                JobId::generate()->toString(),
+                JobId::generate()->toString(),
+                JobId::generate()->toString(),
+            ];
+
+            // Add progress for some jobs
+            $this->progressTracker->updateProgress($jobIds[0], JobProgress::fromRatio(25, 100, 'Job 1 progress'));
+            $this->progressTracker->updateProgress($jobIds[1], JobProgress::fromRatio(75, 100, 'Job 2 progress'));
+            // Job 3 has no progress
+
+            $bulkProgress = $this->progressTracker->getProgressForJobs($jobIds);
+
+            expect(count($bulkProgress))->toBe(2);
+            expect($bulkProgress[$jobIds[0]]->percentage->getValue())->toBe(25.0);
+            expect($bulkProgress[$jobIds[1]]->percentage->getValue())->toBe(75.0);
+            expect(isset($bulkProgress[$jobIds[2]]))->toBeFalse();
+        });
+
+        it('can find jobs above certain progress threshold', function () {
+            $jobs = [
+                JobId::generate()->toString() => 10.0,
+                JobId::generate()->toString() => 50.0,
+                JobId::generate()->toString() => 80.0,
+                JobId::generate()->toString() => 95.0,
+            ];
+
+            foreach ($jobs as $jobId => $progress) {
+                $this->progressTracker->updateProgress(
+                    $jobId,
+                    JobProgress::fromRatio((int)$progress, 100, "Progress at {$progress}%")
+                );
+            }
+
+            $jobsAbove60 = $this->progressTracker->getJobsAboveProgress(60.0);
+            expect(count($jobsAbove60))->toBe(2); // 80% and 95%
+
+            $jobsAbove90 = $this->progressTracker->getJobsAboveProgress(90.0);
+            expect(count($jobsAbove90))->toBe(1); // Only 95%
+
+            $jobsAbove100 = $this->progressTracker->getJobsAboveProgress(100.0);
+            expect(count($jobsAbove100))->toBe(0); // None at 100%
+        });
+
+        it('handles empty job lists gracefully', function () {
+            $emptyResult = $this->progressTracker->getProgressForJobs([]);
+            expect($emptyResult)->toBe([]);
+
+            $noJobs = $this->progressTracker->getJobsAboveProgress(50.0);
+            expect($noJobs)->toBe([]);
+        });
+    });
+
+    describe('Progress Tracking Edge Cases', function () {
+        it('handles rapid progress updates', function () {
+            $jobId = JobId::generate()->toString();
+
+            // Simulate rapid updates
+            for ($i = 0; $i <= 100; $i += 10) {
+                $this->progressTracker->updateProgress(
+                    $jobId,
+                    JobProgress::fromRatio($i, 100, "Progress at {$i}%")
+                );
+            }
+
+            $history = $this->progressTracker->getProgressHistory($jobId);
+            expect(count($history))->toBe(11); // 0, 10, 20, ..., 100
+
+            $current = $this->progressTracker->getCurrentProgress($jobId);
+            expect($current->isCompleted())->toBeTrue();
+        });
+
+        it('maintains progress order', function () {
+            $jobId = JobId::generate()->toString();
+
+            $progressUpdates = [
+                ['percentage' => 0, 'message' => 'Starting'],
+                ['percentage' => 25, 'message' => 'Quarter done'],
+                ['percentage' => 50, 'message' => 'Half done'],
+                ['percentage' => 75, 'message' => 'Three quarters done'],
+                ['percentage' => 100, 'message' => 'Completed'],
+            ];
+
+            foreach ($progressUpdates as $update) {
+                $this->progressTracker->updateProgress(
+                    $jobId,
+                    JobProgress::fromRatio($update['percentage'], 100, $update['message'])
+                );
+                // Small delay to ensure different timestamps
+                usleep(1000);
+            }
+
+            $history = $this->progressTracker->getProgressHistory($jobId);
+            $messages = array_map(fn($entry) => $entry['progress']->message, $history);
+
+            expect($messages)->toBe([
+                'Starting',
+                'Quarter done',
+                'Half done',
+                'Three quarters done',
+                'Completed'
+            ]);
+        });
+
+        it('handles concurrent job tracking', function () {
+            $jobIds = [
+                'job_a' => JobId::generate()->toString(),
+                'job_b' => JobId::generate()->toString(),
+                'job_c' => JobId::generate()->toString(),
+            ];
+
+            // Simulate concurrent progress updates
+            foreach ($jobIds as $label => $jobId) {
+                $this->progressTracker->updateProgress($jobId, JobProgress::starting("Starting {$label}"));
+            }
+
+            foreach ($jobIds as $label => $jobId) {
+                $this->progressTracker->updateProgress($jobId, JobProgress::fromRatio(50, 100, "{$label} half done"));
+            }
+
+            // Complete jobs at different times
+            $this->progressTracker->markJobCompleted($jobIds['job_a'], 'Job A completed');
+            $this->progressTracker->markJobFailed($jobIds['job_b'], 'Job B failed');
+            $this->progressTracker->markJobCompleted($jobIds['job_c'], 'Job C completed');
+
+            // Verify independent tracking
+            $progressA = $this->progressTracker->getCurrentProgress($jobIds['job_a']);
+            $progressB = $this->progressTracker->getCurrentProgress($jobIds['job_b']);
+            $progressC = $this->progressTracker->getCurrentProgress($jobIds['job_c']);
+
+            expect($progressA->isCompleted())->toBeTrue();
+            expect($progressB->isFailed())->toBeTrue();
+            expect($progressC->isCompleted())->toBeTrue();
+
+            // Each job should have its own history
+            expect(count($this->progressTracker->getProgressHistory($jobIds['job_a'])))->toBe(3);
+            expect(count($this->progressTracker->getProgressHistory($jobIds['job_b'])))->toBe(3);
+            expect(count($this->progressTracker->getProgressHistory($jobIds['job_c'])))->toBe(3);
+        });
+    });
+});
+
+describe('Job Progress Integration Scenarios', function () {
+
+    beforeEach(function () {
+        $this->emailJob = new class {
+            public function __construct(
+                public array $recipients = ['test@example.com'],
+                public string $subject = 'Test Email',
+                public string $template = 'newsletter'
+            ) {}
+
+            public function getRecipientCount(): int {
+                return count($this->recipients);
+            }
+        };
+
+        $this->reportJob = new class {
+            public function __construct(
+                public string $reportType = 'sales',
+                public array $criteria = ['period' => 'monthly'],
+                public int $totalSteps = 5
+            ) {}
+
+            public function getSteps(): array {
+                return [
+                    'data_collection' => 'Collecting data from database',
+                    'data_processing' => 'Processing and aggregating data',
+                    'chart_generation' => 'Generating charts and graphs',
+                    'pdf_creation' => 'Creating PDF document',
+                    'distribution' => 'Distributing report to stakeholders'
+                ];
+            }
+        };
+    });
+
+    it('demonstrates email job progress tracking', function () {
+        $jobId = JobId::generate()->toString();
+        $progressTracker = new class {
+            private array $progressEntries = [];
+            public function updateProgress(string $jobId, JobProgress $progress, ?string $stepName = null): void {
+                $this->progressEntries[$jobId][] = ['progress' => $progress, 'step_name' => $stepName];
+            }
+            public function getCurrentProgress(string $jobId): ?JobProgress {
+                if (!isset($this->progressEntries[$jobId])) return null;
+                return end($this->progressEntries[$jobId])['progress'];
+            }
+        };
+
+        $totalRecipients = count($this->emailJob->recipients);
+
+        // Start email job
+        $progressTracker->updateProgress(
+            $jobId,
+            JobProgress::starting('Initializing email job'),
+            'initialization'
+        );
+
+        // Template preparation
+        $progressTracker->updateProgress(
+            $jobId,
+            JobProgress::fromRatio(1, 4, 'Preparing email template'),
+            'template_preparation'
+        );
+
+        // Recipient validation
+        $progressTracker->updateProgress(
+            $jobId,
+            JobProgress::fromRatio(2, 4, 'Validating recipient addresses'),
+            'recipient_validation'
+        );
+
+        // Email sending
+        $progressTracker->updateProgress(
+            $jobId,
+            JobProgress::fromRatio(3, 4, 'Sending emails'),
+            'email_sending'
+        );
+
+        // Completion
+        $progressTracker->updateProgress(
+            $jobId,
+            JobProgress::completed('All emails sent successfully'),
+            'completion'
+        );
+
+        $finalProgress = $progressTracker->getCurrentProgress($jobId);
+        expect($finalProgress->isCompleted())->toBeTrue();
+        expect($finalProgress->message)->toBe('All emails sent successfully');
+    });
+
+    it('demonstrates report generation progress tracking', function () {
+        $jobId = JobId::generate()->toString();
+        $progressTracker = new class {
+            private array $progressEntries = [];
+            public function updateProgress(string $jobId, JobProgress $progress, ?string $stepName = null): void {
+                $this->progressEntries[$jobId][] = ['progress' => $progress, 'step_name' => $stepName];
+            }
+            public function getProgressHistory(string $jobId): array {
+                return $this->progressEntries[$jobId] ?? [];
+            }
+        };
+
+        $steps = $this->reportJob->getSteps();
+        $totalSteps = count($steps);
+        $currentStep = 0;
+
+        foreach ($steps as $stepName => $description) {
+            $currentStep++;
+            $progressTracker->updateProgress(
+                $jobId,
+                JobProgress::fromRatio($currentStep, $totalSteps, $description),
+                $stepName
+            );
+        }
+
+        $history = $progressTracker->getProgressHistory($jobId);
+        expect(count($history))->toBe($totalSteps);
+
+        // Verify step progression
+        $stepNames = array_map(fn($entry) => $entry['step_name'], $history);
+        expect($stepNames)->toBe(array_keys($steps));
+
+        // Verify progress percentages
+        $percentages = array_map(fn($entry) => $entry['progress']->percentage->getValue(), $history);
+        expect($percentages)->toBe([20.0, 40.0, 60.0, 80.0, 100.0]);
+    });
+
+    it('demonstrates error handling with progress tracking', function () {
+        $jobId = JobId::generate()->toString();
+        $progressTracker = new class {
+            private array $progressEntries = [];
+            public function updateProgress(string $jobId, JobProgress $progress, ?string $stepName = null): void {
+                $this->progressEntries[$jobId][] = ['progress' => $progress, 'step_name' => $stepName];
+            }
+            public function getCurrentProgress(string $jobId): ?JobProgress {
+                if (!isset($this->progressEntries[$jobId])) return null;
+                return end($this->progressEntries[$jobId])['progress'];
+            }
+        };
+
+        // Start processing
+        $progressTracker->updateProgress(
+            $jobId,
+            JobProgress::starting('Starting data processing job'),
+            'initialization'
+        );
+
+        $progressTracker->updateProgress(
+            $jobId,
+            JobProgress::fromRatio(1, 3, 'Loading data from database'),
+            'data_loading'
+        );
+
+        // Simulate error during processing
+        $exception = new \RuntimeException('Database connection lost');
+        $failedProgress = JobProgress::failed('Processing failed due to database error')
+            ->withMetadata([
+                'exception_type' => get_class($exception),
+                'exception_message' => $exception->getMessage(),
+                'failed_at_step' => 'data_processing',
+                'items_processed' => 150,
+                'total_items' => 500
+            ]);
+
+        $progressTracker->updateProgress($jobId, $failedProgress, 'data_processing');
+
+        $currentProgress = $progressTracker->getCurrentProgress($jobId);
+        expect($currentProgress->isFailed())->toBeTrue();
+        expect($currentProgress->metadata['items_processed'])->toBe(150);
+        expect($currentProgress->metadata['exception_type'])->toBe('RuntimeException');
+    });
+});

tests/Framework/Queue/Performance/DatabasePerformanceTest.php

@@ -0,0 +1,622 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Queue\Performance;
+
+use App\Framework\Database\DatabaseManager;
+use App\Framework\Queue\Distribution\JobDistributionService;
+use App\Framework\Queue\Jobs\JobStatus;
+use App\Framework\Queue\Workers\WorkerRegistry;
+use App\Framework\Queue\Workers\WorkerStatus;
+use PHPUnit\Framework\TestCase;
+
+final class DatabasePerformanceTest extends TestCase
+{
+    private DatabaseManager $database;
+    private WorkerRegistry $workerRegistry;
+    private JobDistributionService $distributionService;
+
+    protected function setUp(): void
+    {
+        $this->database = $this->createTestDatabase();
+        $this->workerRegistry = new WorkerRegistry($this->database);
+        $this->distributionService = new JobDistributionService(
+            $this->database,
+            $this->workerRegistry
+        );
+
+        $this->cleanupTestData();
+        PerformanceTestHelper::warmupDatabase($this->database->getConnection());
+    }
+
+    protected function tearDown(): void
+    {
+        $this->cleanupTestData();
+    }
+
+    public function testWorkerQueryPerformance(): void
+    {
+        // Create workers with different statuses and capacities
+        $workers = array_merge(
+            $this->createWorkers(50, 20, WorkerStatus::AVAILABLE),
+            $this->createWorkers(20, 15, WorkerStatus::BUSY),
+            $this->createWorkers(10, 25, WorkerStatus::FAILED)
+        );
+
+        $this->registerWorkers($workers);
+
+        echo "\nWorker Query Performance Test:\n";
+        echo "Total workers: " . count($workers) . "\n";
+
+        // Test worker lookup by ID
+        $workerLookupTimes = [];
+        for ($i = 0; $i < 100; $i++) {
+            $randomWorker = $workers[array_rand($workers)];
+            $workerId = $randomWorker->id->toString();
+
+            $time = PerformanceTestHelper::measureTime(function() use ($workerId) {
+                return $this->workerRegistry->getWorker($workerId);
+            });
+
+            $workerLookupTimes[] = $time;
+        }
+
+        $lookupStats = PerformanceTestHelper::calculateStatistics($workerLookupTimes);
+        echo "Worker lookup by ID: " . PerformanceTestHelper::formatStatistics($lookupStats) . "\n";
+
+        // Test getting available workers
+        $availableWorkerTimes = [];
+        for ($i = 0; $i < 100; $i++) {
+            $time = PerformanceTestHelper::measureTime(function() {
+                return $this->workerRegistry->getAvailableWorkers();
+            });
+            $availableWorkerTimes[] = $time;
+        }
+
+        $availableStats = PerformanceTestHelper::calculateStatistics($availableWorkerTimes);
+        echo "Get available workers: " . PerformanceTestHelper::formatStatistics($availableStats) . "\n";
+
+        // Test worker status updates
+        $updateTimes = [];
+        for ($i = 0; $i < 100; $i++) {
+            $randomWorker = $workers[array_rand($workers)];
+            $workerId = $randomWorker->id->toString();
+
+            $time = PerformanceTestHelper::measureTime(function() use ($workerId) {
+                $this->updateWorkerStatus($workerId, WorkerStatus::BUSY);
+                $this->updateWorkerStatus($workerId, WorkerStatus::AVAILABLE);
+            });
+
+            $updateTimes[] = $time;
+        }
+
+        $updateStats = PerformanceTestHelper::calculateStatistics($updateTimes);
+        echo "Worker status updates: " . PerformanceTestHelper::formatStatistics($updateStats) . "\n";
+
+        // Validate performance benchmarks
+        $this->assertLessThan(1.0, $lookupStats['avg'], 'Worker lookup average time exceeds 1ms');
+        $this->assertLessThan(2.0, $availableStats['avg'], 'Available workers query average time exceeds 2ms');
+        $this->assertLessThan(5.0, $updateStats['avg'], 'Worker update average time exceeds 5ms');
+
+        PerformanceTestHelper::assertPerformance($workerLookupTimes, 1.0, 2.0, 'Worker lookup');
+        PerformanceTestHelper::assertPerformance($availableWorkerTimes, 2.0, 5.0, 'Available workers query');
+    }
+
+    public function testJobQueryPerformance(): void
+    {
+        $workers = $this->createWorkers(20, 25);
+        $this->registerWorkers($workers);
+
+        // Create jobs with different statuses and priorities
+        $jobs = array_merge(
+            PerformanceTestHelper::createBulkJobs(500),
+            PerformanceTestHelper::createBulkJobs(300, \App\Framework\Queue\Jobs\JobPriority::HIGH),
+            PerformanceTestHelper::createBulkJobs(200, \App\Framework\Queue\Jobs\JobPriority::CRITICAL)
+        );
+
+        // Distribute and update job statuses
+        foreach ($jobs as $index => $job) {
+            $this->distributionService->distributeJob($job);
+
+            // Simulate some completed jobs
+            if ($index % 3 === 0) {
+                $this->updateJobStatus($job->id, JobStatus::COMPLETED);
+            } elseif ($index % 5 === 0) {
+                $this->updateJobStatus($job->id, JobStatus::FAILED);
+            }
+        }
+
+        echo "\nJob Query Performance Test:\n";
+        echo "Total jobs: " . count($jobs) . "\n";
+
+        // Test job lookup by ID
+        $jobLookupTimes = [];
+        for ($i = 0; $i < 100; $i++) {
+            $randomJob = $jobs[array_rand($jobs)];
+            $jobId = $randomJob->id;
+
+            $time = PerformanceTestHelper::measureTime(function() use ($jobId) {
+                return $this->getJobById($jobId);
+            });
+
+            $jobLookupTimes[] = $time;
+        }
+
+        $lookupStats = PerformanceTestHelper::calculateStatistics($jobLookupTimes);
+        echo "Job lookup by ID: " . PerformanceTestHelper::formatStatistics($lookupStats) . "\n";
+
+        // Test getting jobs by status
+        $statusQueryTimes = [];
+        $statuses = [JobStatus::PENDING, JobStatus::PROCESSING, JobStatus::COMPLETED, JobStatus::FAILED];
+
+        foreach ($statuses as $status) {
+            for ($i = 0; $i < 25; $i++) {
+                $time = PerformanceTestHelper::measureTime(function() use ($status) {
+                    return $this->getJobsByStatus($status);
+                });
+                $statusQueryTimes[] = $time;
+            }
+        }
+
+        $statusStats = PerformanceTestHelper::calculateStatistics($statusQueryTimes);
+        echo "Jobs by status query: " . PerformanceTestHelper::formatStatistics($statusStats) . "\n";
+
+        // Test getting jobs by worker
+        $workerJobTimes = [];
+        for ($i = 0; $i < 50; $i++) {
+            $randomWorker = $workers[array_rand($workers)];
+            $workerId = $randomWorker->id->toString();
+
+            $time = PerformanceTestHelper::measureTime(function() use ($workerId) {
+                return $this->getJobsByWorker($workerId);
+            });
+
+            $workerJobTimes[] = $time;
+        }
+
+        $workerJobStats = PerformanceTestHelper::calculateStatistics($workerJobTimes);
+        echo "Jobs by worker query: " . PerformanceTestHelper::formatStatistics($workerJobStats) . "\n";
+
+        // Validate performance benchmarks
+        $this->assertLessThan(1.0, $lookupStats['avg'], 'Job lookup average time exceeds 1ms');
+        $this->assertLessThan(5.0, $statusStats['avg'], 'Job status query average time exceeds 5ms');
+        $this->assertLessThan(3.0, $workerJobStats['avg'], 'Jobs by worker query average time exceeds 3ms');
+
+        PerformanceTestHelper::assertPerformance($jobLookupTimes, 1.0, 2.0, 'Job lookup');
+        PerformanceTestHelper::assertPerformance($statusQueryTimes, 5.0, 10.0, 'Job status queries');
+    }
+
+    public function testBatchOperationPerformance(): void
+    {
+        echo "\nBatch Operation Performance Test:\n";
+
+        $batchSizes = [10, 50, 100, 500, 1000];
+
+        foreach ($batchSizes as $batchSize) {
+            echo "Testing batch size: {$batchSize}\n";
+
+            // Test batch worker registration
+            $workers = $this->createWorkers($batchSize, 20);
+
+            $batchRegisterTime = PerformanceTestHelper::measureTime(function() use ($workers) {
+                $this->registerWorkers($workers);
+            });
+
+            // Test batch job distribution
+            $jobs = PerformanceTestHelper::createBulkJobs($batchSize);
+
+            $batchDistributeTime = PerformanceTestHelper::measureTime(function() use ($jobs) {
+                foreach ($jobs as $job) {
+                    $this->distributionService->distributeJob($job);
+                }
+            });
+
+            // Test batch job status updates
+            $batchUpdateTime = PerformanceTestHelper::measureTime(function() use ($jobs) {
+                foreach ($jobs as $job) {
+                    $this->updateJobStatus($job->id, JobStatus::COMPLETED);
+                }
+            });
+
+            $perItemRegister = $batchRegisterTime / $batchSize;
+            $perItemDistribute = $batchDistributeTime / $batchSize;
+            $perItemUpdate = $batchUpdateTime / $batchSize;
+
+            echo sprintf(
+                "  Register: %6.1fms total (%4.2fms/item), Distribute: %6.1fms (%4.2fms/item), Update: %6.1fms (%4.2fms/item)\n",
+                $batchRegisterTime,
+                $perItemRegister,
+                $batchDistributeTime,
+                $perItemDistribute,
+                $batchUpdateTime,
+                $perItemUpdate
+            );
+
+            // Batch operations should be efficient
+            $this->assertLessThan(2.0, $perItemRegister, "Worker registration too slow for batch size {$batchSize}");
+            $this->assertLessThan(5.0, $perItemDistribute, "Job distribution too slow for batch size {$batchSize}");
+            $this->assertLessThan(1.0, $perItemUpdate, "Job update too slow for batch size {$batchSize}");
+
+            $this->cleanupTestData();
+        }
+    }
+
+    public function testIndexEfficiency(): void
+    {
+        echo "\nIndex Efficiency Test:\n";
+
+        // Create large dataset to test index effectiveness
+        $workerCount = 1000;
+        $jobCount = 5000;
+
+        $workers = $this->createWorkers($workerCount, 20);
+        $this->registerWorkers($workers);
+
+        $jobs = PerformanceTestHelper::createBulkJobs($jobCount);
+        foreach ($jobs as $job) {
+            $this->distributionService->distributeJob($job);
+        }
+
+        echo "Dataset: {$workerCount} workers, {$jobCount} jobs\n";
+
+        // Test indexed queries performance
+        $indexTests = [
+            'worker_by_id' => function() use ($workers) {
+                $randomWorker = $workers[array_rand($workers)];
+                return $this->workerRegistry->getWorker($randomWorker->id->toString());
+            },
+            'workers_by_status' => function() {
+                return $this->workerRegistry->getWorkersByStatus(WorkerStatus::AVAILABLE);
+            },
+            'jobs_by_status' => function() {
+                return $this->getJobsByStatus(JobStatus::PENDING);
+            },
+            'jobs_by_priority' => function() {
+                return $this->getJobsByPriority(\App\Framework\Queue\Jobs\JobPriority::HIGH);
+            },
+            'jobs_by_queue' => function() {
+                return $this->getJobsByQueue('test_queue');
+            }
+        ];
+
+        foreach ($indexTests as $testName => $testFunction) {
+            $times = [];
+
+            for ($i = 0; $i < 100; $i++) {
+                $time = PerformanceTestHelper::measureTime($testFunction);
+                $times[] = $time;
+            }
+
+            $stats = PerformanceTestHelper::calculateStatistics($times);
+            echo "{$testName}: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+            // All indexed queries should be fast even with large dataset
+            $this->assertLessThan(10.0, $stats['avg'], "Index query {$testName} too slow with large dataset");
+            $this->assertLessThan(25.0, $stats['p95'], "Index query {$testName} P95 too slow with large dataset");
+        }
+    }
+
+    public function testConnectionPoolingPerformance(): void
+    {
+        echo "\nConnection Pooling Performance Test:\n";
+
+        // Simulate multiple concurrent database operations
+        $operationTypes = [
+            'worker_lookup' => function() {
+                $workerId = 'worker_' . rand(1, 100);
+                return $this->workerRegistry->getWorker($workerId);
+            },
+            'job_insertion' => function() {
+                $job = PerformanceTestHelper::createTestJob('pool_test_' . uniqid());
+                return $this->distributionService->distributeJob($job);
+            },
+            'status_query' => function() {
+                return $this->getJobsByStatus(JobStatus::PENDING);
+            }
+        ];
+
+        $concurrencyLevels = [1, 5, 10, 20];
+
+        foreach ($concurrencyLevels as $concurrency) {
+            echo "Testing concurrency level: {$concurrency}\n";
+
+            $operationTimes = [];
+            $operationsPerType = 20;
+
+            foreach ($operationTypes as $typeName => $operation) {
+                $typeTimes = [];
+
+                // Simulate concurrent operations (simplified for single-threaded PHP)
+                for ($i = 0; $i < $operationsPerType * $concurrency; $i++) {
+                    $time = PerformanceTestHelper::measureTime($operation);
+                    $typeTimes[] = $time;
+                    $operationTimes[] = $time;
+                }
+
+                $typeStats = PerformanceTestHelper::calculateStatistics($typeTimes);
+                echo "  {$typeName}: " . PerformanceTestHelper::formatStatistics($typeStats) . "\n";
+            }
+
+            $overallStats = PerformanceTestHelper::calculateStatistics($operationTimes);
+            echo "  Overall: " . PerformanceTestHelper::formatStatistics($overallStats) . "\n";
+
+            // Performance should not degrade significantly with concurrency
+            $this->assertLessThan(50.0, $overallStats['avg'], "Database operations too slow at concurrency {$concurrency}");
+        }
+    }
+
+    public function testQueryOptimizationEffectiveness(): void
+    {
+        echo "\nQuery Optimization Effectiveness Test:\n";
+
+        // Create test data with specific patterns to test optimization
+        $workers = $this->createWorkers(500, 20);
+        $this->registerWorkers($workers);
+
+        $jobs = PerformanceTestHelper::createBulkJobs(2000);
+        foreach ($jobs as $job) {
+            $this->distributionService->distributeJob($job);
+        }
+
+        // Test complex queries that should benefit from optimization
+        $complexQueries = [
+            'workers_with_capacity_filter' => function() {
+                return $this->getWorkersByCapacityRange(15, 25);
+            },
+            'jobs_with_multiple_filters' => function() {
+                return $this->getJobsWithFilters(JobStatus::PENDING, \App\Framework\Queue\Jobs\JobPriority::NORMAL);
+            },
+            'job_count_aggregation' => function() {
+                return $this->getJobCountsByStatus();
+            },
+            'worker_utilization_stats' => function() {
+                return $this->getWorkerUtilizationStats();
+            }
+        ];
+
+        foreach ($complexQueries as $queryName => $queryFunction) {
+            $times = [];
+
+            for ($i = 0; $i < 50; $i++) {
+                $time = PerformanceTestHelper::measureTime($queryFunction);
+                $times[] = $time;
+            }
+
+            $stats = PerformanceTestHelper::calculateStatistics($times);
+            echo "{$queryName}: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+            // Complex queries should still be reasonably fast
+            $this->assertLessThan(20.0, $stats['avg'], "Complex query {$queryName} not optimized enough");
+            $this->assertLessThan(50.0, $stats['p95'], "Complex query {$queryName} P95 not optimized enough");
+        }
+    }
+
+    public function testTransactionPerformance(): void
+    {
+        echo "\nTransaction Performance Test:\n";
+
+        $workers = $this->createWorkers(10, 20);
+        $this->registerWorkers($workers);
+
+        // Test transaction overhead
+        $transactionSizes = [1, 5, 10, 50, 100];
+
+        foreach ($transactionSizes as $size) {
+            $transactionTimes = [];
+
+            for ($iteration = 0; $iteration < 20; $iteration++) {
+                $time = PerformanceTestHelper::measureTime(function() use ($size, $iteration) {
+                    $pdo = $this->database->getConnection();
+
+                    try {
+                        $pdo->beginTransaction();
+
+                        for ($i = 0; $i < $size; $i++) {
+                            $job = PerformanceTestHelper::createTestJob("tx_job_{$iteration}_{$i}");
+                            $this->distributionService->distributeJob($job);
+                        }
+
+                        $pdo->commit();
+                    } catch (\Exception $e) {
+                        $pdo->rollBack();
+                        throw $e;
+                    }
+                });
+
+                $transactionTimes[] = $time;
+            }
+
+            $stats = PerformanceTestHelper::calculateStatistics($transactionTimes);
+            $timePerOperation = $stats['avg'] / $size;
+
+            echo sprintf(
+                "Transaction size %3d: %6.1fms total (%5.2fms/operation)\n",
+                $size,
+                $stats['avg'],
+                $timePerOperation
+            );
+
+            // Transaction overhead should be reasonable
+            $this->assertLessThan(200.0, $stats['avg'], "Transaction time too high for size {$size}");
+
+            $this->cleanupJobs();
+        }
+    }
+
+    private function createWorkers(int $count, int $capacity, WorkerStatus $status = WorkerStatus::AVAILABLE): array
+    {
+        $workers = [];
+        for ($i = 1; $i <= $count; $i++) {
+            $workers[] = PerformanceTestHelper::createTestWorker(
+                "db_perf_worker_{$i}",
+                $capacity,
+                $status
+            );
+        }
+        return $workers;
+    }
+
+    private function registerWorkers(array $workers): void
+    {
+        foreach ($workers as $worker) {
+            $this->workerRegistry->registerWorker($worker);
+        }
+    }
+
+    private function updateWorkerStatus(string $workerId, WorkerStatus $status): void
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('UPDATE workers SET status = ? WHERE id = ?');
+        $stmt->execute([$status->value, $workerId]);
+    }
+
+    private function updateJobStatus(string $jobId, JobStatus $status): void
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('UPDATE jobs SET status = ? WHERE id = ?');
+        $stmt->execute([$status->value, $jobId]);
+    }
+
+    private function getJobById(string $jobId): ?array
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('SELECT * FROM jobs WHERE id = ?');
+        $stmt->execute([$jobId]);
+        return $stmt->fetch(\PDO::FETCH_ASSOC) ?: null;
+    }
+
+    private function getJobsByStatus(JobStatus $status): array
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('SELECT * FROM jobs WHERE status = ? LIMIT 100');
+        $stmt->execute([$status->value]);
+        return $stmt->fetchAll(\PDO::FETCH_ASSOC);
+    }
+
+    private function getJobsByWorker(string $workerId): array
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('SELECT * FROM jobs WHERE worker_id = ? LIMIT 100');
+        $stmt->execute([$workerId]);
+        return $stmt->fetchAll(\PDO::FETCH_ASSOC);
+    }
+
+    private function getJobsByPriority(\App\Framework\Queue\Jobs\JobPriority $priority): array
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('SELECT * FROM jobs WHERE priority = ? LIMIT 100');
+        $stmt->execute([$priority->value]);
+        return $stmt->fetchAll(\PDO::FETCH_ASSOC);
+    }
+
+    private function getJobsByQueue(string $queueName): array
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('SELECT * FROM jobs WHERE queue_name = ? LIMIT 100');
+        $stmt->execute([$queueName]);
+        return $stmt->fetchAll(\PDO::FETCH_ASSOC);
+    }
+
+    private function getWorkersByCapacityRange(int $minCapacity, int $maxCapacity): array
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('SELECT * FROM workers WHERE capacity BETWEEN ? AND ?');
+        $stmt->execute([$minCapacity, $maxCapacity]);
+        return $stmt->fetchAll(\PDO::FETCH_ASSOC);
+    }
+
+    private function getJobsWithFilters(JobStatus $status, \App\Framework\Queue\Jobs\JobPriority $priority): array
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('SELECT * FROM jobs WHERE status = ? AND priority = ? LIMIT 100');
+        $stmt->execute([$status->value, $priority->value]);
+        return $stmt->fetchAll(\PDO::FETCH_ASSOC);
+    }
+
+    private function getJobCountsByStatus(): array
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->query('SELECT status, COUNT(*) as count FROM jobs GROUP BY status');
+        return $stmt->fetchAll(\PDO::FETCH_ASSOC);
+    }
+
+    private function getWorkerUtilizationStats(): array
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->query('
+            SELECT
+                w.status,
+                AVG(w.capacity) as avg_capacity,
+                COUNT(*) as worker_count,
+                COUNT(j.id) as job_count
+            FROM workers w
+            LEFT JOIN jobs j ON w.id = j.worker_id
+            GROUP BY w.status
+        ');
+        return $stmt->fetchAll(\PDO::FETCH_ASSOC);
+    }
+
+    private function cleanupJobs(): void
+    {
+        $pdo = $this->database->getConnection();
+        $pdo->exec('DELETE FROM jobs');
+    }
+
+    private function createTestDatabase(): DatabaseManager
+    {
+        $pdo = new \PDO('sqlite::memory:');
+        $pdo->setAttribute(\PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION);
+
+        $pdo->exec('
+            CREATE TABLE workers (
+                id TEXT PRIMARY KEY,
+                queue_names TEXT NOT NULL,
+                capacity INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                last_heartbeat TEXT NOT NULL,
+                metadata TEXT
+            )
+        ');
+
+        $pdo->exec('
+            CREATE TABLE jobs (
+                id TEXT PRIMARY KEY,
+                type TEXT NOT NULL,
+                payload TEXT NOT NULL,
+                queue_name TEXT NOT NULL,
+                priority INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                worker_id TEXT,
+                created_at TEXT NOT NULL,
+                started_at TEXT,
+                completed_at TEXT,
+                attempts INTEGER DEFAULT 0,
+                error_message TEXT
+            )
+        ');
+
+        // Comprehensive indexes for performance testing
+        $pdo->exec('CREATE INDEX idx_workers_id ON workers(id)');
+        $pdo->exec('CREATE INDEX idx_workers_status ON workers(status)');
+        $pdo->exec('CREATE INDEX idx_workers_capacity ON workers(capacity)');
+        $pdo->exec('CREATE INDEX idx_workers_status_capacity ON workers(status, capacity)');
+
+        $pdo->exec('CREATE INDEX idx_jobs_id ON jobs(id)');
+        $pdo->exec('CREATE INDEX idx_jobs_status ON jobs(status)');
+        $pdo->exec('CREATE INDEX idx_jobs_priority ON jobs(priority)');
+        $pdo->exec('CREATE INDEX idx_jobs_queue ON jobs(queue_name)');
+        $pdo->exec('CREATE INDEX idx_jobs_worker ON jobs(worker_id)');
+        $pdo->exec('CREATE INDEX idx_jobs_status_priority ON jobs(status, priority)');
+        $pdo->exec('CREATE INDEX idx_jobs_created ON jobs(created_at)');
+
+        return new DatabaseManager($pdo);
+    }
+
+    private function cleanupTestData(): void
+    {
+        $pdo = $this->database->getConnection();
+        $pdo->exec('DELETE FROM workers');
+        $pdo->exec('DELETE FROM jobs');
+    }
+}

tests/Framework/Queue/Performance/DistributedLockPerformanceTest.php

@@ -0,0 +1,435 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Queue\Performance;
+
+use App\Framework\Database\DatabaseManager;
+use App\Framework\Queue\Locks\DatabaseDistributedLock;
+use App\Framework\Queue\Locks\LockKey;
+use App\Framework\Queue\Locks\LockOwner;
+use PHPUnit\Framework\TestCase;
+
+final class DistributedLockPerformanceTest extends TestCase
+{
+    private DatabaseManager $database;
+    private DatabaseDistributedLock $lockService;
+
+    protected function setUp(): void
+    {
+        $this->database = $this->createTestDatabase();
+        $this->lockService = new DatabaseDistributedLock($this->database);
+
+        $this->cleanupTestData();
+        PerformanceTestHelper::warmupDatabase($this->database->getConnection());
+    }
+
+    protected function tearDown(): void
+    {
+        $this->cleanupTestData();
+    }
+
+    public function testLockAcquisitionLatency(): void
+    {
+        $acquisitionTimes = [];
+        $iterations = 1000;
+
+        for ($i = 0; $i < $iterations; $i++) {
+            $lockKey = new LockKey("test_lock_{$i}");
+            $owner = new LockOwner("owner_{$i}");
+
+            $time = PerformanceTestHelper::measureTime(function() use ($lockKey, $owner) {
+                $acquired = $this->lockService->acquire($lockKey, $owner, 30);
+                if ($acquired) {
+                    $this->lockService->release($lockKey, $owner);
+                }
+                return $acquired;
+            });
+
+            $acquisitionTimes[] = $time;
+        }
+
+        $stats = PerformanceTestHelper::calculateStatistics($acquisitionTimes);
+
+        // Validate performance benchmarks
+        $this->assertLessThan(2.0, $stats['avg'], 'Average lock acquisition time exceeds 2ms');
+        $this->assertLessThan(5.0, $stats['p95'], 'P95 lock acquisition time exceeds 5ms');
+        $this->assertLessThan(10.0, $stats['p99'], 'P99 lock acquisition time exceeds 10ms');
+
+        echo "\nLock Acquisition Latency Results:\n";
+        echo "Iterations: {$iterations}\n";
+        echo "Performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        PerformanceTestHelper::assertPerformance(
+            $acquisitionTimes,
+            2.0,
+            5.0,
+            'Lock acquisition'
+        );
+    }
+
+    public function testLockReleaseLatency(): void
+    {
+        $releaseTimes = [];
+        $iterations = 1000;
+
+        // Pre-acquire locks
+        $locks = [];
+        for ($i = 0; $i < $iterations; $i++) {
+            $lockKey = new LockKey("release_lock_{$i}");
+            $owner = new LockOwner("owner_{$i}");
+
+            $acquired = $this->lockService->acquire($lockKey, $owner, 60);
+            if ($acquired) {
+                $locks[] = ['key' => $lockKey, 'owner' => $owner];
+            }
+        }
+
+        // Measure release times
+        foreach ($locks as $lock) {
+            $time = PerformanceTestHelper::measureTime(function() use ($lock) {
+                return $this->lockService->release($lock['key'], $lock['owner']);
+            });
+            $releaseTimes[] = $time;
+        }
+
+        $stats = PerformanceTestHelper::calculateStatistics($releaseTimes);
+
+        // Validate performance benchmarks
+        $this->assertLessThan(1.5, $stats['avg'], 'Average lock release time exceeds 1.5ms');
+        $this->assertLessThan(3.0, $stats['p95'], 'P95 lock release time exceeds 3ms');
+        $this->assertLessThan(8.0, $stats['p99'], 'P99 lock release time exceeds 8ms');
+
+        echo "\nLock Release Latency Results:\n";
+        echo "Locks released: " . count($releaseTimes) . "\n";
+        echo "Performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        PerformanceTestHelper::assertPerformance(
+            $releaseTimes,
+            1.5,
+            3.0,
+            'Lock release'
+        );
+    }
+
+    public function testLockContentionPerformance(): void
+    {
+        $lockKey = new LockKey('contended_lock');
+        $concurrentAttempts = 20;
+        $attemptsPerWorker = 50;
+
+        $allResults = [];
+        $successCounts = [];
+        $failureCounts = [];
+
+        // Simulate concurrent lock acquisition attempts
+        for ($worker = 0; $worker < $concurrentAttempts; $worker++) {
+            $owner = new LockOwner("worker_{$worker}");
+            $workerResults = [];
+            $successes = 0;
+            $failures = 0;
+
+            for ($attempt = 0; $attempt < $attemptsPerWorker; $attempt++) {
+                $result = PerformanceTestHelper::measureTimeWithResult(function() use ($lockKey, $owner) {
+                    $acquired = $this->lockService->acquire($lockKey, $owner, 1); // 1 second timeout
+                    if ($acquired) {
+                        // Hold lock briefly then release
+                        usleep(100); // 0.1ms
+                        $this->lockService->release($lockKey, $owner);
+                        return true;
+                    }
+                    return false;
+                });
+
+                $workerResults[] = $result['time_ms'];
+
+                if ($result['result']) {
+                    $successes++;
+                } else {
+                    $failures++;
+                }
+
+                // Brief pause between attempts
+                usleep(50); // 0.05ms
+            }
+
+            $allResults = array_merge($allResults, $workerResults);
+            $successCounts[$worker] = $successes;
+            $failureCounts[$worker] = $failures;
+        }
+
+        $stats = PerformanceTestHelper::calculateStatistics($allResults);
+        $totalSuccesses = array_sum($successCounts);
+        $totalFailures = array_sum($failureCounts);
+        $successRate = $totalSuccesses / ($totalSuccesses + $totalFailures) * 100;
+
+        echo "\nLock Contention Performance Results:\n";
+        echo "Concurrent workers: {$concurrentAttempts}\n";
+        echo "Total attempts: " . ($totalSuccesses + $totalFailures) . "\n";
+        echo "Successful acquisitions: {$totalSuccesses}\n";
+        echo "Failed acquisitions: {$totalFailures}\n";
+        echo "Success rate: {$successRate}%\n";
+        echo "Attempt performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        // Under contention, some failures are expected but most should succeed
+        $this->assertGreaterThan(50.0, $successRate, 'Lock success rate too low under contention');
+
+        // Performance should degrade gracefully under contention
+        $this->assertLessThan(50.0, $stats['avg'], 'Average lock time too high under contention');
+        $this->assertLessThan(200.0, $stats['p95'], 'P95 lock time too high under contention');
+    }
+
+    public function testLockTimeoutPerformance(): void
+    {
+        $lockKey = new LockKey('timeout_lock');
+        $owner1 = new LockOwner('owner_1');
+        $owner2 = new LockOwner('owner_2');
+
+        // First owner acquires the lock
+        $acquired = $this->lockService->acquire($lockKey, $owner1, 60);
+        $this->assertTrue($acquired, 'Initial lock acquisition should succeed');
+
+        $timeoutResults = [];
+        $iterations = 100;
+
+        // Second owner repeatedly tries to acquire with short timeouts
+        for ($i = 0; $i < $iterations; $i++) {
+            $result = PerformanceTestHelper::measureTimeWithResult(function() use ($lockKey, $owner2) {
+                return $this->lockService->acquire($lockKey, $owner2, 0.1); // 100ms timeout
+            });
+
+            $timeoutResults[] = $result['time_ms'];
+            $this->assertFalse($result['result'], 'Lock acquisition should fail due to timeout');
+        }
+
+        // Release the lock
+        $this->lockService->release($lockKey, $owner1);
+
+        $stats = PerformanceTestHelper::calculateStatistics($timeoutResults);
+
+        echo "\nLock Timeout Performance Results:\n";
+        echo "Timeout attempts: {$iterations}\n";
+        echo "Performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        // Timeout should be close to requested timeout (100ms) but not much longer
+        $this->assertGreaterThan(90.0, $stats['avg'], 'Timeout too fast - should wait approximately 100ms');
+        $this->assertLessThan(150.0, $stats['avg'], 'Timeout too slow - should be close to 100ms');
+
+        // Timeouts should be consistent
+        $this->assertLessThan(30.0, $stats['stddev'], 'Timeout timing too inconsistent');
+    }
+
+    public function testLockCleanupPerformance(): void
+    {
+        $expiredLockCount = 500;
+        $validLockCount = 100;
+
+        // Create expired locks
+        $pdo = $this->database->getConnection();
+        $expiredTime = (new \DateTimeImmutable())->modify('-1 hour');
+
+        for ($i = 0; $i < $expiredLockCount; $i++) {
+            $pdo->exec(sprintf(
+                "INSERT INTO distributed_locks (lock_key, owner_id, acquired_at, expires_at) VALUES ('expired_%d', 'owner_%d', '%s', '%s')",
+                $i,
+                $i,
+                $expiredTime->format('Y-m-d H:i:s'),
+                $expiredTime->format('Y-m-d H:i:s')
+            ));
+        }
+
+        // Create valid locks
+        $validTime = (new \DateTimeImmutable())->modify('+1 hour');
+        for ($i = 0; $i < $validLockCount; $i++) {
+            $pdo->exec(sprintf(
+                "INSERT INTO distributed_locks (lock_key, owner_id, acquired_at, expires_at) VALUES ('valid_%d', 'owner_%d', '%s', '%s')",
+                $i,
+                $i,
+                $validTime->format('Y-m-d H:i:s'),
+                $validTime->format('Y-m-d H:i:s')
+            ));
+        }
+
+        // Measure cleanup performance
+        $cleanupTime = PerformanceTestHelper::measureTime(function() {
+            $this->lockService->cleanupExpiredLocks();
+        });
+
+        // Verify cleanup results
+        $remaining = $pdo->query('SELECT COUNT(*) FROM distributed_locks')->fetchColumn();
+
+        echo "\nLock Cleanup Performance Results:\n";
+        echo "Expired locks created: {$expiredLockCount}\n";
+        echo "Valid locks created: {$validLockCount}\n";
+        echo "Locks remaining after cleanup: {$remaining}\n";
+        echo "Cleanup time: {$cleanupTime}ms\n";
+
+        $this->assertEquals($validLockCount, $remaining, 'Should only clean up expired locks');
+        $this->assertLessThan(100.0, $cleanupTime, 'Lock cleanup should complete within 100ms');
+
+        // Test cleanup performance with larger dataset
+        $this->cleanupTestData();
+
+        // Create many more expired locks
+        $largeExpiredCount = 5000;
+        for ($i = 0; $i < $largeExpiredCount; $i++) {
+            $pdo->exec(sprintf(
+                "INSERT INTO distributed_locks (lock_key, owner_id, acquired_at, expires_at) VALUES ('large_expired_%d', 'owner_%d', '%s', '%s')",
+                $i,
+                $i,
+                $expiredTime->format('Y-m-d H:i:s'),
+                $expiredTime->format('Y-m-d H:i:s')
+            ));
+        }
+
+        $largeCleanupTime = PerformanceTestHelper::measureTime(function() {
+            $this->lockService->cleanupExpiredLocks();
+        });
+
+        echo "Large cleanup ({$largeExpiredCount} locks): {$largeCleanupTime}ms\n";
+
+        $this->assertLessThan(500.0, $largeCleanupTime, 'Large cleanup should complete within 500ms');
+    }
+
+    public function testHighThroughputLockOperations(): void
+    {
+        $operationsPerSecond = 500;
+        $testDuration = 10; // seconds
+        $totalOperations = $operationsPerSecond * $testDuration;
+
+        echo "\nHigh Throughput Lock Operations Test:\n";
+        echo "Target: {$operationsPerSecond} operations/second for {$testDuration} seconds\n";
+
+        $loadResult = PerformanceTestHelper::simulateLoad(
+            function($index) {
+                $lockKey = new LockKey("throughput_lock_{$index}");
+                $owner = new LockOwner("owner_{$index}");
+
+                // Acquire and immediately release
+                $acquired = $this->lockService->acquire($lockKey, $owner, 5);
+                if ($acquired) {
+                    $this->lockService->release($lockKey, $owner);
+                    return true;
+                }
+                return false;
+            },
+            $totalOperations,
+            25, // Moderate concurrency
+            $testDuration
+        );
+
+        $actualThroughput = $loadResult['throughput_ops_per_sec'];
+        $operationTimes = array_column($loadResult['results'], 'time_ms');
+        $stats = PerformanceTestHelper::calculateStatistics($operationTimes);
+
+        $successfulOperations = count(array_filter(
+            array_column($loadResult['results'], 'result'),
+            fn($result) => $result['result'] === true
+        ));
+
+        echo "Actual Throughput: {$actualThroughput} operations/second\n";
+        echo "Successful operations: {$successfulOperations}\n";
+        echo "Operation Performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        // Should achieve at least 70% of target throughput
+        $this->assertGreaterThan(
+            $operationsPerSecond * 0.7,
+            $actualThroughput,
+            'High throughput lock operations below 70% of target'
+        );
+
+        // Most operations should succeed
+        $successRate = $successfulOperations / $loadResult['operations_completed'] * 100;
+        $this->assertGreaterThan(95.0, $successRate, 'Lock operation success rate too low');
+
+        // Operation times should remain reasonable
+        $this->assertLessThan(20.0, $stats['avg'], 'Average operation time too high under load');
+        $this->assertLessThan(100.0, $stats['p95'], 'P95 operation time too high under load');
+    }
+
+    public function testLockRetryPerformance(): void
+    {
+        $lockKey = new LockKey('retry_lock');
+        $owner1 = new LockOwner('blocking_owner');
+        $owner2 = new LockOwner('retry_owner');
+
+        // First owner acquires lock for a short time
+        $this->lockService->acquire($lockKey, $owner1, 60);
+
+        // Schedule lock release after 200ms
+        $releaseTime = microtime(true) + 0.2;
+
+        $retryAttempts = [];
+        $maxRetries = 50;
+        $retryDelay = 50; // 50ms between retries
+
+        for ($i = 0; $i < $maxRetries; $i++) {
+            $startTime = microtime(true);
+
+            // Release the lock when it's time
+            if ($startTime >= $releaseTime && $this->lockService->isLocked($lockKey)) {
+                $this->lockService->release($lockKey, $owner1);
+            }
+
+            $result = PerformanceTestHelper::measureTimeWithResult(function() use ($lockKey, $owner2) {
+                return $this->lockService->acquire($lockKey, $owner2, 0.01); // 10ms timeout
+            });
+
+            $retryAttempts[] = [
+                'time_ms' => $result['time_ms'],
+                'success' => $result['result']
+            ];
+
+            if ($result['result']) {
+                // Successfully acquired, release it and stop
+                $this->lockService->release($lockKey, $owner2);
+                break;
+            }
+
+            usleep($retryDelay * 1000); // Convert to microseconds
+        }
+
+        $retryTimes = array_column($retryAttempts, 'time_ms');
+        $stats = PerformanceTestHelper::calculateStatistics($retryTimes);
+
+        $successfulAttempt = array_search(true, array_column($retryAttempts, 'success'));
+        $attemptsUntilSuccess = $successfulAttempt !== false ? $successfulAttempt + 1 : $maxRetries;
+
+        echo "\nLock Retry Performance Results:\n";
+        echo "Attempts until success: {$attemptsUntilSuccess}\n";
+        echo "Retry performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        // Should eventually succeed
+        $this->assertNotFalse($successfulAttempt, 'Lock retry should eventually succeed');
+
+        // Retry attempts should be fast (mostly just timeout delays)
+        $this->assertLessThan(20.0, $stats['avg'], 'Retry attempts taking too long');
+    }
+
+    private function createTestDatabase(): DatabaseManager
+    {
+        $pdo = new \PDO('sqlite::memory:');
+        $pdo->setAttribute(\PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION);
+
+        $pdo->exec('
+            CREATE TABLE distributed_locks (
+                lock_key TEXT PRIMARY KEY,
+                owner_id TEXT NOT NULL,
+                acquired_at TEXT NOT NULL,
+                expires_at TEXT NOT NULL
+            )
+        ');
+
+        // Performance-optimized indexes
+        $pdo->exec('CREATE INDEX idx_locks_expires ON distributed_locks(expires_at)');
+        $pdo->exec('CREATE INDEX idx_locks_owner ON distributed_locks(owner_id)');
+
+        return new DatabaseManager($pdo);
+    }
+
+    private function cleanupTestData(): void
+    {
+        $pdo = $this->database->getConnection();
+        $pdo->exec('DELETE FROM distributed_locks');
+    }
+}

tests/Framework/Queue/Performance/FailoverPerformanceTest.php

@@ -0,0 +1,524 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Queue\Performance;
+
+use App\Framework\Database\DatabaseManager;
+use App\Framework\Queue\Distribution\JobDistributionService;
+use App\Framework\Queue\Failover\FailoverRecoveryService;
+use App\Framework\Queue\Health\WorkerHealthCheckService;
+use App\Framework\Queue\Jobs\JobStatus;
+use App\Framework\Queue\Workers\WorkerRegistry;
+use App\Framework\Queue\Workers\WorkerStatus;
+use PHPUnit\Framework\TestCase;
+
+final class FailoverPerformanceTest extends TestCase
+{
+    private DatabaseManager $database;
+    private WorkerRegistry $workerRegistry;
+    private WorkerHealthCheckService $healthCheckService;
+    private FailoverRecoveryService $failoverService;
+    private JobDistributionService $distributionService;
+
+    protected function setUp(): void
+    {
+        $this->database = $this->createTestDatabase();
+        $this->workerRegistry = new WorkerRegistry($this->database);
+        $this->healthCheckService = new WorkerHealthCheckService(
+            $this->database,
+            $this->workerRegistry
+        );
+        $this->failoverService = new FailoverRecoveryService(
+            $this->database,
+            $this->workerRegistry
+        );
+        $this->distributionService = new JobDistributionService(
+            $this->database,
+            $this->workerRegistry
+        );
+
+        $this->cleanupTestData();
+        PerformanceTestHelper::warmupDatabase($this->database->getConnection());
+    }
+
+    protected function tearDown(): void
+    {
+        $this->cleanupTestData();
+    }
+
+    public function testWorkerFailureDetectionTime(): void
+    {
+        // Create workers with recent heartbeats
+        $workers = $this->createHealthyWorkers(10);
+        $this->registerWorkers($workers);
+
+        // Simulate worker failures by setting old heartbeats
+        $failedWorkerIds = [];
+        $currentTime = new \DateTimeImmutable();
+
+        // Make 3 workers appear failed (no heartbeat for 2 minutes)
+        for ($i = 0; $i < 3; $i++) {
+            $workerId = $workers[$i]->id->toString();
+            $failedWorkerIds[] = $workerId;
+
+            $this->updateWorkerHeartbeat($workerId, $currentTime->modify('-2 minutes'));
+        }
+
+        // Measure failure detection time
+        $detectionTimes = [];
+        $iterations = 10;
+
+        for ($i = 0; $i < $iterations; $i++) {
+            $time = PerformanceTestHelper::measureTime(function() {
+                return $this->healthCheckService->checkAllWorkers();
+            });
+            $detectionTimes[] = $time;
+
+            // Brief pause between checks
+            usleep(10000); // 10ms
+        }
+
+        $stats = PerformanceTestHelper::calculateStatistics($detectionTimes);
+
+        // Verify failed workers were detected
+        $failedWorkers = $this->workerRegistry->getWorkersByStatus(WorkerStatus::FAILED);
+        $detectedFailures = array_map(fn($w) => $w->id->toString(), $failedWorkers);
+
+        echo "\nWorker Failure Detection Results:\n";
+        echo "Workers created: " . count($workers) . "\n";
+        echo "Workers failed: " . count($failedWorkerIds) . "\n";
+        echo "Failures detected: " . count($detectedFailures) . "\n";
+        echo "Detection performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        // All failed workers should be detected
+        foreach ($failedWorkerIds as $failedId) {
+            $this->assertContains($failedId, $detectedFailures, "Failed worker {$failedId} not detected");
+        }
+
+        // Detection should be fast
+        $this->assertLessThan(50.0, $stats['avg'], 'Average failure detection time too slow');
+        $this->assertLessThan(100.0, $stats['p95'], 'P95 failure detection time too slow');
+
+        PerformanceTestHelper::assertPerformance(
+            $detectionTimes,
+            50.0,
+            100.0,
+            'Worker failure detection'
+        );
+    }
+
+    public function testJobReassignmentSpeed(): void
+    {
+        // Create workers and assign jobs
+        $workers = $this->createHealthyWorkers(5);
+        $this->registerWorkers($workers);
+
+        // Distribute jobs to workers
+        $jobs = PerformanceTestHelper::createBulkJobs(50);
+        $assignedJobs = [];
+
+        foreach ($jobs as $job) {
+            $assignedWorker = $this->distributionService->distributeJob($job);
+            if ($assignedWorker) {
+                $assignedJobs[] = [
+                    'job' => $job,
+                    'worker_id' => $assignedWorker->id->toString()
+                ];
+            }
+        }
+
+        // Simulate worker failure
+        $failedWorkerId = $workers[0]->id->toString();
+        $this->updateWorkerStatus($failedWorkerId, WorkerStatus::FAILED);
+
+        // Find jobs assigned to failed worker
+        $jobsToReassign = array_filter(
+            $assignedJobs,
+            fn($item) => $item['worker_id'] === $failedWorkerId
+        );
+
+        echo "\nJob Reassignment Test:\n";
+        echo "Total jobs: " . count($assignedJobs) . "\n";
+        echo "Jobs to reassign: " . count($jobsToReassign) . "\n";
+
+        // Measure job reassignment performance
+        $reassignmentTime = PerformanceTestHelper::measureTime(function() use ($failedWorkerId) {
+            return $this->failoverService->reassignFailedWorkerJobs($failedWorkerId);
+        });
+
+        echo "Reassignment time: {$reassignmentTime}ms\n";
+
+        // Verify jobs were reassigned
+        $reassignedCount = $this->countJobsReassignedFrom($failedWorkerId);
+        echo "Jobs successfully reassigned: {$reassignedCount}\n";
+
+        // Job reassignment should be fast
+        $this->assertLessThan(200.0, $reassignmentTime, 'Job reassignment took too long');
+
+        // All jobs should be reassigned
+        $this->assertEquals(
+            count($jobsToReassign),
+            $reassignedCount,
+            'Not all jobs were reassigned'
+        );
+
+        // Performance should scale reasonably with job count
+        $averageTimePerJob = $reassignmentTime / max(1, count($jobsToReassign));
+        $this->assertLessThan(5.0, $averageTimePerJob, 'Reassignment time per job too high');
+    }
+
+    public function testSystemRecoveryTime(): void
+    {
+        // Create a system with multiple workers and jobs
+        $workers = $this->createHealthyWorkers(8);
+        $this->registerWorkers($workers);
+
+        // Distribute many jobs
+        $jobs = PerformanceTestHelper::createBulkJobs(200);
+        foreach ($jobs as $job) {
+            $this->distributionService->distributeJob($job);
+        }
+
+        // Simulate multiple worker failures
+        $failedWorkerIds = [
+            $workers[0]->id->toString(),
+            $workers[1]->id->toString(),
+            $workers[2]->id->toString()
+        ];
+
+        foreach ($failedWorkerIds as $workerId) {
+            $this->updateWorkerStatus($workerId, WorkerStatus::FAILED);
+        }
+
+        echo "\nSystem Recovery Test:\n";
+        echo "Total workers: " . count($workers) . "\n";
+        echo "Failed workers: " . count($failedWorkerIds) . "\n";
+        echo "Total jobs: " . count($jobs) . "\n";
+
+        // Measure full system recovery time
+        $recoveryTime = PerformanceTestHelper::measureTime(function() {
+            return $this->failoverService->performFullSystemRecovery();
+        });
+
+        echo "Full recovery time: {$recoveryTime}ms\n";
+
+        // Verify system state after recovery
+        $activeWorkers = $this->workerRegistry->getAvailableWorkers();
+        $pendingJobs = $this->countJobsByStatus(JobStatus::PENDING);
+        $processingJobs = $this->countJobsByStatus(JobStatus::PROCESSING);
+
+        echo "Active workers after recovery: " . count($activeWorkers) . "\n";
+        echo "Pending jobs: {$pendingJobs}\n";
+        echo "Processing jobs: {$processingJobs}\n";
+
+        // Recovery should complete within reasonable time
+        $this->assertLessThan(5000.0, $recoveryTime, 'System recovery took too long (>5 seconds)');
+
+        // Should have remaining active workers
+        $this->assertGreaterThan(0, count($activeWorkers), 'No workers available after recovery');
+
+        // Jobs should be properly redistributed
+        $this->assertGreaterThan(0, $pendingJobs + $processingJobs, 'No jobs available after recovery');
+    }
+
+    public function testPartialFailureGracefulDegradation(): void
+    {
+        // Create system with mixed capacity workers
+        $workers = [
+            PerformanceTestHelper::createTestWorker('high_capacity_1', 50),
+            PerformanceTestHelper::createTestWorker('high_capacity_2', 50),
+            PerformanceTestHelper::createTestWorker('medium_capacity_1', 20),
+            PerformanceTestHelper::createTestWorker('medium_capacity_2', 20),
+            PerformanceTestHelper::createTestWorker('low_capacity_1', 10),
+            PerformanceTestHelper::createTestWorker('low_capacity_2', 10)
+        ];
+
+        $this->registerWorkers($workers);
+
+        // Measure baseline throughput
+        $baselineThroughput = $this->measureDistributionThroughput(100, 'baseline');
+
+        // Fail high capacity workers
+        $this->updateWorkerStatus('high_capacity_1', WorkerStatus::FAILED);
+        $this->updateWorkerStatus('high_capacity_2', WorkerStatus::FAILED);
+
+        $degradedThroughput = $this->measureDistributionThroughput(100, 'degraded');
+
+        // Fail medium capacity workers too
+        $this->updateWorkerStatus('medium_capacity_1', WorkerStatus::FAILED);
+        $this->updateWorkerStatus('medium_capacity_2', WorkerStatus::FAILED);
+
+        $severeDegradationThroughput = $this->measureDistributionThroughput(100, 'severe');
+
+        echo "\nGraceful Degradation Results:\n";
+        echo "Baseline throughput: {$baselineThroughput} jobs/sec\n";
+        echo "After high-capacity failure: {$degradedThroughput} jobs/sec\n";
+        echo "After medium-capacity failure: {$severeDegradationThroughput} jobs/sec\n";
+
+        $degradationRatio1 = $degradedThroughput / $baselineThroughput;
+        $degradationRatio2 = $severeDegradationThroughput / $baselineThroughput;
+
+        echo "First degradation ratio: " . round($degradationRatio1 * 100, 1) . "%\n";
+        echo "Severe degradation ratio: " . round($degradationRatio2 * 100, 1) . "%\n";
+
+        // System should degrade gracefully
+        $this->assertGreaterThan(0.3, $degradationRatio1, 'Degradation too severe after high-capacity failure');
+        $this->assertGreaterThan(0.1, $degradationRatio2, 'System should still function with low-capacity workers');
+
+        // Should maintain some reasonable performance
+        $this->assertGreaterThan(10, $severeDegradationThroughput, 'Minimum throughput too low');
+    }
+
+    public function testFailoverUnderHighLoad(): void
+    {
+        // Create workers under high load
+        $workers = $this->createHealthyWorkers(6);
+        $this->registerWorkers($workers);
+
+        // Start high load job distribution
+        $jobsDistributed = 0;
+        $distributionErrors = 0;
+        $startTime = microtime(true);
+        $testDuration = 20; // 20 seconds
+        $endTime = $startTime + $testDuration;
+
+        $distributionTimes = [];
+
+        // Simulate ongoing load
+        while (microtime(true) < $endTime) {
+            $job = PerformanceTestHelper::createTestJob("load_job_{$jobsDistributed}");
+
+            $result = PerformanceTestHelper::measureTimeWithResult(function() use ($job) {
+                try {
+                    return $this->distributionService->distributeJob($job);
+                } catch (\Exception $e) {
+                    return null;
+                }
+            });
+
+            $distributionTimes[] = $result['time_ms'];
+
+            if ($result['result'] !== null) {
+                $jobsDistributed++;
+            } else {
+                $distributionErrors++;
+            }
+
+            // Simulate worker failure at 1/3 of test duration
+            if (microtime(true) > $startTime + ($testDuration / 3) &&
+                microtime(true) < $startTime + ($testDuration / 3) + 1) {
+
+                // Fail 2 workers during high load
+                $this->updateWorkerStatus($workers[0]->id->toString(), WorkerStatus::FAILED);
+                $this->updateWorkerStatus($workers[1]->id->toString(), WorkerStatus::FAILED);
+
+                // Trigger recovery
+                $this->failoverService->performFullSystemRecovery();
+            }
+
+            usleep(5000); // 5ms between jobs
+        }
+
+        $actualDuration = microtime(true) - $startTime;
+        $throughput = $jobsDistributed / $actualDuration;
+        $errorRate = $distributionErrors / ($jobsDistributed + $distributionErrors) * 100;
+
+        $stats = PerformanceTestHelper::calculateStatistics($distributionTimes);
+
+        echo "\nFailover Under High Load Results:\n";
+        echo "Test duration: {$actualDuration} seconds\n";
+        echo "Jobs distributed: {$jobsDistributed}\n";
+        echo "Distribution errors: {$distributionErrors}\n";
+        echo "Throughput: {$throughput} jobs/sec\n";
+        echo "Error rate: {$errorRate}%\n";
+        echo "Distribution performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        // System should maintain reasonable performance during failover
+        $this->assertGreaterThan(20, $throughput, 'Throughput too low during failover');
+        $this->assertLessThan(10.0, $errorRate, 'Error rate too high during failover');
+
+        // Distribution times may be higher during failover but should recover
+        $this->assertLessThan(100.0, $stats['avg'], 'Average distribution time too high during failover');
+    }
+
+    public function testWorkerRecoveryPerformance(): void
+    {
+        // Create workers, some initially failed
+        $workers = $this->createHealthyWorkers(8);
+        $this->registerWorkers($workers);
+
+        // Mark some workers as failed
+        $failedWorkerIds = [
+            $workers[0]->id->toString(),
+            $workers[1]->id->toString(),
+            $workers[2]->id->toString()
+        ];
+
+        foreach ($failedWorkerIds as $workerId) {
+            $this->updateWorkerStatus($workerId, WorkerStatus::FAILED);
+        }
+
+        echo "\nWorker Recovery Performance Test:\n";
+        echo "Failed workers: " . count($failedWorkerIds) . "\n";
+
+        // Simulate workers coming back online
+        $recoveryTimes = [];
+
+        foreach ($failedWorkerIds as $workerId) {
+            // Update heartbeat to simulate worker recovery
+            $this->updateWorkerHeartbeat($workerId, new \DateTimeImmutable());
+
+            $recoveryTime = PerformanceTestHelper::measureTime(function() use ($workerId) {
+                // Simulate health check detecting recovery
+                $this->healthCheckService->checkWorker($workerId);
+
+                // Trigger recovery process
+                return $this->failoverService->recoverWorker($workerId);
+            });
+
+            $recoveryTimes[] = $recoveryTime;
+        }
+
+        $stats = PerformanceTestHelper::calculateStatistics($recoveryTimes);
+
+        echo "Worker recovery performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        // Verify workers are back online
+        $availableWorkers = $this->workerRegistry->getAvailableWorkers();
+        $availableCount = count($availableWorkers);
+
+        echo "Workers available after recovery: {$availableCount}\n";
+
+        // Recovery should be fast
+        $this->assertLessThan(100.0, $stats['avg'], 'Average worker recovery time too slow');
+        $this->assertLessThan(200.0, $stats['p95'], 'P95 worker recovery time too slow');
+
+        // All workers should be recovered
+        $this->assertGreaterThanOrEqual(
+            count($workers),
+            $availableCount,
+            'Not all workers recovered successfully'
+        );
+
+        PerformanceTestHelper::assertPerformance(
+            $recoveryTimes,
+            100.0,
+            200.0,
+            'Worker recovery'
+        );
+    }
+
+    private function measureDistributionThroughput(int $jobCount, string $label): float
+    {
+        $jobs = PerformanceTestHelper::createBulkJobs($jobCount);
+        $startTime = microtime(true);
+
+        foreach ($jobs as $job) {
+            $this->distributionService->distributeJob($job);
+        }
+
+        $endTime = microtime(true);
+        $duration = $endTime - $startTime;
+
+        return round($jobCount / $duration, 1);
+    }
+
+    private function createHealthyWorkers(int $count): array
+    {
+        $workers = [];
+        for ($i = 1; $i <= $count; $i++) {
+            $workers[] = PerformanceTestHelper::createTestWorker(
+                "healthy_worker_{$i}",
+                20,
+                WorkerStatus::AVAILABLE
+            );
+        }
+        return $workers;
+    }
+
+    private function registerWorkers(array $workers): void
+    {
+        foreach ($workers as $worker) {
+            $this->workerRegistry->registerWorker($worker);
+        }
+    }
+
+    private function updateWorkerHeartbeat(string $workerId, \DateTimeImmutable $heartbeat): void
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('UPDATE workers SET last_heartbeat = ? WHERE id = ?');
+        $stmt->execute([$heartbeat->format('Y-m-d H:i:s'), $workerId]);
+    }
+
+    private function updateWorkerStatus(string $workerId, WorkerStatus $status): void
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('UPDATE workers SET status = ? WHERE id = ?');
+        $stmt->execute([$status->value, $workerId]);
+    }
+
+    private function countJobsReassignedFrom(string $failedWorkerId): int
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('SELECT COUNT(*) FROM jobs WHERE worker_id != ? AND worker_id IS NOT NULL');
+        $stmt->execute([$failedWorkerId]);
+        return (int) $stmt->fetchColumn();
+    }
+
+    private function countJobsByStatus(JobStatus $status): int
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('SELECT COUNT(*) FROM jobs WHERE status = ?');
+        $stmt->execute([$status->value]);
+        return (int) $stmt->fetchColumn();
+    }
+
+    private function createTestDatabase(): DatabaseManager
+    {
+        $pdo = new \PDO('sqlite::memory:');
+        $pdo->setAttribute(\PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION);
+
+        $pdo->exec('
+            CREATE TABLE workers (
+                id TEXT PRIMARY KEY,
+                queue_names TEXT NOT NULL,
+                capacity INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                last_heartbeat TEXT NOT NULL,
+                metadata TEXT
+            )
+        ');
+
+        $pdo->exec('
+            CREATE TABLE jobs (
+                id TEXT PRIMARY KEY,
+                type TEXT NOT NULL,
+                payload TEXT NOT NULL,
+                queue_name TEXT NOT NULL,
+                priority INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                worker_id TEXT,
+                created_at TEXT NOT NULL,
+                started_at TEXT,
+                completed_at TEXT,
+                attempts INTEGER DEFAULT 0,
+                error_message TEXT
+            )
+        ');
+
+        // Performance indexes
+        $pdo->exec('CREATE INDEX idx_workers_status_heartbeat ON workers(status, last_heartbeat)');
+        $pdo->exec('CREATE INDEX idx_jobs_worker_status ON jobs(worker_id, status)');
+        $pdo->exec('CREATE INDEX idx_jobs_status_created ON jobs(status, created_at)');
+
+        return new DatabaseManager($pdo);
+    }
+
+    private function cleanupTestData(): void
+    {
+        $pdo = $this->database->getConnection();
+        $pdo->exec('DELETE FROM workers');
+        $pdo->exec('DELETE FROM jobs');
+    }
+}

tests/Framework/Queue/Performance/LoadBalancingPerformanceTest.php

@@ -0,0 +1,411 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Queue\Performance;
+
+use App\Framework\Database\DatabaseManager;
+use App\Framework\Queue\Distribution\JobDistributionService;
+use App\Framework\Queue\Distribution\LoadBalancer;
+use App\Framework\Queue\Jobs\JobPriority;
+use App\Framework\Queue\Queue\QueueName;
+use App\Framework\Queue\Workers\WorkerRegistry;
+use App\Framework\Queue\Workers\WorkerStatus;
+use PHPUnit\Framework\TestCase;
+
+final class LoadBalancingPerformanceTest extends TestCase
+{
+    private DatabaseManager $database;
+    private WorkerRegistry $workerRegistry;
+    private JobDistributionService $distributionService;
+    private LoadBalancer $loadBalancer;
+
+    protected function setUp(): void
+    {
+        $this->database = $this->createTestDatabase();
+        $this->workerRegistry = new WorkerRegistry($this->database);
+        $this->loadBalancer = new LoadBalancer($this->workerRegistry);
+        $this->distributionService = new JobDistributionService(
+            $this->database,
+            $this->workerRegistry
+        );
+
+        $this->cleanupTestData();
+        PerformanceTestHelper::warmupDatabase($this->database->getConnection());
+    }
+
+    protected function tearDown(): void
+    {
+        $this->cleanupTestData();
+    }
+
+    public function testWorkerSelectionLatency(): void
+    {
+        // Create workers with different loads
+        $workers = [
+            PerformanceTestHelper::createTestWorker('worker_1', 20),
+            PerformanceTestHelper::createTestWorker('worker_2', 15),
+            PerformanceTestHelper::createTestWorker('worker_3', 10),
+            PerformanceTestHelper::createTestWorker('worker_4', 25),
+            PerformanceTestHelper::createTestWorker('worker_5', 30)
+        ];
+
+        $this->registerWorkers($workers);
+
+        $selectionTimes = [];
+        $iterations = 1000;
+
+        for ($i = 0; $i < $iterations; $i++) {
+            $time = PerformanceTestHelper::measureTime(function() {
+                $this->loadBalancer->selectWorker(new QueueName('test_queue'));
+            });
+            $selectionTimes[] = $time;
+        }
+
+        $stats = PerformanceTestHelper::calculateStatistics($selectionTimes);
+
+        // Validate performance benchmarks
+        $this->assertLessThan(5.0, $stats['avg'], 'Average worker selection time exceeds 5ms');
+        $this->assertLessThan(10.0, $stats['p95'], 'P95 worker selection time exceeds 10ms');
+        $this->assertLessThan(20.0, $stats['p99'], 'P99 worker selection time exceeds 20ms');
+
+        echo "\nWorker Selection Latency Results:\n";
+        echo "Iterations: {$iterations}\n";
+        echo "Performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        PerformanceTestHelper::assertPerformance(
+            $selectionTimes,
+            5.0,
+            10.0,
+            'Worker selection'
+        );
+    }
+
+    public function testJobDistributionLatency(): void
+    {
+        $workers = $this->createBalancedWorkers(10, 20);
+        $this->registerWorkers($workers);
+
+        $distributionTimes = [];
+        $iterations = 500;
+
+        for ($i = 0; $i < $iterations; $i++) {
+            $job = PerformanceTestHelper::createTestJob("dist_job_{$i}");
+
+            $time = PerformanceTestHelper::measureTime(function() use ($job) {
+                $this->distributionService->distributeJob($job);
+            });
+
+            $distributionTimes[] = $time;
+        }
+
+        $stats = PerformanceTestHelper::calculateStatistics($distributionTimes);
+
+        // Validate performance benchmarks
+        $this->assertLessThan(10.0, $stats['avg'], 'Average job distribution time exceeds 10ms');
+        $this->assertLessThan(20.0, $stats['p95'], 'P95 job distribution time exceeds 20ms');
+        $this->assertLessThan(50.0, $stats['p99'], 'P99 job distribution time exceeds 50ms');
+
+        echo "\nJob Distribution Latency Results:\n";
+        echo "Iterations: {$iterations}\n";
+        echo "Performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        PerformanceTestHelper::assertPerformance(
+            $distributionTimes,
+            10.0,
+            20.0,
+            'Job distribution'
+        );
+    }
+
+    public function testHighThroughputDistribution(): void
+    {
+        $workers = $this->createBalancedWorkers(15, 25);
+        $this->registerWorkers($workers);
+
+        $jobsPerSecond = 1000;
+        $testDuration = 10; // seconds
+        $totalJobs = $jobsPerSecond * $testDuration;
+
+        echo "\nHigh Throughput Distribution Test:\n";
+        echo "Target: {$jobsPerSecond} jobs/second for {$testDuration} seconds\n";
+
+        $loadResult = PerformanceTestHelper::simulateLoad(
+            function($index) {
+                $job = PerformanceTestHelper::createTestJob("load_job_{$index}");
+                return $this->distributionService->distributeJob($job);
+            },
+            $totalJobs,
+            50, // High concurrency
+            $testDuration
+        );
+
+        $actualThroughput = $loadResult['throughput_ops_per_sec'];
+        $distributionTimes = array_column($loadResult['results'], 'time_ms');
+        $stats = PerformanceTestHelper::calculateStatistics($distributionTimes);
+
+        echo "Actual Throughput: {$actualThroughput} jobs/second\n";
+        echo "Distribution Performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        // Should achieve at least 80% of target throughput
+        $this->assertGreaterThan(
+            $jobsPerSecond * 0.8,
+            $actualThroughput,
+            'High throughput distribution below 80% of target'
+        );
+
+        // Distribution times should remain reasonable under high load
+        $this->assertLessThan(30.0, $stats['avg'], 'Average distribution time too high under load');
+        $this->assertLessThan(100.0, $stats['p95'], 'P95 distribution time too high under load');
+    }
+
+    public function testFairDistributionUnderLoad(): void
+    {
+        $workers = [
+            PerformanceTestHelper::createTestWorker('worker_1', 10),
+            PerformanceTestHelper::createTestWorker('worker_2', 20),
+            PerformanceTestHelper::createTestWorker('worker_3', 30),
+            PerformanceTestHelper::createTestWorker('worker_4', 15),
+            PerformanceTestHelper::createTestWorker('worker_5', 25)
+        ];
+
+        $this->registerWorkers($workers);
+
+        $jobCount = 1000;
+        $workerAssignments = [];
+
+        for ($i = 0; $i < $jobCount; $i++) {
+            $job = PerformanceTestHelper::createTestJob("fair_job_{$i}");
+            $selectedWorker = $this->distributionService->distributeJob($job);
+
+            if ($selectedWorker) {
+                $workerId = $selectedWorker->id->toString();
+                $workerAssignments[$workerId] = ($workerAssignments[$workerId] ?? 0) + 1;
+            }
+        }
+
+        echo "\nFair Distribution Results:\n";
+        $totalCapacity = array_sum(array_map(fn($w) => $w->capacity->value, $workers));
+
+        foreach ($workers as $worker) {
+            $workerId = $worker->id->toString();
+            $assignments = $workerAssignments[$workerId] ?? 0;
+            $expectedRatio = $worker->capacity->value / $totalCapacity;
+            $actualRatio = $assignments / $jobCount;
+            $efficiency = ($actualRatio / $expectedRatio) * 100;
+
+            echo sprintf(
+                "Worker %s: Capacity=%d, Assignments=%d, Expected=%.1f%%, Actual=%.1f%%, Efficiency=%.1f%%\n",
+                $workerId,
+                $worker->capacity->value,
+                $assignments,
+                $expectedRatio * 100,
+                $actualRatio * 100,
+                $efficiency
+            );
+
+            // Each worker should get jobs roughly proportional to their capacity
+            // Allow 20% variance for fair distribution
+            $this->assertGreaterThan(
+                80.0,
+                $efficiency,
+                "Worker {$workerId} received fewer jobs than expected (efficiency: {$efficiency}%)"
+            );
+
+            $this->assertLessThan(
+                120.0,
+                $efficiency,
+                "Worker {$workerId} received more jobs than expected (efficiency: {$efficiency}%)"
+            );
+        }
+    }
+
+    public function testMixedCapacityLoadBalancing(): void
+    {
+        // Create workers with very different capacities
+        $workers = [
+            PerformanceTestHelper::createTestWorker('small_worker', 5),
+            PerformanceTestHelper::createTestWorker('medium_worker_1', 15),
+            PerformanceTestHelper::createTestWorker('medium_worker_2', 20),
+            PerformanceTestHelper::createTestWorker('large_worker', 50),
+            PerformanceTestHelper::createTestWorker('xlarge_worker', 100)
+        ];
+
+        $this->registerWorkers($workers);
+
+        $selectionTimes = [];
+        $iterations = 500;
+
+        for ($i = 0; $i < $iterations; $i++) {
+            $time = PerformanceTestHelper::measureTime(function() {
+                $this->loadBalancer->selectWorker(new QueueName('test_queue'));
+            });
+            $selectionTimes[] = $time;
+        }
+
+        $stats = PerformanceTestHelper::calculateStatistics($selectionTimes);
+
+        echo "\nMixed Capacity Load Balancing Results:\n";
+        echo "Worker capacities: 5, 15, 20, 50, 100\n";
+        echo "Selection performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        // Selection should still be fast even with mixed capacities
+        $this->assertLessThan(8.0, $stats['avg'], 'Mixed capacity selection average time too high');
+        $this->assertLessThan(15.0, $stats['p95'], 'Mixed capacity selection P95 time too high');
+    }
+
+    public function testPriorityJobDistribution(): void
+    {
+        $workers = $this->createBalancedWorkers(8, 15);
+        $this->registerWorkers($workers);
+
+        $priorities = [JobPriority::LOW, JobPriority::NORMAL, JobPriority::HIGH, JobPriority::CRITICAL];
+        $distributionTimes = [];
+
+        foreach ($priorities as $priority) {
+            $iterationsPerPriority = 100;
+
+            for ($i = 0; $i < $iterationsPerPriority; $i++) {
+                $job = PerformanceTestHelper::createTestJob(
+                    "priority_job_{$priority->value}_{$i}",
+                    $priority
+                );
+
+                $time = PerformanceTestHelper::measureTime(function() use ($job) {
+                    $this->distributionService->distributeJob($job);
+                });
+
+                $distributionTimes[$priority->value][] = $time;
+            }
+        }
+
+        echo "\nPriority Job Distribution Results:\n";
+
+        foreach ($priorities as $priority) {
+            $stats = PerformanceTestHelper::calculateStatistics($distributionTimes[$priority->value]);
+            echo "Priority {$priority->value}: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+            // All priorities should have similar distribution performance
+            $this->assertLessThan(15.0, $stats['avg'], "Priority {$priority->value} distribution too slow");
+        }
+    }
+
+    public function testWorkerOverloadHandling(): void
+    {
+        // Create workers that will quickly become overloaded
+        $workers = [
+            PerformanceTestHelper::createTestWorker('worker_1', 2),
+            PerformanceTestHelper::createTestWorker('worker_2', 3),
+            PerformanceTestHelper::createTestWorker('worker_3', 2)
+        ];
+
+        $this->registerWorkers($workers);
+
+        $distributionTimes = [];
+        $successfulDistributions = 0;
+        $failedDistributions = 0;
+
+        // Try to distribute more jobs than total worker capacity
+        $jobCount = 20; // Total capacity is only 7
+
+        for ($i = 0; $i < $jobCount; $i++) {
+            $job = PerformanceTestHelper::createTestJob("overload_job_{$i}");
+
+            $result = PerformanceTestHelper::measureTimeWithResult(function() use ($job) {
+                return $this->distributionService->distributeJob($job);
+            });
+
+            $distributionTimes[] = $result['time_ms'];
+
+            if ($result['result'] !== null) {
+                $successfulDistributions++;
+            } else {
+                $failedDistributions++;
+            }
+        }
+
+        $stats = PerformanceTestHelper::calculateStatistics($distributionTimes);
+
+        echo "\nWorker Overload Handling Results:\n";
+        echo "Total jobs: {$jobCount}\n";
+        echo "Successful distributions: {$successfulDistributions}\n";
+        echo "Failed distributions: {$failedDistributions}\n";
+        echo "Distribution performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        // Should successfully distribute up to total capacity
+        $this->assertGreaterThanOrEqual(7, $successfulDistributions, 'Should distribute at least 7 jobs');
+
+        // Distribution times should remain reasonable even when workers are overloaded
+        $this->assertLessThan(20.0, $stats['avg'], 'Distribution time too high during overload');
+    }
+
+    private function createBalancedWorkers(int $count, int $capacity): array
+    {
+        $workers = [];
+        for ($i = 1; $i <= $count; $i++) {
+            $workers[] = PerformanceTestHelper::createTestWorker(
+                "balanced_worker_{$i}",
+                $capacity,
+                WorkerStatus::AVAILABLE
+            );
+        }
+        return $workers;
+    }
+
+    private function registerWorkers(array $workers): void
+    {
+        foreach ($workers as $worker) {
+            $this->workerRegistry->registerWorker($worker);
+        }
+    }
+
+    private function createTestDatabase(): DatabaseManager
+    {
+        $pdo = new \PDO('sqlite::memory:');
+        $pdo->setAttribute(\PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION);
+
+        // Create required tables with indexes for performance
+        $pdo->exec('
+            CREATE TABLE workers (
+                id TEXT PRIMARY KEY,
+                queue_names TEXT NOT NULL,
+                capacity INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                last_heartbeat TEXT NOT NULL,
+                metadata TEXT
+            )
+        ');
+
+        $pdo->exec('
+            CREATE TABLE jobs (
+                id TEXT PRIMARY KEY,
+                type TEXT NOT NULL,
+                payload TEXT NOT NULL,
+                queue_name TEXT NOT NULL,
+                priority INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                worker_id TEXT,
+                created_at TEXT NOT NULL,
+                started_at TEXT,
+                completed_at TEXT,
+                attempts INTEGER DEFAULT 0,
+                error_message TEXT
+            )
+        ');
+
+        // Performance-optimized indexes
+        $pdo->exec('CREATE INDEX idx_workers_status_capacity ON workers(status, capacity DESC)');
+        $pdo->exec('CREATE INDEX idx_workers_queue_status ON workers(queue_names, status)');
+        $pdo->exec('CREATE INDEX idx_jobs_worker_status ON jobs(worker_id, status)');
+        $pdo->exec('CREATE INDEX idx_jobs_priority_created ON jobs(priority DESC, created_at)');
+
+        return new DatabaseManager($pdo);
+    }
+
+    private function cleanupTestData(): void
+    {
+        $pdo = $this->database->getConnection();
+        $pdo->exec('DELETE FROM workers');
+        $pdo->exec('DELETE FROM jobs');
+    }
+}

tests/Framework/Queue/Performance/MultiWorkerThroughputTest.php

@@ -0,0 +1,386 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Queue\Performance;
+
+use App\Framework\Database\DatabaseManager;
+use App\Framework\Queue\Distribution\JobDistributionService;
+use App\Framework\Queue\Jobs\Job;
+use App\Framework\Queue\Jobs\JobPriority;
+use App\Framework\Queue\Jobs\JobStatus;
+use App\Framework\Queue\Queue\QueueName;
+use App\Framework\Queue\Workers\Worker;
+use App\Framework\Queue\Workers\WorkerCapacity;
+use App\Framework\Queue\Workers\WorkerId;
+use App\Framework\Queue\Workers\WorkerRegistry;
+use App\Framework\Queue\Workers\WorkerStatus;
+use PHPUnit\Framework\TestCase;
+
+final class MultiWorkerThroughputTest extends TestCase
+{
+    private DatabaseManager $database;
+    private WorkerRegistry $workerRegistry;
+    private JobDistributionService $distributionService;
+
+    protected function setUp(): void
+    {
+        $this->database = $this->createTestDatabase();
+        $this->workerRegistry = new WorkerRegistry($this->database);
+        $this->distributionService = new JobDistributionService(
+            $this->database,
+            $this->workerRegistry
+        );
+
+        // Clean up any existing test data
+        $this->cleanupTestData();
+
+        // Warm up database connections
+        PerformanceTestHelper::warmupDatabase($this->database->getConnection());
+    }
+
+    protected function tearDown(): void
+    {
+        $this->cleanupTestData();
+    }
+
+    public function testSingleWorkerThroughput(): void
+    {
+        $workerCount = 1;
+        $jobCount = 100;
+        $workers = $this->createWorkers($workerCount, 50); // High capacity worker
+
+        $result = $this->measureThroughput($workers, $jobCount);
+
+        $this->assertGreaterThan(
+            50, // At least 50 jobs/second with single worker
+            $result['throughput'],
+            'Single worker throughput below expected minimum'
+        );
+
+        echo "\nSingle Worker Throughput Results:\n";
+        echo "Throughput: {$result['throughput']} jobs/second\n";
+        echo "Total Time: {$result['total_time_ms']}ms\n";
+        echo "Average Job Distribution Time: " .
+             PerformanceTestHelper::formatStatistics($result['distribution_stats']) . "\n";
+    }
+
+    public function testFiveWorkerThroughput(): void
+    {
+        $workerCount = 5;
+        $jobCount = 500;
+        $workers = $this->createWorkers($workerCount, 20);
+
+        $result = $this->measureThroughput($workers, $jobCount);
+
+        $this->assertGreaterThan(
+            200, // Should achieve at least 200 jobs/second with 5 workers
+            $result['throughput'],
+            'Five worker throughput below expected minimum'
+        );
+
+        echo "\nFive Worker Throughput Results:\n";
+        echo "Throughput: {$result['throughput']} jobs/second\n";
+        echo "Total Time: {$result['total_time_ms']}ms\n";
+        echo "Average Job Distribution Time: " .
+             PerformanceTestHelper::formatStatistics($result['distribution_stats']) . "\n";
+    }
+
+    public function testTenWorkerThroughput(): void
+    {
+        $workerCount = 10;
+        $jobCount = 1000;
+        $workers = $this->createWorkers($workerCount, 15);
+
+        $result = $this->measureThroughput($workers, $jobCount);
+
+        $this->assertGreaterThan(
+            350, // Should achieve at least 350 jobs/second with 10 workers
+            $result['throughput'],
+            'Ten worker throughput below expected minimum'
+        );
+
+        echo "\nTen Worker Throughput Results:\n";
+        echo "Throughput: {$result['throughput']} jobs/second\n";
+        echo "Total Time: {$result['total_time_ms']}ms\n";
+        echo "Average Job Distribution Time: " .
+             PerformanceTestHelper::formatStatistics($result['distribution_stats']) . "\n";
+    }
+
+    public function testTwentyWorkerThroughput(): void
+    {
+        $workerCount = 20;
+        $jobCount = 2000;
+        $workers = $this->createWorkers($workerCount, 10);
+
+        $result = $this->measureThroughput($workers, $jobCount);
+
+        $this->assertGreaterThan(
+            600, // Should achieve at least 600 jobs/second with 20 workers
+            $result['throughput'],
+            'Twenty worker throughput below expected minimum'
+        );
+
+        echo "\nTwenty Worker Throughput Results:\n";
+        echo "Throughput: {$result['throughput']} jobs/second\n";
+        echo "Total Time: {$result['total_time_ms']}ms\n";
+        echo "Average Job Distribution Time: " .
+             PerformanceTestHelper::formatStatistics($result['distribution_stats']) . "\n";
+    }
+
+    public function testThroughputScaling(): void
+    {
+        $testCases = [
+            ['workers' => 1, 'jobs' => 50, 'capacity' => 50],
+            ['workers' => 5, 'jobs' => 250, 'capacity' => 20],
+            ['workers' => 10, 'jobs' => 500, 'capacity' => 15],
+            ['workers' => 20, 'jobs' => 1000, 'capacity' => 10]
+        ];
+
+        $results = [];
+
+        foreach ($testCases as $case) {
+            $workers = $this->createWorkers($case['workers'], $case['capacity']);
+            $result = $this->measureThroughput($workers, $case['jobs']);
+
+            $results[] = [
+                'worker_count' => $case['workers'],
+                'throughput' => $result['throughput'],
+                'efficiency' => $result['throughput'] / $case['workers'] // Jobs per worker per second
+            ];
+
+            $this->cleanupJobs();
+        }
+
+        // Validate scaling efficiency
+        for ($i = 1; $i < count($results); $i++) {
+            $prev = $results[$i - 1];
+            $curr = $results[$i];
+
+            $scalingFactor = $curr['worker_count'] / $prev['worker_count'];
+            $throughputIncrease = $curr['throughput'] / $prev['throughput'];
+
+            // Throughput should increase with more workers (allow for some overhead)
+            $this->assertGreaterThan(
+                $scalingFactor * 0.7, // Allow 30% overhead
+                $throughputIncrease,
+                sprintf(
+                    'Throughput scaling below expected: %dx workers should achieve at least %.1fx throughput',
+                    $scalingFactor,
+                    $scalingFactor * 0.7
+                )
+            );
+        }
+
+        echo "\nThroughput Scaling Results:\n";
+        foreach ($results as $result) {
+            echo sprintf(
+                "Workers: %2d, Throughput: %6.1f jobs/sec, Efficiency: %5.1f jobs/worker/sec\n",
+                $result['worker_count'],
+                $result['throughput'],
+                $result['efficiency']
+            );
+        }
+    }
+
+    public function testMixedCapacityThroughput(): void
+    {
+        $workers = [
+            PerformanceTestHelper::createTestWorker('worker_1', 50),
+            PerformanceTestHelper::createTestWorker('worker_2', 30),
+            PerformanceTestHelper::createTestWorker('worker_3', 20),
+            PerformanceTestHelper::createTestWorker('worker_4', 10),
+            PerformanceTestHelper::createTestWorker('worker_5', 5)
+        ];
+
+        $this->registerWorkers($workers);
+        $jobCount = 500;
+
+        $result = $this->measureThroughput($workers, $jobCount);
+
+        // Mixed capacity should still achieve good throughput
+        $this->assertGreaterThan(
+            200, // Reasonable expectation for mixed capacity workers
+            $result['throughput'],
+            'Mixed capacity worker throughput below expected minimum'
+        );
+
+        echo "\nMixed Capacity Worker Results:\n";
+        echo "Worker Capacities: 50, 30, 20, 10, 5\n";
+        echo "Throughput: {$result['throughput']} jobs/second\n";
+        echo "Average Job Distribution Time: " .
+             PerformanceTestHelper::formatStatistics($result['distribution_stats']) . "\n";
+    }
+
+    public function testSustainedLoadThroughput(): void
+    {
+        $workers = $this->createWorkers(10, 20);
+        $duration = 30; // 30 second sustained load test
+        $batchSize = 50;
+
+        $startTime = microtime(true);
+        $endTime = $startTime + $duration;
+        $totalJobs = 0;
+        $distributionTimes = [];
+
+        while (microtime(true) < $endTime) {
+            $jobs = PerformanceTestHelper::createBulkJobs($batchSize);
+
+            $batchStartTime = microtime(true);
+            foreach ($jobs as $job) {
+                $measureResult = PerformanceTestHelper::measureTimeWithResult(
+                    fn() => $this->distributionService->distributeJob($job)
+                );
+                $distributionTimes[] = $measureResult['time_ms'];
+            }
+            $batchEndTime = microtime(true);
+
+            $totalJobs += count($jobs);
+
+            // Clean up completed jobs to prevent memory issues
+            if ($totalJobs % 200 === 0) {
+                $this->cleanupJobs();
+            }
+
+            // Brief pause to prevent overwhelming
+            usleep(10000); // 10ms
+        }
+
+        $actualDuration = microtime(true) - $startTime;
+        $sustainedThroughput = $totalJobs / $actualDuration;
+
+        $this->assertGreaterThan(
+            100, // Should maintain at least 100 jobs/second under sustained load
+            $sustainedThroughput,
+            'Sustained load throughput below minimum'
+        );
+
+        $distributionStats = PerformanceTestHelper::calculateStatistics($distributionTimes);
+
+        echo "\nSustained Load Test Results:\n";
+        echo "Duration: {$actualDuration} seconds\n";
+        echo "Total Jobs: {$totalJobs}\n";
+        echo "Sustained Throughput: {$sustainedThroughput} jobs/second\n";
+        echo "Distribution Times: " . PerformanceTestHelper::formatStatistics($distributionStats) . "\n";
+
+        // Distribution times should remain reasonable under sustained load
+        $this->assertLessThan(50, $distributionStats['avg'], 'Average distribution time too high under sustained load');
+        $this->assertLessThan(100, $distributionStats['p95'], 'P95 distribution time too high under sustained load');
+    }
+
+    private function measureThroughput(array $workers, int $jobCount): array
+    {
+        $this->registerWorkers($workers);
+
+        $jobs = PerformanceTestHelper::createBulkJobs($jobCount);
+        $distributionTimes = [];
+
+        $startTime = microtime(true);
+
+        foreach ($jobs as $job) {
+            $measureResult = PerformanceTestHelper::measureTimeWithResult(
+                fn() => $this->distributionService->distributeJob($job)
+            );
+            $distributionTimes[] = $measureResult['time_ms'];
+        }
+
+        $endTime = microtime(true);
+        $totalTimeMs = ($endTime - $startTime) * 1000;
+        $throughput = $jobCount / ($endTime - $startTime);
+
+        return [
+            'throughput' => round($throughput, 1),
+            'total_time_ms' => round($totalTimeMs, 1),
+            'distribution_stats' => PerformanceTestHelper::calculateStatistics($distributionTimes),
+            'jobs_processed' => $jobCount
+        ];
+    }
+
+    private function createWorkers(int $count, int $capacity): array
+    {
+        $workers = [];
+        for ($i = 1; $i <= $count; $i++) {
+            $workers[] = PerformanceTestHelper::createTestWorker(
+                "perf_worker_{$i}",
+                $capacity,
+                WorkerStatus::AVAILABLE
+            );
+        }
+        return $workers;
+    }
+
+    private function registerWorkers(array $workers): void
+    {
+        foreach ($workers as $worker) {
+            $this->workerRegistry->registerWorker($worker);
+        }
+    }
+
+    private function createTestDatabase(): DatabaseManager
+    {
+        // Use in-memory SQLite for performance tests
+        $pdo = new \PDO('sqlite::memory:');
+        $pdo->setAttribute(\PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION);
+
+        // Create required tables
+        $pdo->exec('
+            CREATE TABLE workers (
+                id TEXT PRIMARY KEY,
+                queue_names TEXT NOT NULL,
+                capacity INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                last_heartbeat TEXT NOT NULL,
+                metadata TEXT
+            )
+        ');
+
+        $pdo->exec('
+            CREATE TABLE jobs (
+                id TEXT PRIMARY KEY,
+                type TEXT NOT NULL,
+                payload TEXT NOT NULL,
+                queue_name TEXT NOT NULL,
+                priority INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                worker_id TEXT,
+                created_at TEXT NOT NULL,
+                started_at TEXT,
+                completed_at TEXT,
+                attempts INTEGER DEFAULT 0,
+                error_message TEXT
+            )
+        ');
+
+        $pdo->exec('
+            CREATE TABLE distributed_locks (
+                lock_key TEXT PRIMARY KEY,
+                owner_id TEXT NOT NULL,
+                acquired_at TEXT NOT NULL,
+                expires_at TEXT NOT NULL
+            )
+        ');
+
+        // Create indexes for performance
+        $pdo->exec('CREATE INDEX idx_workers_status ON workers(status)');
+        $pdo->exec('CREATE INDEX idx_jobs_status ON jobs(status)');
+        $pdo->exec('CREATE INDEX idx_jobs_queue ON jobs(queue_name)');
+        $pdo->exec('CREATE INDEX idx_jobs_priority ON jobs(priority)');
+        $pdo->exec('CREATE INDEX idx_locks_expires ON distributed_locks(expires_at)');
+
+        return new DatabaseManager($pdo);
+    }
+
+    private function cleanupTestData(): void
+    {
+        $pdo = $this->database->getConnection();
+        $pdo->exec('DELETE FROM workers WHERE id LIKE "perf_worker_%"');
+        $pdo->exec('DELETE FROM jobs WHERE id LIKE "job_%"');
+        $pdo->exec('DELETE FROM distributed_locks');
+    }
+
+    private function cleanupJobs(): void
+    {
+        $pdo = $this->database->getConnection();
+        $pdo->exec('DELETE FROM jobs WHERE status IN ("COMPLETED", "FAILED")');
+    }
+}

tests/Framework/Queue/Performance/PerformanceTestHelper.php

@@ -0,0 +1,295 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Queue\Performance;
+
+use App\Framework\Queue\Jobs\Job;
+use App\Framework\Queue\Jobs\JobRequest;
+use App\Framework\Queue\Jobs\JobResult;
+use App\Framework\Queue\Jobs\JobStatus;
+use App\Framework\Queue\Workers\Worker;
+use App\Framework\Queue\Workers\WorkerCapacity;
+use App\Framework\Queue\Workers\WorkerId;
+use App\Framework\Queue\Workers\WorkerStatus;
+use App\Framework\Queue\Queue\QueueName;
+use App\Framework\Queue\Queue\JobPriority;
+
+final readonly class PerformanceTestHelper
+{
+    public static function createTestWorker(
+        string $id = null,
+        int $capacity = 10,
+        WorkerStatus $status = WorkerStatus::AVAILABLE
+    ): Worker {
+        return new Worker(
+            id: new WorkerId($id ?? uniqid('worker_')),
+            queueNames: [new QueueName('test_queue')],
+            capacity: new WorkerCapacity($capacity),
+            status: $status,
+            lastHeartbeat: new \DateTimeImmutable(),
+            metadata: []
+        );
+    }
+
+    public static function createTestJob(
+        string $id = null,
+        JobPriority $priority = JobPriority::NORMAL,
+        array $payload = []
+    ): Job {
+        return new Job(
+            id: $id ?? uniqid('job_'),
+            request: new JobRequest(
+                type: 'test_job',
+                payload: $payload ?: ['test' => 'data'],
+                queue: new QueueName('test_queue'),
+                priority: $priority
+            ),
+            status: JobStatus::PENDING,
+            createdAt: new \DateTimeImmutable(),
+            attempts: 0
+        );
+    }
+
+    public static function createBulkJobs(int $count, JobPriority $priority = JobPriority::NORMAL): array
+    {
+        $jobs = [];
+        for ($i = 0; $i < $count; $i++) {
+            $jobs[] = self::createTestJob(
+                id: "job_{$i}",
+                priority: $priority,
+                payload: ['batch_id' => $i, 'data' => str_repeat('x', 100)]
+            );
+        }
+        return $jobs;
+    }
+
+    public static function measureTime(callable $operation): float
+    {
+        $start = microtime(true);
+        $operation();
+        $end = microtime(true);
+
+        return ($end - $start) * 1000; // Return milliseconds
+    }
+
+    public static function measureTimeWithResult(callable $operation): array
+    {
+        $start = microtime(true);
+        $result = $operation();
+        $end = microtime(true);
+
+        return [
+            'result' => $result,
+            'time_ms' => ($end - $start) * 1000
+        ];
+    }
+
+    public static function calculateStatistics(array $measurements): array
+    {
+        if (empty($measurements)) {
+            return [
+                'count' => 0,
+                'min' => 0,
+                'max' => 0,
+                'avg' => 0,
+                'median' => 0,
+                'p95' => 0,
+                'p99' => 0,
+                'stddev' => 0
+            ];
+        }
+
+        sort($measurements);
+        $count = count($measurements);
+
+        $min = $measurements[0];
+        $max = $measurements[$count - 1];
+        $avg = array_sum($measurements) / $count;
+
+        $median = $count % 2 === 0
+            ? ($measurements[$count / 2 - 1] + $measurements[$count / 2]) / 2
+            : $measurements[intval($count / 2)];
+
+        $p95Index = intval($count * 0.95) - 1;
+        $p99Index = intval($count * 0.99) - 1;
+
+        $p95 = $measurements[max(0, $p95Index)];
+        $p99 = $measurements[max(0, $p99Index)];
+
+        // Calculate standard deviation
+        $sumSquaredDiff = 0;
+        foreach ($measurements as $value) {
+            $sumSquaredDiff += pow($value - $avg, 2);
+        }
+        $stddev = sqrt($sumSquaredDiff / $count);
+
+        return [
+            'count' => $count,
+            'min' => round($min, 3),
+            'max' => round($max, 3),
+            'avg' => round($avg, 3),
+            'median' => round($median, 3),
+            'p95' => round($p95, 3),
+            'p99' => round($p99, 3),
+            'stddev' => round($stddev, 3)
+        ];
+    }
+
+    public static function formatStatistics(array $stats, string $unit = 'ms'): string
+    {
+        return sprintf(
+            "Count: %d, Min: %.3f%s, Max: %.3f%s, Avg: %.3f%s, P95: %.3f%s, P99: %.3f%s, StdDev: %.3f%s",
+            $stats['count'],
+            $stats['min'], $unit,
+            $stats['max'], $unit,
+            $stats['avg'], $unit,
+            $stats['p95'], $unit,
+            $stats['p99'], $unit,
+            $stats['stddev'], $unit
+        );
+    }
+
+    public static function assertPerformance(
+        array $measurements,
+        float $expectedAvg,
+        float $expectedP95,
+        string $operation
+    ): void {
+        $stats = self::calculateStatistics($measurements);
+
+        if ($stats['avg'] > $expectedAvg) {
+            throw new \AssertionError(
+                sprintf(
+                    "%s average performance exceeded: expected ≤%.3fms, got %.3fms",
+                    $operation,
+                    $expectedAvg,
+                    $stats['avg']
+                )
+            );
+        }
+
+        if ($stats['p95'] > $expectedP95) {
+            throw new \AssertionError(
+                sprintf(
+                    "%s P95 performance exceeded: expected ≤%.3fms, got %.3fms",
+                    $operation,
+                    $expectedP95,
+                    $stats['p95']
+                )
+            );
+        }
+    }
+
+    public static function getMemoryUsage(): array
+    {
+        return [
+            'current_mb' => round(memory_get_usage(true) / 1024 / 1024, 2),
+            'peak_mb' => round(memory_get_peak_usage(true) / 1024 / 1024, 2),
+            'current_real_mb' => round(memory_get_usage(false) / 1024 / 1024, 2),
+            'peak_real_mb' => round(memory_get_peak_usage(false) / 1024 / 1024, 2)
+        ];
+    }
+
+    public static function warmupDatabase(\PDO $pdo): void
+    {
+        // Execute simple queries to warm up connections
+        $pdo->query('SELECT 1');
+        $pdo->query('SELECT COUNT(*) FROM workers');
+        $pdo->query('SELECT COUNT(*) FROM jobs');
+    }
+
+    public static function createConcurrentOperation(callable $operation, int $concurrency): \Generator
+    {
+        $operations = [];
+
+        for ($i = 0; $i < $concurrency; $i++) {
+            $operations[] = function() use ($operation, $i) {
+                return $operation($i);
+            };
+        }
+
+        foreach ($operations as $op) {
+            yield $op;
+        }
+    }
+
+    public static function simulateLoad(
+        callable $operation,
+        int $totalOperations,
+        int $concurrency,
+        float $durationSeconds = null
+    ): array {
+        $results = [];
+        $startTime = microtime(true);
+        $endTime = $durationSeconds ? $startTime + $durationSeconds : PHP_FLOAT_MAX;
+
+        $operationsCompleted = 0;
+        $batch = 0;
+
+        while ($operationsCompleted < $totalOperations && microtime(true) < $endTime) {
+            $batchSize = min($concurrency, $totalOperations - $operationsCompleted);
+            $batchResults = [];
+
+            // Execute concurrent operations
+            for ($i = 0; $i < $batchSize; $i++) {
+                $result = self::measureTimeWithResult(function() use ($operation, $batch, $i) {
+                    return $operation($batch * $concurrency + $i);
+                });
+                $batchResults[] = $result;
+            }
+
+            $results = array_merge($results, $batchResults);
+            $operationsCompleted += $batchSize;
+            $batch++;
+
+            // Small delay to prevent overwhelming the system
+            if (microtime(true) < $endTime) {
+                usleep(1000); // 1ms
+            }
+        }
+
+        return [
+            'results' => $results,
+            'operations_completed' => $operationsCompleted,
+            'duration_seconds' => microtime(true) - $startTime,
+            'throughput_ops_per_sec' => $operationsCompleted / (microtime(true) - $startTime)
+        ];
+    }
+
+    public static function generatePerformanceReport(array $testResults): string
+    {
+        $report = "\n" . str_repeat("=", 80) . "\n";
+        $report .= "PERFORMANCE TEST REPORT\n";
+        $report .= str_repeat("=", 80) . "\n\n";
+
+        foreach ($testResults as $testName => $results) {
+            $report .= "Test: {$testName}\n";
+            $report .= str_repeat("-", 40) . "\n";
+
+            if (isset($results['statistics'])) {
+                $report .= "Statistics: " . self::formatStatistics($results['statistics']) . "\n";
+            }
+
+            if (isset($results['throughput'])) {
+                $report .= "Throughput: {$results['throughput']} ops/sec\n";
+            }
+
+            if (isset($results['memory'])) {
+                $report .= sprintf(
+                    "Memory: Current: %.2fMB, Peak: %.2fMB\n",
+                    $results['memory']['current_mb'],
+                    $results['memory']['peak_mb']
+                );
+            }
+
+            if (isset($results['notes'])) {
+                $report .= "Notes: {$results['notes']}\n";
+            }
+
+            $report .= "\n";
+        }
+
+        return $report;
+    }
+}

tests/Framework/Queue/Performance/RealisticLoadScenariosTest.php

@@ -0,0 +1,720 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Queue\Performance;
+
+use App\Framework\Database\DatabaseManager;
+use App\Framework\Queue\Distribution\JobDistributionService;
+use App\Framework\Queue\Failover\FailoverRecoveryService;
+use App\Framework\Queue\Health\WorkerHealthCheckService;
+use App\Framework\Queue\Jobs\JobPriority;
+use App\Framework\Queue\Jobs\JobStatus;
+use App\Framework\Queue\Workers\WorkerRegistry;
+use App\Framework\Queue\Workers\WorkerStatus;
+use PHPUnit\Framework\TestCase;
+
+final class RealisticLoadScenariosTest extends TestCase
+{
+    private DatabaseManager $database;
+    private WorkerRegistry $workerRegistry;
+    private JobDistributionService $distributionService;
+    private WorkerHealthCheckService $healthCheckService;
+    private FailoverRecoveryService $failoverService;
+
+    protected function setUp(): void
+    {
+        $this->database = $this->createTestDatabase();
+        $this->workerRegistry = new WorkerRegistry($this->database);
+        $this->distributionService = new JobDistributionService(
+            $this->database,
+            $this->workerRegistry
+        );
+        $this->healthCheckService = new WorkerHealthCheckService(
+            $this->database,
+            $this->workerRegistry
+        );
+        $this->failoverService = new FailoverRecoveryService(
+            $this->database,
+            $this->workerRegistry
+        );
+
+        $this->cleanupTestData();
+        PerformanceTestHelper::warmupDatabase($this->database->getConnection());
+    }
+
+    protected function tearDown(): void
+    {
+        $this->cleanupTestData();
+    }
+
+    public function testEcommercePeakTrafficScenario(): void
+    {
+        echo "\nE-commerce Peak Traffic Scenario:\n";
+        echo "Simulating Black Friday / Cyber Monday traffic patterns\n";
+
+        // Setup: Mixed capacity workers for different job types
+        $workers = [
+            // High-capacity workers for order processing
+            ...$this->createWorkers(8, 50, 'order_processor'),
+            // Medium-capacity workers for inventory updates
+            ...$this->createWorkers(12, 30, 'inventory_worker'),
+            // Lower-capacity workers for email notifications
+            ...$this->createWorkers(20, 15, 'notification_worker')
+        ];
+
+        $this->registerWorkers($workers);
+
+        // Simulate peak traffic: 1000+ jobs per minute for 5 minutes
+        $scenarioDuration = 300; // 5 minutes
+        $peakJobsPerMinute = 1200;
+        $jobsPerSecond = $peakJobsPerMinute / 60;
+
+        echo "Target load: {$peakJobsPerMinute} jobs/minute ({$jobsPerSecond} jobs/second)\n";
+        echo "Duration: {$scenarioDuration} seconds\n";
+
+        $results = $this->simulateRealisticLoad(
+            $scenarioDuration,
+            $jobsPerSecond,
+            $this->createEcommerceJobMix()
+        );
+
+        echo "\nE-commerce Peak Results:\n";
+        echo "Actual throughput: {$results['throughput']} jobs/second\n";
+        echo "Success rate: {$results['success_rate']}%\n";
+        echo "Average response time: {$results['avg_response_time']}ms\n";
+        echo "P95 response time: {$results['p95_response_time']}ms\n";
+        echo "Memory usage: {$results['memory_usage']}MB\n";
+
+        // Validate e-commerce performance requirements
+        $this->assertGreaterThan(15, $results['throughput'], 'E-commerce throughput below minimum');
+        $this->assertGreaterThan(95.0, $results['success_rate'], 'E-commerce success rate below 95%');
+        $this->assertLessThan(100.0, $results['avg_response_time'], 'E-commerce response time too high');
+        $this->assertLessThan(200.0, $results['p95_response_time'], 'E-commerce P95 response time too high');
+    }
+
+    public function testMediaProcessingWorkloadScenario(): void
+    {
+        echo "\nMedia Processing Workload Scenario:\n";
+        echo "Simulating video transcoding and image processing pipeline\n";
+
+        // Setup: Fewer, high-capacity workers for CPU/memory intensive tasks
+        $workers = [
+            // Heavy-duty workers for video processing
+            ...$this->createWorkers(4, 100, 'video_processor'),
+            // Medium workers for image processing
+            ...$this->createWorkers(8, 50, 'image_processor'),
+            // Light workers for metadata extraction
+            ...$this->createWorkers(12, 25, 'metadata_worker')
+        ];
+
+        $this->registerWorkers($workers);
+
+        // Simulate media processing: Lower frequency but CPU/memory intensive
+        $scenarioDuration = 600; // 10 minutes
+        $jobsPerSecond = 3; // Lower rate due to intensive processing
+
+        echo "Target load: {$jobsPerSecond} jobs/second (CPU/memory intensive)\n";
+        echo "Duration: {$scenarioDuration} seconds\n";
+
+        $results = $this->simulateRealisticLoad(
+            $scenarioDuration,
+            $jobsPerSecond,
+            $this->createMediaProcessingJobMix(),
+            $enableResourceMonitoring = true
+        );
+
+        echo "\nMedia Processing Results:\n";
+        echo "Actual throughput: {$results['throughput']} jobs/second\n";
+        echo "Success rate: {$results['success_rate']}%\n";
+        echo "Average processing time: {$results['avg_response_time']}ms\n";
+        echo "Memory efficiency: {$results['memory_efficiency']}%\n";
+        echo "Resource utilization: {$results['resource_utilization']}%\n";
+
+        // Validate media processing performance requirements
+        $this->assertGreaterThan(2.5, $results['throughput'], 'Media processing throughput below minimum');
+        $this->assertGreaterThan(98.0, $results['success_rate'], 'Media processing success rate below 98%');
+        $this->assertLessThan(500.0, $results['avg_response_time'], 'Media processing time too high');
+        $this->assertGreaterThan(80.0, $results['resource_utilization'], 'Resource utilization too low');
+    }
+
+    public function testFinancialTransactionProcessingScenario(): void
+    {
+        echo "\nFinancial Transaction Processing Scenario:\n";
+        echo "Simulating real-time payment processing with low latency requirements\n";
+
+        // Setup: Many workers optimized for low-latency processing
+        $workers = [
+            // High-speed transaction processors
+            ...$this->createWorkers(20, 20, 'payment_processor'),
+            // Fraud detection workers
+            ...$this->createWorkers(10, 15, 'fraud_detector'),
+            // Settlement workers
+            ...$this->createWorkers(5, 30, 'settlement_worker')
+        ];
+
+        $this->registerWorkers($workers);
+
+        // Simulate financial processing: High frequency, low latency requirements
+        $scenarioDuration = 120; // 2 minutes
+        $jobsPerSecond = 50; // High frequency transactions
+
+        echo "Target load: {$jobsPerSecond} jobs/second (low latency requirement)\n";
+        echo "Duration: {$scenarioDuration} seconds\n";
+
+        $results = $this->simulateRealisticLoad(
+            $scenarioDuration,
+            $jobsPerSecond,
+            $this->createFinancialJobMix(),
+            $enableResourceMonitoring = false,
+            $lowLatencyMode = true
+        );
+
+        echo "\nFinancial Processing Results:\n";
+        echo "Actual throughput: {$results['throughput']} jobs/second\n";
+        echo "Success rate: {$results['success_rate']}%\n";
+        echo "Average latency: {$results['avg_response_time']}ms\n";
+        echo "P95 latency: {$results['p95_response_time']}ms\n";
+        echo "P99 latency: {$results['p99_response_time']}ms\n";
+
+        // Validate financial processing requirements (strict latency)
+        $this->assertGreaterThan(40, $results['throughput'], 'Financial throughput below minimum');
+        $this->assertGreaterThan(99.9, $results['success_rate'], 'Financial success rate below 99.9%');
+        $this->assertLessThan(20.0, $results['avg_response_time'], 'Financial latency too high');
+        $this->assertLessThan(50.0, $results['p95_response_time'], 'Financial P95 latency too high');
+        $this->assertLessThan(100.0, $results['p99_response_time'], 'Financial P99 latency too high');
+    }
+
+    public function testBatchProcessingScenario(): void
+    {
+        echo "\nBatch Processing Scenario:\n";
+        echo "Simulating ETL pipeline with high throughput requirements\n";
+
+        // Setup: High-capacity workers optimized for batch processing
+        $workers = [
+            // ETL workers for data transformation
+            ...$this->createWorkers(6, 100, 'etl_worker'),
+            // Data validation workers
+            ...$this->createWorkers(8, 75, 'validator'),
+            // Report generation workers
+            ...$this->createWorkers(4, 150, 'report_generator')
+        ];
+
+        $this->registerWorkers($workers);
+
+        // Simulate batch processing: Very high throughput
+        $scenarioDuration = 300; // 5 minutes
+        $jobsPerSecond = 100; // High throughput batch processing
+
+        echo "Target load: {$jobsPerSecond} jobs/second (high throughput batch)\n";
+        echo "Duration: {$scenarioDuration} seconds\n";
+
+        $results = $this->simulateRealisticLoad(
+            $scenarioDuration,
+            $jobsPerSecond,
+            $this->createBatchProcessingJobMix(),
+            $enableResourceMonitoring = true
+        );
+
+        echo "\nBatch Processing Results:\n";
+        echo "Actual throughput: {$results['throughput']} jobs/second\n";
+        echo "Success rate: {$results['success_rate']}%\n";
+        echo "Batch efficiency: {$results['batch_efficiency']}%\n";
+        echo "Resource utilization: {$results['resource_utilization']}%\n";
+        echo "Memory stability: {$results['memory_stability']}\n";
+
+        // Validate batch processing requirements
+        $this->assertGreaterThan(80, $results['throughput'], 'Batch throughput below minimum');
+        $this->assertGreaterThan(99.0, $results['success_rate'], 'Batch success rate below 99%');
+        $this->assertGreaterThan(85.0, $results['batch_efficiency'], 'Batch efficiency too low');
+        $this->assertGreaterThan(75.0, $results['resource_utilization'], 'Batch resource utilization too low');
+    }
+
+    public function testMixedWorkloadStressTest(): void
+    {
+        echo "\nMixed Workload Stress Test:\n";
+        echo "Simulating real-world environment with multiple concurrent workload types\n";
+
+        // Setup: Diverse worker pool handling multiple workload types
+        $workers = [
+            // Web request processors
+            ...$this->createWorkers(15, 30, 'web_processor'),
+            // Background task workers
+            ...$this->createWorkers(10, 20, 'background_worker'),
+            // Heavy computation workers
+            ...$this->createWorkers(5, 80, 'compute_worker'),
+            // Notification workers
+            ...$this->createWorkers(20, 10, 'notification_worker')
+        ];
+
+        $this->registerWorkers($workers);
+
+        // Simulate mixed workload with varying intensity
+        $phases = [
+            ['duration' => 60, 'rate' => 20, 'mix' => 'normal'],
+            ['duration' => 120, 'rate' => 50, 'mix' => 'peak'],
+            ['duration' => 60, 'rate' => 15, 'mix' => 'background'],
+            ['duration' => 90, 'rate' => 35, 'mix' => 'mixed']
+        ];
+
+        $overallResults = [];
+
+        foreach ($phases as $phaseIndex => $phase) {
+            echo "\nPhase " . ($phaseIndex + 1) . ": {$phase['mix']} workload\n";
+            echo "Duration: {$phase['duration']}s, Rate: {$phase['rate']} jobs/sec\n";
+
+            $jobMix = $this->createMixedWorkloadJobMix($phase['mix']);
+
+            $results = $this->simulateRealisticLoad(
+                $phase['duration'],
+                $phase['rate'],
+                $jobMix,
+                $enableResourceMonitoring = true
+            );
+
+            echo "Phase Results - Throughput: {$results['throughput']}, Success: {$results['success_rate']}%\n";
+
+            $overallResults[] = $results;
+
+            // Brief pause between phases
+            sleep(2);
+        }
+
+        // Analyze overall performance across all phases
+        $this->analyzeOverallPerformance($overallResults);
+    }
+
+    public function testFailoverUnderRealWorldLoad(): void
+    {
+        echo "\nFailover Under Real-World Load Test:\n";
+        echo "Simulating worker failures during active production load\n";
+
+        // Setup: Production-like worker configuration
+        $workers = [
+            ...$this->createWorkers(12, 25, 'primary_worker'),
+            ...$this->createWorkers(8, 30, 'secondary_worker'),
+            ...$this->createWorkers(6, 20, 'backup_worker')
+        ];
+
+        $this->registerWorkers($workers);
+
+        // Start sustained load
+        $testDuration = 180; // 3 minutes
+        $baseJobRate = 30; // jobs per second
+
+        echo "Base load: {$baseJobRate} jobs/second\n";
+        echo "Test duration: {$testDuration} seconds\n";
+
+        $startTime = microtime(true);
+        $endTime = $startTime + $testDuration;
+
+        $metrics = [
+            'jobs_processed' => 0,
+            'jobs_failed' => 0,
+            'response_times' => [],
+            'failover_events' => []
+        ];
+
+        $failoverTriggered = false;
+
+        while (microtime(true) < $endTime) {
+            $cycleStart = microtime(true);
+
+            // Trigger failover at 1/3 of test duration
+            if (!$failoverTriggered && (microtime(true) - $startTime) > ($testDuration / 3)) {
+                echo "\nTriggering failover scenario...\n";
+
+                // Fail primary workers
+                for ($i = 1; $i <= 4; $i++) {
+                    $this->updateWorkerStatus("primary_worker_{$i}", WorkerStatus::FAILED);
+                }
+
+                $failoverTime = PerformanceTestHelper::measureTime(function() {
+                    $this->failoverService->performFullSystemRecovery();
+                });
+
+                $metrics['failover_events'][] = [
+                    'time' => microtime(true) - $startTime,
+                    'recovery_time' => $failoverTime
+                ];
+
+                echo "Failover completed in {$failoverTime}ms\n";
+                $failoverTriggered = true;
+            }
+
+            // Process jobs
+            for ($i = 0; $i < $baseJobRate; $i++) {
+                $job = PerformanceTestHelper::createTestJob("realworld_job_{$metrics['jobs_processed']}");
+
+                $result = PerformanceTestHelper::measureTimeWithResult(function() use ($job) {
+                    try {
+                        return $this->distributionService->distributeJob($job);
+                    } catch (\Exception $e) {
+                        return null;
+                    }
+                });
+
+                $metrics['response_times'][] = $result['time_ms'];
+
+                if ($result['result'] !== null) {
+                    $metrics['jobs_processed']++;
+                } else {
+                    $metrics['jobs_failed']++;
+                }
+            }
+
+            // Maintain rate
+            $cycleTime = microtime(true) - $cycleStart;
+            $sleepTime = 1.0 - $cycleTime;
+            if ($sleepTime > 0) {
+                usleep($sleepTime * 1000000);
+            }
+        }
+
+        $actualDuration = microtime(true) - $startTime;
+        $actualThroughput = $metrics['jobs_processed'] / $actualDuration;
+        $successRate = $metrics['jobs_processed'] / ($metrics['jobs_processed'] + $metrics['jobs_failed']) * 100;
+
+        $responseStats = PerformanceTestHelper::calculateStatistics($metrics['response_times']);
+
+        echo "\nFailover Test Results:\n";
+        echo "Actual throughput: {$actualThroughput} jobs/second\n";
+        echo "Success rate: {$successRate}%\n";
+        echo "Response times: " . PerformanceTestHelper::formatStatistics($responseStats) . "\n";
+
+        if (!empty($metrics['failover_events'])) {
+            echo "Failover recovery time: {$metrics['failover_events'][0]['recovery_time']}ms\n";
+        }
+
+        // System should maintain reasonable performance during failover
+        $this->assertGreaterThan(20, $actualThroughput, 'Throughput too low during failover');
+        $this->assertGreaterThan(90.0, $successRate, 'Success rate too low during failover');
+        $this->assertLessThan(100.0, $responseStats['avg'], 'Response time too high during failover');
+    }
+
+    private function simulateRealisticLoad(
+        int $duration,
+        float $jobsPerSecond,
+        array $jobMix,
+        bool $enableResourceMonitoring = false,
+        bool $lowLatencyMode = false
+    ): array {
+        $startTime = microtime(true);
+        $endTime = $startTime + $duration;
+
+        $metrics = [
+            'jobs_processed' => 0,
+            'jobs_failed' => 0,
+            'response_times' => [],
+            'memory_snapshots' => [],
+            'start_memory' => null,
+            'end_memory' => null
+        ];
+
+        if ($enableResourceMonitoring) {
+            $metrics['start_memory'] = PerformanceTestHelper::getMemoryUsage();
+        }
+
+        $jobCounter = 0;
+        $snapshotInterval = $enableResourceMonitoring ? 30 : 0; // Take snapshots every 30 seconds
+        $nextSnapshotTime = $startTime + $snapshotInterval;
+
+        while (microtime(true) < $endTime) {
+            $cycleStart = microtime(true);
+
+            // Determine job type based on mix
+            $jobType = $this->selectJobType($jobMix);
+            $job = $this->createJobForType($jobType, $jobCounter);
+
+            $result = PerformanceTestHelper::measureTimeWithResult(function() use ($job) {
+                try {
+                    return $this->distributionService->distributeJob($job);
+                } catch (\Exception $e) {
+                    return null;
+                }
+            });
+
+            $metrics['response_times'][] = $result['time_ms'];
+
+            if ($result['result'] !== null) {
+                $metrics['jobs_processed']++;
+            } else {
+                $metrics['jobs_failed']++;
+            }
+
+            $jobCounter++;
+
+            // Take memory snapshots
+            if ($enableResourceMonitoring && microtime(true) >= $nextSnapshotTime) {
+                $metrics['memory_snapshots'][] = [
+                    'time' => microtime(true) - $startTime,
+                    'memory' => PerformanceTestHelper::getMemoryUsage()
+                ];
+                $nextSnapshotTime += $snapshotInterval;
+            }
+
+            // Rate limiting
+            if ($lowLatencyMode) {
+                // Minimal delay for low latency requirements
+                usleep(10); // 0.01ms
+            } else {
+                // Calculate delay to maintain target rate
+                $targetCycleTime = 1.0 / $jobsPerSecond;
+                $actualCycleTime = microtime(true) - $cycleStart;
+                $sleepTime = $targetCycleTime - $actualCycleTime;
+
+                if ($sleepTime > 0) {
+                    usleep($sleepTime * 1000000);
+                }
+            }
+        }
+
+        if ($enableResourceMonitoring) {
+            $metrics['end_memory'] = PerformanceTestHelper::getMemoryUsage();
+        }
+
+        return $this->calculateScenarioResults($metrics, microtime(true) - $startTime, $enableResourceMonitoring);
+    }
+
+    private function calculateScenarioResults(array $metrics, float $actualDuration, bool $includeResourceMetrics): array
+    {
+        $throughput = $metrics['jobs_processed'] / $actualDuration;
+        $successRate = $metrics['jobs_processed'] / max(1, $metrics['jobs_processed'] + $metrics['jobs_failed']) * 100;
+
+        $responseStats = PerformanceTestHelper::calculateStatistics($metrics['response_times']);
+
+        $results = [
+            'throughput' => round($throughput, 1),
+            'success_rate' => round($successRate, 2),
+            'avg_response_time' => $responseStats['avg'],
+            'p95_response_time' => $responseStats['p95'],
+            'p99_response_time' => $responseStats['p99']
+        ];
+
+        if ($includeResourceMetrics && isset($metrics['start_memory'], $metrics['end_memory'])) {
+            $startMem = $metrics['start_memory']['current_mb'];
+            $endMem = $metrics['end_memory']['current_mb'];
+            $peakMem = $metrics['end_memory']['peak_mb'];
+
+            $results['memory_usage'] = $endMem;
+            $results['memory_efficiency'] = round((1 - ($endMem - $startMem) / max(1, $startMem)) * 100, 1);
+            $results['resource_utilization'] = round(($endMem / $peakMem) * 100, 1);
+            $results['memory_stability'] = abs($endMem - $startMem) < 10 ? 'stable' : 'unstable';
+            $results['batch_efficiency'] = round($throughput / max(1, $endMem) * 100, 1);
+        }
+
+        return $results;
+    }
+
+    private function createEcommerceJobMix(): array
+    {
+        return [
+            'order_processing' => 40,
+            'inventory_update' => 25,
+            'payment_processing' => 20,
+            'email_notification' => 10,
+            'user_analytics' => 5
+        ];
+    }
+
+    private function createMediaProcessingJobMix(): array
+    {
+        return [
+            'video_transcode' => 30,
+            'image_resize' => 40,
+            'thumbnail_generation' => 20,
+            'metadata_extraction' => 10
+        ];
+    }
+
+    private function createFinancialJobMix(): array
+    {
+        return [
+            'payment_processing' => 50,
+            'fraud_detection' => 25,
+            'account_verification' => 15,
+            'transaction_logging' => 10
+        ];
+    }
+
+    private function createBatchProcessingJobMix(): array
+    {
+        return [
+            'data_transformation' => 40,
+            'data_validation' => 30,
+            'report_generation' => 20,
+            'data_archival' => 10
+        ];
+    }
+
+    private function createMixedWorkloadJobMix(string $mixType): array
+    {
+        return match($mixType) {
+            'normal' => [
+                'web_request' => 50,
+                'background_task' => 30,
+                'notification' => 20
+            ],
+            'peak' => [
+                'web_request' => 60,
+                'background_task' => 20,
+                'notification' => 15,
+                'compute_task' => 5
+            ],
+            'background' => [
+                'background_task' => 60,
+                'compute_task' => 30,
+                'notification' => 10
+            ],
+            'mixed' => [
+                'web_request' => 35,
+                'background_task' => 25,
+                'compute_task' => 25,
+                'notification' => 15
+            ],
+            default => ['web_request' => 100]
+        };
+    }
+
+    private function selectJobType(array $jobMix): string
+    {
+        $rand = rand(1, 100);
+        $cumulative = 0;
+
+        foreach ($jobMix as $type => $percentage) {
+            $cumulative += $percentage;
+            if ($rand <= $cumulative) {
+                return $type;
+            }
+        }
+
+        return array_key_first($jobMix);
+    }
+
+    private function createJobForType(string $jobType, int $counter): \App\Framework\Queue\Jobs\Job
+    {
+        $priority = match($jobType) {
+            'payment_processing', 'fraud_detection' => JobPriority::CRITICAL,
+            'order_processing', 'web_request' => JobPriority::HIGH,
+            'inventory_update', 'background_task' => JobPriority::NORMAL,
+            default => JobPriority::LOW
+        };
+
+        $payloadSize = match($jobType) {
+            'video_transcode', 'compute_task' => 1000, // Large payload
+            'image_resize', 'data_transformation' => 500, // Medium payload
+            default => 100 // Small payload
+        };
+
+        return PerformanceTestHelper::createTestJob(
+            "{$jobType}_job_{$counter}",
+            $priority,
+            ['type' => $jobType, 'data' => str_repeat('x', $payloadSize)]
+        );
+    }
+
+    private function analyzeOverallPerformance(array $phaseResults): void
+    {
+        echo "\nOverall Mixed Workload Analysis:\n";
+
+        $totalThroughput = array_sum(array_column($phaseResults, 'throughput')) / count($phaseResults);
+        $averageSuccessRate = array_sum(array_column($phaseResults, 'success_rate')) / count($phaseResults);
+        $averageResponseTime = array_sum(array_column($phaseResults, 'avg_response_time')) / count($phaseResults);
+
+        echo "Average throughput across phases: {$totalThroughput} jobs/second\n";
+        echo "Average success rate: {$averageSuccessRate}%\n";
+        echo "Average response time: {$averageResponseTime}ms\n";
+
+        // Validate mixed workload performance
+        $this->assertGreaterThan(25, $totalThroughput, 'Mixed workload throughput below minimum');
+        $this->assertGreaterThan(95.0, $averageSuccessRate, 'Mixed workload success rate below 95%');
+        $this->assertLessThan(80.0, $averageResponseTime, 'Mixed workload response time too high');
+
+        // Check performance consistency across phases
+        $throughputStdDev = $this->calculateStandardDeviation(array_column($phaseResults, 'throughput'));
+        $this->assertLessThan(10.0, $throughputStdDev, 'Throughput too inconsistent across phases');
+    }
+
+    private function calculateStandardDeviation(array $values): float
+    {
+        $mean = array_sum($values) / count($values);
+        $sumSquaredDiffs = array_sum(array_map(fn($v) => pow($v - $mean, 2), $values));
+        return sqrt($sumSquaredDiffs / count($values));
+    }
+
+    private function createWorkers(int $count, int $capacity, string $prefix): array
+    {
+        $workers = [];
+        for ($i = 1; $i <= $count; $i++) {
+            $workers[] = PerformanceTestHelper::createTestWorker(
+                "{$prefix}_{$i}",
+                $capacity,
+                WorkerStatus::AVAILABLE
+            );
+        }
+        return $workers;
+    }
+
+    private function registerWorkers(array $workers): void
+    {
+        foreach ($workers as $worker) {
+            $this->workerRegistry->registerWorker($worker);
+        }
+    }
+
+    private function updateWorkerStatus(string $workerId, WorkerStatus $status): void
+    {
+        $pdo = $this->database->getConnection();
+        $stmt = $pdo->prepare('UPDATE workers SET status = ? WHERE id = ?');
+        $stmt->execute([$status->value, $workerId]);
+    }
+
+    private function createTestDatabase(): DatabaseManager
+    {
+        $pdo = new \PDO('sqlite::memory:');
+        $pdo->setAttribute(\PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION);
+
+        $pdo->exec('
+            CREATE TABLE workers (
+                id TEXT PRIMARY KEY,
+                queue_names TEXT NOT NULL,
+                capacity INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                last_heartbeat TEXT NOT NULL,
+                metadata TEXT
+            )
+        ');
+
+        $pdo->exec('
+            CREATE TABLE jobs (
+                id TEXT PRIMARY KEY,
+                type TEXT NOT NULL,
+                payload TEXT NOT NULL,
+                queue_name TEXT NOT NULL,
+                priority INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                worker_id TEXT,
+                created_at TEXT NOT NULL,
+                started_at TEXT,
+                completed_at TEXT,
+                attempts INTEGER DEFAULT 0,
+                error_message TEXT
+            )
+        ');
+
+        // Performance indexes
+        $pdo->exec('CREATE INDEX idx_workers_status ON workers(status)');
+        $pdo->exec('CREATE INDEX idx_jobs_status ON jobs(status)');
+        $pdo->exec('CREATE INDEX idx_jobs_priority ON jobs(priority)');
+        $pdo->exec('CREATE INDEX idx_jobs_worker ON jobs(worker_id)');
+
+        return new DatabaseManager($pdo);
+    }
+
+    private function cleanupTestData(): void
+    {
+        $pdo = $this->database->getConnection();
+        $pdo->exec('DELETE FROM workers');
+        $pdo->exec('DELETE FROM jobs');
+    }
+}

tests/Framework/Queue/Performance/SystemResourcesTest.php

@@ -0,0 +1,617 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Queue\Performance;
+
+use App\Framework\Database\DatabaseManager;
+use App\Framework\Queue\Distribution\JobDistributionService;
+use App\Framework\Queue\Jobs\JobPriority;
+use App\Framework\Queue\Workers\WorkerRegistry;
+use PHPUnit\Framework\TestCase;
+
+final class SystemResourcesTest extends TestCase
+{
+    private DatabaseManager $database;
+    private WorkerRegistry $workerRegistry;
+    private JobDistributionService $distributionService;
+
+    protected function setUp(): void
+    {
+        $this->database = $this->createTestDatabase();
+        $this->workerRegistry = new WorkerRegistry($this->database);
+        $this->distributionService = new JobDistributionService(
+            $this->database,
+            $this->workerRegistry
+        );
+
+        $this->cleanupTestData();
+        PerformanceTestHelper::warmupDatabase($this->database->getConnection());
+    }
+
+    protected function tearDown(): void
+    {
+        $this->cleanupTestData();
+    }
+
+    public function testMemoryUsageUnderLoad(): void
+    {
+        $workers = $this->createWorkers(10, 25);
+        $this->registerWorkers($workers);
+
+        $initialMemory = PerformanceTestHelper::getMemoryUsage();
+        $memorySnapshots = [$initialMemory];
+
+        echo "\nMemory Usage Under Load Test:\n";
+        echo "Initial memory: {$initialMemory['current_mb']}MB (Peak: {$initialMemory['peak_mb']}MB)\n";
+
+        // Phase 1: Moderate load
+        $this->simulateJobLoad(500, 'moderate', $memorySnapshots);
+
+        // Phase 2: High load
+        $this->simulateJobLoad(1000, 'high', $memorySnapshots);
+
+        // Phase 3: Sustained load
+        $this->simulateSustainedLoad(30, 50, $memorySnapshots); // 30 seconds, 50 jobs/sec
+
+        $finalMemory = PerformanceTestHelper::getMemoryUsage();
+        $memorySnapshots[] = $finalMemory;
+
+        echo "Final memory: {$finalMemory['current_mb']}MB (Peak: {$finalMemory['peak_mb']}MB)\n";
+
+        // Analyze memory usage patterns
+        $this->analyzeMemoryUsage($memorySnapshots);
+
+        // Memory usage should stay within reasonable bounds
+        $this->assertLessThan(
+            100.0,
+            $finalMemory['current_mb'],
+            'Current memory usage exceeds 100MB'
+        );
+
+        $this->assertLessThan(
+            200.0,
+            $finalMemory['peak_mb'],
+            'Peak memory usage exceeds 200MB'
+        );
+
+        // Check for potential memory leaks
+        $memoryIncrease = $finalMemory['current_mb'] - $initialMemory['current_mb'];
+        $this->assertLessThan(
+            50.0,
+            $memoryIncrease,
+            'Memory increase suggests potential memory leak'
+        );
+    }
+
+    public function testMemoryEfficiencyWithBulkOperations(): void
+    {
+        $workers = $this->createWorkers(5, 30);
+        $this->registerWorkers($workers);
+
+        echo "\nMemory Efficiency with Bulk Operations:\n";
+
+        $testCases = [
+            ['batch_size' => 10, 'batches' => 10],
+            ['batch_size' => 50, 'batches' => 10],
+            ['batch_size' => 100, 'batches' => 10],
+            ['batch_size' => 500, 'batches' => 5],
+            ['batch_size' => 1000, 'batches' => 3]
+        ];
+
+        foreach ($testCases as $case) {
+            $batchSize = $case['batch_size'];
+            $batchCount = $case['batches'];
+
+            $beforeMemory = PerformanceTestHelper::getMemoryUsage();
+
+            // Process batches
+            $totalProcessingTime = 0;
+            for ($batch = 0; $batch < $batchCount; $batch++) {
+                $jobs = PerformanceTestHelper::createBulkJobs($batchSize);
+
+                $batchTime = PerformanceTestHelper::measureTime(function() use ($jobs) {
+                    foreach ($jobs as $job) {
+                        $this->distributionService->distributeJob($job);
+                    }
+                });
+
+                $totalProcessingTime += $batchTime;
+
+                // Clean up completed jobs to simulate real processing
+                if ($batch % 2 === 0) {
+                    $this->cleanupCompletedJobs();
+                }
+            }
+
+            $afterMemory = PerformanceTestHelper::getMemoryUsage();
+            $memoryIncrease = $afterMemory['current_mb'] - $beforeMemory['current_mb'];
+            $totalJobs = $batchSize * $batchCount;
+            $avgTimePerJob = $totalProcessingTime / $totalJobs;
+
+            echo sprintf(
+                "Batch size: %4d, Total jobs: %4d, Memory increase: %6.2fMB, Avg time: %6.3fms/job\n",
+                $batchSize,
+                $totalJobs,
+                $memoryIncrease,
+                $avgTimePerJob
+            );
+
+            // Memory increase should not grow linearly with batch size
+            $memoryPerJob = $memoryIncrease / $totalJobs;
+            $this->assertLessThan(
+                0.1,
+                $memoryPerJob,
+                "Memory usage per job too high for batch size {$batchSize}"
+            );
+
+            $this->cleanupTestData();
+        }
+    }
+
+    public function testGarbageCollectionImpact(): void
+    {
+        $workers = $this->createWorkers(8, 20);
+        $this->registerWorkers($workers);
+
+        echo "\nGarbage Collection Impact Test:\n";
+
+        $gcStats = [];
+        $operationTimes = [];
+
+        // Force garbage collection and measure baseline
+        gc_collect_cycles();
+        $initialGcStats = gc_status();
+
+        // Perform operations that generate objects
+        $iterations = 1000;
+        for ($i = 0; $i < $iterations; $i++) {
+            $job = PerformanceTestHelper::createTestJob("gc_test_job_{$i}");
+
+            $operationTime = PerformanceTestHelper::measureTime(function() use ($job) {
+                return $this->distributionService->distributeJob($job);
+            });
+
+            $operationTimes[] = $operationTime;
+
+            // Collect GC stats every 100 operations
+            if ($i % 100 === 0) {
+                $gcStats[] = [
+                    'operation' => $i,
+                    'memory' => PerformanceTestHelper::getMemoryUsage(),
+                    'gc_stats' => gc_status()
+                ];
+            }
+        }
+
+        // Force final garbage collection
+        $gcCycles = gc_collect_cycles();
+        $finalGcStats = gc_status();
+
+        echo "GC cycles collected: {$gcCycles}\n";
+        echo "Initial GC runs: {$initialGcStats['runs']}\n";
+        echo "Final GC runs: {$finalGcStats['runs']}\n";
+        echo "GC runs during test: " . ($finalGcStats['runs'] - $initialGcStats['runs']) . "\n";
+
+        // Analyze operation times for GC impact
+        $stats = PerformanceTestHelper::calculateStatistics($operationTimes);
+        echo "Operation performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+
+        // GC should not cause significant performance degradation
+        $this->assertLessThan(
+            20.0,
+            $stats['avg'],
+            'Average operation time too high - possible GC impact'
+        );
+
+        // P99 should not be extremely high (indicating GC pauses)
+        $this->assertLessThan(
+            100.0,
+            $stats['p99'],
+            'P99 operation time too high - possible GC pause impact'
+        );
+
+        // Analyze memory usage patterns during GC
+        foreach ($gcStats as $snapshot) {
+            $memory = $snapshot['memory'];
+            echo sprintf(
+                "Operation %4d: Memory %6.2fMB, GC runs: %d\n",
+                $snapshot['operation'],
+                $memory['current_mb'],
+                $snapshot['gc_stats']['runs']
+            );
+        }
+    }
+
+    public function testConcurrentOperationResourceUsage(): void
+    {
+        $workers = $this->createWorkers(15, 20);
+        $this->registerWorkers($workers);
+
+        echo "\nConcurrent Operation Resource Usage Test:\n";
+
+        $concurrencyLevels = [1, 5, 10, 20, 50];
+        $operationsPerLevel = 200;
+
+        foreach ($concurrencyLevels as $concurrency) {
+            $beforeMemory = PerformanceTestHelper::getMemoryUsage();
+
+            // Simulate concurrent operations
+            $results = $this->simulateConcurrentOperations($concurrency, $operationsPerLevel);
+
+            $afterMemory = PerformanceTestHelper::getMemoryUsage();
+            $memoryIncrease = $afterMemory['current_mb'] - $beforeMemory['current_mb'];
+
+            $avgTime = array_sum($results['times']) / count($results['times']);
+            $throughput = $results['total_operations'] / $results['duration'];
+
+            echo sprintf(
+                "Concurrency: %2d, Throughput: %6.1f ops/sec, Avg time: %6.3fms, Memory: +%6.2fMB\n",
+                $concurrency,
+                $throughput,
+                $avgTime,
+                $memoryIncrease
+            );
+
+            // Memory usage should not grow excessively with concurrency
+            $this->assertLessThan(
+                10.0,
+                $memoryIncrease,
+                "Memory increase too high for concurrency level {$concurrency}"
+            );
+
+            // Throughput should generally increase with concurrency (up to a point)
+            if ($concurrency <= 10) {
+                $this->assertGreaterThan(
+                    $concurrency * 5, // At least 5 ops/sec per concurrent operation
+                    $throughput,
+                    "Throughput too low for concurrency level {$concurrency}"
+                );
+            }
+
+            $this->cleanupTestData();
+        }
+    }
+
+    public function testLongRunningProcessMemoryStability(): void
+    {
+        $workers = $this->createWorkers(6, 25);
+        $this->registerWorkers($workers);
+
+        echo "\nLong Running Process Memory Stability Test:\n";
+
+        $duration = 120; // 2 minutes
+        $operationsPerSecond = 20;
+        $memorySnapshots = [];
+
+        $startTime = microtime(true);
+        $endTime = $startTime + $duration;
+        $operationCount = 0;
+
+        while (microtime(true) < $endTime) {
+            $cycleStart = microtime(true);
+
+            // Perform operations for one second
+            for ($i = 0; $i < $operationsPerSecond; $i++) {
+                $job = PerformanceTestHelper::createTestJob("stability_job_{$operationCount}");
+                $this->distributionService->distributeJob($job);
+                $operationCount++;
+            }
+
+            // Take memory snapshot every 10 seconds
+            if ($operationCount % ($operationsPerSecond * 10) === 0) {
+                $memory = PerformanceTestHelper::getMemoryUsage();
+                $elapsed = microtime(true) - $startTime;
+                $memorySnapshots[] = [
+                    'time' => $elapsed,
+                    'operations' => $operationCount,
+                    'memory' => $memory
+                ];
+
+                echo sprintf(
+                    "Time: %3ds, Operations: %5d, Memory: %6.2fMB (Peak: %6.2fMB)\n",
+                    $elapsed,
+                    $operationCount,
+                    $memory['current_mb'],
+                    $memory['peak_mb']
+                );
+            }
+
+            // Clean up periodically to simulate real-world processing
+            if ($operationCount % ($operationsPerSecond * 5) === 0) {
+                $this->cleanupCompletedJobs();
+            }
+
+            // Maintain target operations per second
+            $cycleTime = microtime(true) - $cycleStart;
+            $sleepTime = 1.0 - $cycleTime;
+            if ($sleepTime > 0) {
+                usleep($sleepTime * 1000000);
+            }
+        }
+
+        $actualDuration = microtime(true) - $startTime;
+        $actualThroughput = $operationCount / $actualDuration;
+
+        echo "Total operations: {$operationCount}\n";
+        echo "Actual duration: {$actualDuration} seconds\n";
+        echo "Actual throughput: {$actualThroughput} ops/sec\n";
+
+        // Analyze memory stability
+        $this->analyzeMemoryStability($memorySnapshots);
+
+        // Memory should remain stable over time
+        $firstSnapshot = $memorySnapshots[0];
+        $lastSnapshot = end($memorySnapshots);
+        $memoryDrift = $lastSnapshot['memory']['current_mb'] - $firstSnapshot['memory']['current_mb'];
+
+        echo "Memory drift: {$memoryDrift}MB\n";
+
+        $this->assertLessThan(
+            20.0,
+            abs($memoryDrift),
+            'Memory drift too high - indicates memory leak or accumulation'
+        );
+
+        // Throughput should remain stable
+        $this->assertGreaterThan(
+            $operationsPerSecond * 0.8,
+            $actualThroughput,
+            'Throughput degraded too much during long run'
+        );
+    }
+
+    public function testResourceCleanupEfficiency(): void
+    {
+        $workers = $this->createWorkers(5, 20);
+        $this->registerWorkers($workers);
+
+        echo "\nResource Cleanup Efficiency Test:\n";
+
+        // Create many jobs
+        $jobCount = 2000;
+        $jobs = PerformanceTestHelper::createBulkJobs($jobCount);
+
+        $beforeMemory = PerformanceTestHelper::getMemoryUsage();
+        echo "Memory before job creation: {$beforeMemory['current_mb']}MB\n";
+
+        // Distribute all jobs
+        foreach ($jobs as $job) {
+            $this->distributionService->distributeJob($job);
+        }
+
+        $afterDistribution = PerformanceTestHelper::getMemoryUsage();
+        echo "Memory after distribution: {$afterDistribution['current_mb']}MB\n";
+
+        // Measure cleanup time
+        $cleanupTime = PerformanceTestHelper::measureTime(function() {
+            $this->cleanupCompletedJobs();
+        });
+
+        $afterCleanup = PerformanceTestHelper::getMemoryUsage();
+        echo "Memory after cleanup: {$afterCleanup['current_mb']}MB\n";
+        echo "Cleanup time: {$cleanupTime}ms\n";
+
+        $memoryRecovered = $afterDistribution['current_mb'] - $afterCleanup['current_mb'];
+        echo "Memory recovered: {$memoryRecovered}MB\n";
+
+        // Cleanup should be efficient
+        $this->assertLessThan(
+            200.0,
+            $cleanupTime,
+            'Cleanup time too slow for 2000 jobs'
+        );
+
+        // Should recover most of the memory
+        $distributionMemoryUsage = $afterDistribution['current_mb'] - $beforeMemory['current_mb'];
+        $recoveryRatio = $memoryRecovered / max(1, $distributionMemoryUsage);
+
+        echo "Memory recovery ratio: " . round($recoveryRatio * 100, 1) . "%\n";
+
+        $this->assertGreaterThan(
+            0.5,
+            $recoveryRatio,
+            'Should recover at least 50% of memory used during distribution'
+        );
+    }
+
+    private function simulateJobLoad(int $jobCount, string $phase, array &$memorySnapshots): void
+    {
+        echo "Phase: {$phase} ({$jobCount} jobs)\n";
+
+        $beforeMemory = PerformanceTestHelper::getMemoryUsage();
+        $memorySnapshots[] = $beforeMemory;
+
+        $jobs = PerformanceTestHelper::createBulkJobs($jobCount);
+        $distributionTimes = [];
+
+        foreach ($jobs as $job) {
+            $time = PerformanceTestHelper::measureTime(function() use ($job) {
+                return $this->distributionService->distributeJob($job);
+            });
+            $distributionTimes[] = $time;
+        }
+
+        $afterMemory = PerformanceTestHelper::getMemoryUsage();
+        $memorySnapshots[] = $afterMemory;
+
+        $stats = PerformanceTestHelper::calculateStatistics($distributionTimes);
+        $memoryIncrease = $afterMemory['current_mb'] - $beforeMemory['current_mb'];
+
+        echo "  Memory increase: {$memoryIncrease}MB\n";
+        echo "  Distribution performance: " . PerformanceTestHelper::formatStatistics($stats) . "\n";
+    }
+
+    private function simulateSustainedLoad(int $duration, int $jobsPerSecond, array &$memorySnapshots): void
+    {
+        echo "Sustained load: {$jobsPerSecond} jobs/sec for {$duration} seconds\n";
+
+        $startTime = microtime(true);
+        $endTime = $startTime + $duration;
+        $jobCount = 0;
+
+        $snapshotInterval = 5; // Take snapshot every 5 seconds
+        $nextSnapshotTime = $startTime + $snapshotInterval;
+
+        while (microtime(true) < $endTime) {
+            $job = PerformanceTestHelper::createTestJob("sustained_job_{$jobCount}");
+            $this->distributionService->distributeJob($job);
+            $jobCount++;
+
+            // Take memory snapshot
+            if (microtime(true) >= $nextSnapshotTime) {
+                $memory = PerformanceTestHelper::getMemoryUsage();
+                $memorySnapshots[] = $memory;
+                $elapsed = microtime(true) - $startTime;
+                echo "  {$elapsed}s: {$memory['current_mb']}MB\n";
+                $nextSnapshotTime += $snapshotInterval;
+            }
+
+            // Maintain target rate
+            usleep(1000000 / $jobsPerSecond); // Convert to microseconds
+        }
+
+        echo "  Total jobs: {$jobCount}\n";
+    }
+
+    private function simulateConcurrentOperations(int $concurrency, int $totalOperations): array
+    {
+        $times = [];
+        $startTime = microtime(true);
+
+        $operationsPerWorker = intval($totalOperations / $concurrency);
+        $actualOperations = 0;
+
+        // Simulate concurrent operations (simplified for single-threaded PHP)
+        for ($worker = 0; $worker < $concurrency; $worker++) {
+            for ($op = 0; $op < $operationsPerWorker; $op++) {
+                $job = PerformanceTestHelper::createTestJob("concurrent_job_{$worker}_{$op}");
+
+                $time = PerformanceTestHelper::measureTime(function() use ($job) {
+                    return $this->distributionService->distributeJob($job);
+                });
+
+                $times[] = $time;
+                $actualOperations++;
+            }
+        }
+
+        $endTime = microtime(true);
+
+        return [
+            'times' => $times,
+            'total_operations' => $actualOperations,
+            'duration' => $endTime - $startTime
+        ];
+    }
+
+    private function analyzeMemoryUsage(array $memorySnapshots): void
+    {
+        echo "\nMemory Usage Analysis:\n";
+
+        $memoryValues = array_column($memorySnapshots, 'current_mb');
+        $peakValues = array_column($memorySnapshots, 'peak_mb');
+
+        $memoryStats = PerformanceTestHelper::calculateStatistics($memoryValues);
+        $peakStats = PerformanceTestHelper::calculateStatistics($peakValues);
+
+        echo "Current Memory: " . PerformanceTestHelper::formatStatistics($memoryStats, 'MB') . "\n";
+        echo "Peak Memory: " . PerformanceTestHelper::formatStatistics($peakStats, 'MB') . "\n";
+
+        // Check for memory growth pattern
+        $memoryTrend = end($memoryValues) - $memoryValues[0];
+        echo "Memory trend: " . ($memoryTrend >= 0 ? '+' : '') . "{$memoryTrend}MB\n";
+    }
+
+    private function analyzeMemoryStability(array $memorySnapshots): void
+    {
+        echo "\nMemory Stability Analysis:\n";
+
+        $memoryValues = array_column(array_column($memorySnapshots, 'memory'), 'current_mb');
+        $timeValues = array_column($memorySnapshots, 'time');
+
+        // Calculate memory growth rate
+        if (count($memoryValues) >= 2) {
+            $firstMemory = $memoryValues[0];
+            $lastMemory = end($memoryValues);
+            $timeSpan = end($timeValues) - $timeValues[0];
+
+            $growthRate = ($lastMemory - $firstMemory) / $timeSpan; // MB per second
+            echo "Memory growth rate: " . round($growthRate * 60, 3) . " MB/minute\n";
+
+            $this->assertLessThan(
+                0.1, // Less than 0.1 MB/sec = 6 MB/minute
+                abs($growthRate),
+                'Memory growth rate too high - indicates potential leak'
+            );
+        }
+    }
+
+    private function createWorkers(int $count, int $capacity): array
+    {
+        $workers = [];
+        for ($i = 1; $i <= $count; $i++) {
+            $workers[] = PerformanceTestHelper::createTestWorker(
+                "resource_worker_{$i}",
+                $capacity
+            );
+        }
+        return $workers;
+    }
+
+    private function registerWorkers(array $workers): void
+    {
+        foreach ($workers as $worker) {
+            $this->workerRegistry->registerWorker($worker);
+        }
+    }
+
+    private function cleanupCompletedJobs(): void
+    {
+        $pdo = $this->database->getConnection();
+        $pdo->exec('DELETE FROM jobs WHERE status IN ("COMPLETED", "FAILED")');
+    }
+
+    private function createTestDatabase(): DatabaseManager
+    {
+        $pdo = new \PDO('sqlite::memory:');
+        $pdo->setAttribute(\PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION);
+
+        $pdo->exec('
+            CREATE TABLE workers (
+                id TEXT PRIMARY KEY,
+                queue_names TEXT NOT NULL,
+                capacity INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                last_heartbeat TEXT NOT NULL,
+                metadata TEXT
+            )
+        ');
+
+        $pdo->exec('
+            CREATE TABLE jobs (
+                id TEXT PRIMARY KEY,
+                type TEXT NOT NULL,
+                payload TEXT NOT NULL,
+                queue_name TEXT NOT NULL,
+                priority INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                worker_id TEXT,
+                created_at TEXT NOT NULL,
+                started_at TEXT,
+                completed_at TEXT,
+                attempts INTEGER DEFAULT 0,
+                error_message TEXT
+            )
+        ');
+
+        return new DatabaseManager($pdo);
+    }
+
+    private function cleanupTestData(): void
+    {
+        $pdo = $this->database->getConnection();
+        $pdo->exec('DELETE FROM workers');
+        $pdo->exec('DELETE FROM jobs');
+    }
+}

tests/Framework/Queue/QueueServiceRegistrationTest.php

@@ -0,0 +1,493 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\DI\Container;
+use App\Framework\DI\DefaultContainer;
+use App\Framework\Queue\Queue;
+use App\Framework\Queue\QueueInitializer;
+use App\Framework\Queue\QueueDependencyInitializer;
+
+// Queue service interfaces
+use App\Framework\Queue\Interfaces\DistributedLockInterface;
+use App\Framework\Queue\Contracts\JobProgressTrackerInterface;
+use App\Framework\Queue\Contracts\JobDependencyManagerInterface;
+use App\Framework\Queue\Contracts\DeadLetterQueueInterface;
+use App\Framework\Queue\Contracts\JobChainManagerInterface;
+use App\Framework\Queue\Services\JobMetricsManagerInterface;
+
+// Concrete implementations
+use App\Framework\Queue\Services\DatabaseDistributedLock;
+use App\Framework\Queue\Services\DatabaseJobProgressTracker;
+use App\Framework\Queue\Services\DatabaseJobDependencyManager;
+use App\Framework\Queue\Services\DatabaseDeadLetterQueue;
+use App\Framework\Queue\Services\DatabaseJobChainManager;
+use App\Framework\Queue\Services\JobMetricsManager;
+
+// Additional services
+use App\Framework\Queue\Services\WorkerRegistry;
+use App\Framework\Queue\Services\JobDistributionService;
+use App\Framework\Queue\Services\WorkerHealthCheckService;
+use App\Framework\Queue\Services\FailoverRecoveryService;
+use App\Framework\Queue\Services\DependencyResolutionEngine;
+
+// Framework dependencies
+use App\Framework\Database\EntityManagerInterface;
+use App\Framework\Logging\Logger;
+
+describe('Queue Service Registration', function () {
+
+    beforeEach(function () {
+        $this->container = new DefaultContainer();
+
+        // Mock essential framework dependencies
+        $this->mockEntityManager = new class implements EntityManagerInterface {
+            public function persist(object $entity): void {}
+            public function find(string $className, mixed $id): ?object { return null; }
+            public function flush(): void {}
+            public function remove(object $entity): void {}
+            public function clear(): void {}
+            public function detach(object $entity): void {}
+            public function contains(object $entity): bool { return false; }
+            public function refresh(object $entity): void {}
+            public function createQueryBuilder(): object { return new stdClass(); }
+            public function getRepository(string $className): object { return new stdClass(); }
+            public function beginTransaction(): void {}
+            public function commit(): void {}
+            public function rollback(): void {}
+            public function isTransactionActive(): bool { return false; }
+        };
+
+        $this->mockLogger = new class implements Logger {
+            public function emergency(string $message, array $context = []): void {}
+            public function alert(string $message, array $context = []): void {}
+            public function critical(string $message, array $context = []): void {}
+            public function error(string $message, array $context = []): void {}
+            public function warning(string $message, array $context = []): void {}
+            public function notice(string $message, array $context = []): void {}
+            public function info(string $message, array $context = []): void {}
+            public function debug(string $message, array $context = []): void {}
+            public function log(string $level, string $message, array $context = []): void {}
+        };
+
+        // Register mocked dependencies
+        $this->container->instance(EntityManagerInterface::class, $this->mockEntityManager);
+        $this->container->instance(Logger::class, $this->mockLogger);
+    });
+
+    describe('Core Queue Service', function () {
+        it('registers Queue service correctly', function () {
+            // This test verifies that the QueueInitializer properly registers a Queue
+            // Note: This will fallback to FileQueue since Redis is not available in tests
+
+            $queueInitializer = new QueueInitializer(
+                pathProvider: new class {
+                    public function resolvePath(string $path): string {
+                        return '/home/michael/dev/michaelschiemer/tests/tmp/queue/';
+                    }
+                }
+            );
+
+            $queue = $queueInitializer($this->mockLogger);
+
+            expect($queue)->toBeInstanceOf(Queue::class);
+            expect($queue)->not->toBeNull();
+        });
+
+        it('Queue service is accessible from container after registration', function () {
+            // Register queue manually for testing
+            $this->container->singleton(Queue::class, function() {
+                return new \App\Framework\Queue\InMemoryQueue();
+            });
+
+            $queue = $this->container->get(Queue::class);
+            expect($queue)->toBeInstanceOf(Queue::class);
+        });
+    });
+
+    describe('Queue Dependencies Registration', function () {
+        beforeEach(function () {
+            // Initialize the queue dependency system
+            $this->dependencyInitializer = new QueueDependencyInitializer();
+
+            // Register a basic queue interface for the dependencies
+            $this->container->singleton(\App\Framework\Queue\Contracts\QueueInterface::class, function() {
+                return new class implements \App\Framework\Queue\Contracts\QueueInterface {
+                    public function push(mixed $job): void {}
+                    public function pop(): mixed { return null; }
+                    public function size(): int { return 0; }
+                };
+            });
+
+            // Register EventDispatcher mock
+            $this->container->singleton(\App\Framework\Core\Events\EventDispatcherInterface::class, function() {
+                return new class implements \App\Framework\Core\Events\EventDispatcherInterface {
+                    public function dispatch(object $event): void {}
+                    public function listen(string $event, callable $listener): void {}
+                };
+            });
+        });
+
+        it('registers JobDependencyManagerInterface', function () {
+            $dependencyManager = $this->dependencyInitializer->__invoke($this->container);
+
+            expect($dependencyManager)->toBeInstanceOf(JobDependencyManagerInterface::class);
+            expect($dependencyManager)->toBeInstanceOf(DatabaseJobDependencyManager::class);
+
+            // Should be accessible from container
+            $retrieved = $this->container->get(JobDependencyManagerInterface::class);
+            expect($retrieved)->toBe($dependencyManager);
+        });
+
+        it('registers JobChainManagerInterface', function () {
+            $this->dependencyInitializer->__invoke($this->container);
+
+            $chainManager = $this->container->get(JobChainManagerInterface::class);
+            expect($chainManager)->toBeInstanceOf(JobChainManagerInterface::class);
+            expect($chainManager)->toBeInstanceOf(DatabaseJobChainManager::class);
+        });
+
+        it('registers DependencyResolutionEngine as singleton', function () {
+            $this->dependencyInitializer->__invoke($this->container);
+
+            $engine1 = $this->container->get(DependencyResolutionEngine::class);
+            $engine2 = $this->container->get(DependencyResolutionEngine::class);
+
+            expect($engine1)->toBeInstanceOf(DependencyResolutionEngine::class);
+            expect($engine1)->toBe($engine2); // Should be same instance (singleton)
+        });
+
+        it('registers JobMetricsManager as singleton', function () {
+            $this->dependencyInitializer->__invoke($this->container);
+
+            $metrics1 = $this->container->get(JobMetricsManager::class);
+            $metrics2 = $this->container->get(JobMetricsManager::class);
+
+            expect($metrics1)->toBeInstanceOf(JobMetricsManager::class);
+            expect($metrics1)->toBe($metrics2); // Should be same instance (singleton)
+        });
+    });
+
+    describe('Individual Service Registration', function () {
+        it('can register DistributedLockInterface service', function () {
+            $lockService = new DatabaseDistributedLock(
+                entityManager: $this->mockEntityManager,
+                logger: $this->mockLogger
+            );
+
+            $this->container->singleton(DistributedLockInterface::class, $lockService);
+
+            $retrieved = $this->container->get(DistributedLockInterface::class);
+            expect($retrieved)->toBe($lockService);
+            expect($retrieved)->toBeInstanceOf(DistributedLockInterface::class);
+        });
+
+        it('can register JobProgressTrackerInterface service', function () {
+            $progressTracker = new DatabaseJobProgressTracker(
+                entityManager: $this->mockEntityManager,
+                logger: $this->mockLogger
+            );
+
+            $this->container->singleton(JobProgressTrackerInterface::class, $progressTracker);
+
+            $retrieved = $this->container->get(JobProgressTrackerInterface::class);
+            expect($retrieved)->toBe($progressTracker);
+            expect($retrieved)->toBeInstanceOf(JobProgressTrackerInterface::class);
+        });
+
+        it('can register DeadLetterQueueInterface service', function () {
+            $deadLetterQueue = new DatabaseDeadLetterQueue(
+                entityManager: $this->mockEntityManager,
+                logger: $this->mockLogger
+            );
+
+            $this->container->singleton(DeadLetterQueueInterface::class, $deadLetterQueue);
+
+            $retrieved = $this->container->get(DeadLetterQueueInterface::class);
+            expect($retrieved)->toBe($deadLetterQueue);
+            expect($retrieved)->toBeInstanceOf(DeadLetterQueueInterface::class);
+        });
+
+        it('can register WorkerRegistry service', function () {
+            $workerRegistry = new WorkerRegistry(
+                entityManager: $this->mockEntityManager,
+                logger: $this->mockLogger
+            );
+
+            $this->container->singleton(WorkerRegistry::class, $workerRegistry);
+
+            $retrieved = $this->container->get(WorkerRegistry::class);
+            expect($retrieved)->toBe($workerRegistry);
+            expect($retrieved)->toBeInstanceOf(WorkerRegistry::class);
+        });
+
+        it('can register JobDistributionService', function () {
+            // First register dependencies
+            $this->container->singleton(WorkerRegistry::class, new WorkerRegistry(
+                $this->mockEntityManager,
+                $this->mockLogger
+            ));
+
+            $this->container->singleton(\App\Framework\Queue\Contracts\QueueInterface::class, function() {
+                return new class implements \App\Framework\Queue\Contracts\QueueInterface {
+                    public function push(mixed $job): void {}
+                    public function pop(): mixed { return null; }
+                    public function size(): int { return 0; }
+                };
+            });
+
+            $distributionService = new JobDistributionService(
+                workerRegistry: $this->container->get(WorkerRegistry::class),
+                queue: $this->container->get(\App\Framework\Queue\Contracts\QueueInterface::class),
+                logger: $this->mockLogger
+            );
+
+            $this->container->singleton(JobDistributionService::class, $distributionService);
+
+            $retrieved = $this->container->get(JobDistributionService::class);
+            expect($retrieved)->toBe($distributionService);
+            expect($retrieved)->toBeInstanceOf(JobDistributionService::class);
+        });
+    });
+
+    describe('Service Dependencies and Integration', function () {
+        it('services have proper dependencies injected', function () {
+            $this->dependencyInitializer->__invoke($this->container);
+
+            $dependencyManager = $this->container->get(JobDependencyManagerInterface::class);
+            $chainManager = $this->container->get(JobChainManagerInterface::class);
+            $resolutionEngine = $this->container->get(DependencyResolutionEngine::class);
+
+            // Verify dependencies are properly injected
+            expect($dependencyManager)->toBeInstanceOf(DatabaseJobDependencyManager::class);
+            expect($chainManager)->toBeInstanceOf(DatabaseJobChainManager::class);
+            expect($resolutionEngine)->toBeInstanceOf(DependencyResolutionEngine::class);
+
+            // These services should be functional (not throw errors)
+            expect(fn() => $dependencyManager)->not->toThrow();
+            expect(fn() => $chainManager)->not->toThrow();
+            expect(fn() => $resolutionEngine)->not->toThrow();
+        });
+
+        it('can resolve complex dependency graph', function () {
+            $this->dependencyInitializer->__invoke($this->container);
+
+            // Add additional services
+            $this->container->singleton(DistributedLockInterface::class, function() {
+                return new DatabaseDistributedLock(
+                    $this->mockEntityManager,
+                    $this->mockLogger
+                );
+            });
+
+            $this->container->singleton(JobProgressTrackerInterface::class, function() {
+                return new DatabaseJobProgressTracker(
+                    $this->mockEntityManager,
+                    $this->mockLogger
+                );
+            });
+
+            // All services should be resolvable
+            $services = [
+                JobDependencyManagerInterface::class,
+                JobChainManagerInterface::class,
+                DependencyResolutionEngine::class,
+                JobMetricsManager::class,
+                DistributedLockInterface::class,
+                JobProgressTrackerInterface::class,
+            ];
+
+            foreach ($services as $serviceInterface) {
+                $service = $this->container->get($serviceInterface);
+                expect($service)->not->toBeNull();
+                expect($service)->toBeObject();
+            }
+        });
+    });
+
+    describe('Service Lifecycle Management', function () {
+        it('singleton services maintain state across requests', function () {
+            $this->dependencyInitializer->__invoke($this->container);
+
+            $metrics1 = $this->container->get(JobMetricsManager::class);
+            $metrics2 = $this->container->get(JobMetricsManager::class);
+
+            // Should be exact same instance
+            expect($metrics1)->toBe($metrics2);
+        });
+
+        it('services can be replaced for testing', function () {
+            $this->dependencyInitializer->__invoke($this->container);
+
+            // Get original service
+            $original = $this->container->get(JobMetricsManager::class);
+
+            // Create mock replacement
+            $mock = new class implements JobMetricsManagerInterface {
+                public function recordJobExecution(\App\Framework\Queue\ValueObjects\JobId $jobId, float $executionTime): void {}
+                public function recordJobFailure(\App\Framework\Queue\ValueObjects\JobId $jobId, string $errorMessage): void {}
+                public function getJobMetrics(\App\Framework\Queue\ValueObjects\JobId $jobId): ?\App\Framework\Queue\ValueObjects\JobMetrics { return null; }
+                public function getQueueMetrics(\App\Framework\Queue\ValueObjects\QueueName $queueName): \App\Framework\Queue\ValueObjects\QueueMetrics {
+                    return new \App\Framework\Queue\ValueObjects\QueueMetrics(
+                        queueName: $queueName,
+                        totalJobs: 0,
+                        completedJobs: 0,
+                        failedJobs: 0,
+                        averageExecutionTime: 0.0
+                    );
+                }
+                public function getSystemMetrics(): array { return []; }
+            };
+
+            // Replace with mock
+            $this->container->instance(JobMetricsManagerInterface::class, $mock);
+
+            $replaced = $this->container->get(JobMetricsManagerInterface::class);
+            expect($replaced)->toBe($mock);
+            expect($replaced)->not->toBe($original);
+        });
+
+        it('handles missing dependencies gracefully', function () {
+            // Don't register EventDispatcher - this should cause failure
+            unset($this->container);
+            $this->container = new DefaultContainer();
+            $this->container->instance(EntityManagerInterface::class, $this->mockEntityManager);
+            $this->container->instance(Logger::class, $this->mockLogger);
+
+            $dependencyInitializer = new QueueDependencyInitializer();
+
+            // This should fail due to missing dependencies
+            expect(fn() => $dependencyInitializer->__invoke($this->container))
+                ->toThrow();
+        });
+    });
+});
+
+describe('Queue Service Integration Test', function () {
+
+    beforeEach(function () {
+        $this->container = new DefaultContainer();
+
+        // Register all required mocks
+        $this->container->instance(EntityManagerInterface::class, new class implements EntityManagerInterface {
+            public function persist(object $entity): void {}
+            public function find(string $className, mixed $id): ?object { return null; }
+            public function flush(): void {}
+            public function remove(object $entity): void {}
+            public function clear(): void {}
+            public function detach(object $entity): void {}
+            public function contains(object $entity): bool { return false; }
+            public function refresh(object $entity): void {}
+            public function createQueryBuilder(): object { return new stdClass(); }
+            public function getRepository(string $className): object { return new stdClass(); }
+            public function beginTransaction(): void {}
+            public function commit(): void {}
+            public function rollback(): void {}
+            public function isTransactionActive(): bool { return false; }
+        });
+
+        $this->container->instance(Logger::class, new class implements Logger {
+            public function emergency(string $message, array $context = []): void {}
+            public function alert(string $message, array $context = []): void {}
+            public function critical(string $message, array $context = []): void {}
+            public function error(string $message, array $context = []): void {}
+            public function warning(string $message, array $context = []): void {}
+            public function notice(string $message, array $context = []): void {}
+            public function info(string $message, array $context = []): void {}
+            public function debug(string $message, array $context = []): void {}
+            public function log(string $level, string $message, array $context = []): void {}
+        });
+
+        $this->container->singleton(\App\Framework\Queue\Contracts\QueueInterface::class, function() {
+            return new class implements \App\Framework\Queue\Contracts\QueueInterface {
+                public function push(mixed $job): void {}
+                public function pop(): mixed { return null; }
+                public function size(): int { return 0; }
+            };
+        });
+
+        $this->container->singleton(\App\Framework\Core\Events\EventDispatcherInterface::class, function() {
+            return new class implements \App\Framework\Core\Events\EventDispatcherInterface {
+                public function dispatch(object $event): void {}
+                public function listen(string $event, callable $listener): void {}
+            };
+        });
+    });
+
+    it('can initialize complete queue system', function () {
+        // Initialize all queue services
+        $dependencyInitializer = new QueueDependencyInitializer();
+        $dependencyInitializer->__invoke($this->container);
+
+        // Register additional services that would normally be auto-registered
+        $this->container->singleton(DistributedLockInterface::class, function($container) {
+            return new DatabaseDistributedLock(
+                $container->get(EntityManagerInterface::class),
+                $container->get(Logger::class)
+            );
+        });
+
+        $this->container->singleton(JobProgressTrackerInterface::class, function($container) {
+            return new DatabaseJobProgressTracker(
+                $container->get(EntityManagerInterface::class),
+                $container->get(Logger::class)
+            );
+        });
+
+        $this->container->singleton(DeadLetterQueueInterface::class, function($container) {
+            return new DatabaseDeadLetterQueue(
+                $container->get(EntityManagerInterface::class),
+                $container->get(Logger::class)
+            );
+        });
+
+        $this->container->singleton(WorkerRegistry::class, function($container) {
+            return new WorkerRegistry(
+                $container->get(EntityManagerInterface::class),
+                $container->get(Logger::class)
+            );
+        });
+
+        // Verify all 9 expected queue services are registered
+        $expectedServices = [
+            DistributedLockInterface::class,
+            WorkerRegistry::class,
+            JobDistributionService::class, // This might not be auto-registered
+            WorkerHealthCheckService::class, // This might not be auto-registered
+            FailoverRecoveryService::class, // This might not be auto-registered
+            JobProgressTrackerInterface::class,
+            DeadLetterQueueInterface::class,
+            JobMetricsManagerInterface::class,
+            JobDependencyManagerInterface::class,
+        ];
+
+        $registeredCount = 0;
+        foreach ($expectedServices as $service) {
+            try {
+                $instance = $this->container->get($service);
+                if ($instance !== null) {
+                    $registeredCount++;
+                }
+            } catch (\Exception $e) {
+                // Service not registered, which is expected for some
+            }
+        }
+
+        // At least the core services should be registered
+        expect($registeredCount)->toBeGreaterThan(4);
+    });
+
+    it('services can interact without errors', function () {
+        $dependencyInitializer = new QueueDependencyInitializer();
+        $dependencyInitializer->__invoke($this->container);
+
+        $dependencyManager = $this->container->get(JobDependencyManagerInterface::class);
+        $chainManager = $this->container->get(JobChainManagerInterface::class);
+        $metricsManager = $this->container->get(JobMetricsManager::class);
+
+        // Basic interaction tests (should not throw)
+        expect(fn() => $dependencyManager)->not->toThrow();
+        expect(fn() => $chainManager)->not->toThrow();
+        expect(fn() => $metricsManager)->not->toThrow();
+    });
+});

tests/Framework/Queue/QueueTest.php

@@ -0,0 +1,340 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\InMemoryQueue;
+use App\Framework\Queue\ValueObjects\JobPayload;
+use App\Framework\Queue\ValueObjects\QueuePriority;
+use App\Framework\Core\ValueObjects\Duration;
+
+describe('Queue Interface Basic Operations', function () {
+
+    beforeEach(function () {
+        $this->queue = new InMemoryQueue();
+        $this->testJob = new class {
+            public function handle(): string
+            {
+                return 'test job executed';
+            }
+        };
+    });
+
+    describe('push() operation', function () {
+        it('can push jobs to queue', function () {
+            $payload = JobPayload::create($this->testJob);
+
+            $this->queue->push($payload);
+
+            expect($this->queue->size())->toBe(1);
+        });
+
+        it('maintains priority order when pushing multiple jobs', function () {
+            $lowPriorityJob = JobPayload::create($this->testJob, QueuePriority::low());
+            $highPriorityJob = JobPayload::create($this->testJob, QueuePriority::high());
+            $criticalJob = JobPayload::create($this->testJob, QueuePriority::critical());
+
+            // Push in random order
+            $this->queue->push($lowPriorityJob);
+            $this->queue->push($criticalJob);
+            $this->queue->push($highPriorityJob);
+
+            expect($this->queue->size())->toBe(3);
+
+            // Peek should return critical priority first
+            $next = $this->queue->peek();
+            expect($next->priority->isCritical())->toBeTrue();
+        });
+
+        it('accepts jobs with different configurations', function () {
+            $immediateJob = JobPayload::immediate($this->testJob);
+            $delayedJob = JobPayload::delayed($this->testJob, Duration::fromSeconds(30));
+            $backgroundJob = JobPayload::background($this->testJob);
+            $criticalJob = JobPayload::critical($this->testJob);
+
+            $this->queue->push($immediateJob);
+            $this->queue->push($delayedJob);
+            $this->queue->push($backgroundJob);
+            $this->queue->push($criticalJob);
+
+            expect($this->queue->size())->toBe(4);
+        });
+    });
+
+    describe('pop() operation', function () {
+        it('returns null when queue is empty', function () {
+            expect($this->queue->pop())->toBeNull();
+        });
+
+        it('returns and removes highest priority job first', function () {
+            $lowJob = JobPayload::create($this->testJob, QueuePriority::low());
+            $highJob = JobPayload::create($this->testJob, QueuePriority::high());
+
+            $this->queue->push($lowJob);
+            $this->queue->push($highJob);
+
+            $popped = $this->queue->pop();
+            expect($popped->priority->isHigh())->toBeTrue();
+            expect($this->queue->size())->toBe(1);
+
+            $remaining = $this->queue->pop();
+            expect($remaining->priority->isLow())->toBeTrue();
+            expect($this->queue->size())->toBe(0);
+        });
+
+        it('processes FIFO for same priority jobs', function () {
+            $job1 = new class { public $id = 1; };
+            $job2 = new class { public $id = 2; };
+
+            $payload1 = JobPayload::create($job1, QueuePriority::normal());
+            $payload2 = JobPayload::create($job2, QueuePriority::normal());
+
+            $this->queue->push($payload1);
+            $this->queue->push($payload2);
+
+            $first = $this->queue->pop();
+            expect($first->job->id)->toBe(1);
+
+            $second = $this->queue->pop();
+            expect($second->job->id)->toBe(2);
+        });
+    });
+
+    describe('peek() operation', function () {
+        it('returns null when queue is empty', function () {
+            expect($this->queue->peek())->toBeNull();
+        });
+
+        it('returns next job without removing it', function () {
+            $payload = JobPayload::create($this->testJob);
+            $this->queue->push($payload);
+
+            $peeked = $this->queue->peek();
+            expect($peeked)->not->toBeNull();
+            expect($this->queue->size())->toBe(1);
+
+            // Should return same job when peeked again
+            $peekedAgain = $this->queue->peek();
+            expect($peekedAgain)->toBe($peeked);
+        });
+
+        it('shows highest priority job', function () {
+            $normalJob = JobPayload::create($this->testJob, QueuePriority::normal());
+            $criticalJob = JobPayload::create($this->testJob, QueuePriority::critical());
+
+            $this->queue->push($normalJob);
+            $this->queue->push($criticalJob);
+
+            $peeked = $this->queue->peek();
+            expect($peeked->priority->isCritical())->toBeTrue();
+        });
+    });
+
+    describe('size() operation', function () {
+        it('returns 0 for empty queue', function () {
+            expect($this->queue->size())->toBe(0);
+        });
+
+        it('tracks size correctly as jobs are added and removed', function () {
+            expect($this->queue->size())->toBe(0);
+
+            $this->queue->push(JobPayload::create($this->testJob));
+            expect($this->queue->size())->toBe(1);
+
+            $this->queue->push(JobPayload::create($this->testJob));
+            expect($this->queue->size())->toBe(2);
+
+            $this->queue->pop();
+            expect($this->queue->size())->toBe(1);
+
+            $this->queue->pop();
+            expect($this->queue->size())->toBe(0);
+        });
+    });
+
+    describe('clear() operation', function () {
+        it('returns 0 when clearing empty queue', function () {
+            expect($this->queue->clear())->toBe(0);
+        });
+
+        it('removes all jobs and returns count', function () {
+            $this->queue->push(JobPayload::create($this->testJob));
+            $this->queue->push(JobPayload::create($this->testJob));
+            $this->queue->push(JobPayload::create($this->testJob));
+
+            expect($this->queue->size())->toBe(3);
+
+            $cleared = $this->queue->clear();
+            expect($cleared)->toBe(3);
+            expect($this->queue->size())->toBe(0);
+        });
+
+        it('queue is usable after clearing', function () {
+            $this->queue->push(JobPayload::create($this->testJob));
+            $this->queue->clear();
+
+            // Should be able to add new jobs
+            $this->queue->push(JobPayload::create($this->testJob));
+            expect($this->queue->size())->toBe(1);
+        });
+    });
+
+    describe('getStats() operation', function () {
+        it('returns basic stats for empty queue', function () {
+            $stats = $this->queue->getStats();
+
+            expect($stats)->toHaveKey('size');
+            expect($stats['size'])->toBe(0);
+            expect($stats)->toHaveKey('priority_breakdown');
+            expect($stats['priority_breakdown'])->toBe([]);
+        });
+
+        it('provides priority breakdown for populated queue', function () {
+            $this->queue->push(JobPayload::create($this->testJob, QueuePriority::high()));
+            $this->queue->push(JobPayload::create($this->testJob, QueuePriority::high()));
+            $this->queue->push(JobPayload::create($this->testJob, QueuePriority::normal()));
+            $this->queue->push(JobPayload::create($this->testJob, QueuePriority::low()));
+
+            $stats = $this->queue->getStats();
+
+            expect($stats['size'])->toBe(4);
+            expect($stats['priority_breakdown']['high'])->toBe(2);
+            expect($stats['priority_breakdown']['normal'])->toBe(1);
+            expect($stats['priority_breakdown']['low'])->toBe(1);
+        });
+
+        it('updates stats as queue changes', function () {
+            $this->queue->push(JobPayload::create($this->testJob, QueuePriority::critical()));
+            $this->queue->push(JobPayload::create($this->testJob, QueuePriority::normal()));
+
+            $stats = $this->queue->getStats();
+            expect($stats['size'])->toBe(2);
+            expect($stats['priority_breakdown']['critical'])->toBe(1);
+
+            // Remove one job
+            $this->queue->pop();
+            $updatedStats = $this->queue->getStats();
+            expect($updatedStats['size'])->toBe(1);
+            expect($updatedStats['priority_breakdown']['critical'])->toBe(0);
+            expect($updatedStats['priority_breakdown']['normal'])->toBe(1);
+        });
+    });
+});
+
+describe('Queue Priority Processing', function () {
+
+    beforeEach(function () {
+        $this->queue = new InMemoryQueue();
+    });
+
+    it('processes jobs in correct priority order', function () {
+        $jobs = [];
+
+        // Create jobs with different priorities
+        $jobs['low'] = JobPayload::create(new class { public $type = 'low'; }, QueuePriority::low());
+        $jobs['deferred'] = JobPayload::create(new class { public $type = 'deferred'; }, QueuePriority::deferred());
+        $jobs['normal'] = JobPayload::create(new class { public $type = 'normal'; }, QueuePriority::normal());
+        $jobs['high'] = JobPayload::create(new class { public $type = 'high'; }, QueuePriority::high());
+        $jobs['critical'] = JobPayload::create(new class { public $type = 'critical'; }, QueuePriority::critical());
+
+        // Push in random order
+        $this->queue->push($jobs['normal']);
+        $this->queue->push($jobs['deferred']);
+        $this->queue->push($jobs['critical']);
+        $this->queue->push($jobs['low']);
+        $this->queue->push($jobs['high']);
+
+        // Pop should return in priority order
+        $order = [];
+        while (($job = $this->queue->pop()) !== null) {
+            $order[] = $job->job->type;
+        }
+
+        expect($order)->toBe(['critical', 'high', 'normal', 'low', 'deferred']);
+    });
+
+    it('handles custom priority values correctly', function () {
+        $customHigh = JobPayload::create(new class { public $id = 'custom_high'; }, new QueuePriority(500));
+        $customLow = JobPayload::create(new class { public $id = 'custom_low'; }, new QueuePriority(-50));
+        $standardHigh = JobPayload::create(new class { public $id = 'standard_high'; }, QueuePriority::high());
+
+        $this->queue->push($customLow);
+        $this->queue->push($standardHigh);
+        $this->queue->push($customHigh);
+
+        $first = $this->queue->pop();
+        expect($first->job->id)->toBe('custom_high'); // 500 priority
+
+        $second = $this->queue->pop();
+        expect($second->job->id)->toBe('standard_high'); // 100 priority
+
+        $third = $this->queue->pop();
+        expect($third->job->id)->toBe('custom_low'); // -50 priority
+    });
+});
+
+describe('Queue Edge Cases', function () {
+
+    beforeEach(function () {
+        $this->queue = new InMemoryQueue();
+    });
+
+    it('handles many operations on empty queue gracefully', function () {
+        expect($this->queue->pop())->toBeNull();
+        expect($this->queue->pop())->toBeNull();
+        expect($this->queue->peek())->toBeNull();
+        expect($this->queue->peek())->toBeNull();
+        expect($this->queue->size())->toBe(0);
+        expect($this->queue->clear())->toBe(0);
+        expect($this->queue->clear())->toBe(0);
+    });
+
+    it('maintains integrity after mixed operations', function () {
+        $job = new class { public $data = 'test'; };
+
+        // Complex sequence of operations
+        $this->queue->push(JobPayload::create($job));
+        expect($this->queue->size())->toBe(1);
+
+        $peeked = $this->queue->peek();
+        expect($peeked->job->data)->toBe('test');
+        expect($this->queue->size())->toBe(1);
+
+        $popped = $this->queue->pop();
+        expect($popped->job->data)->toBe('test');
+        expect($this->queue->size())->toBe(0);
+
+        expect($this->queue->peek())->toBeNull();
+        expect($this->queue->pop())->toBeNull();
+
+        // Add more after emptying
+        $this->queue->push(JobPayload::create($job));
+        expect($this->queue->size())->toBe(1);
+    });
+
+    it('handles large number of jobs efficiently', function () {
+        $start = microtime(true);
+
+        // Add 1000 jobs
+        for ($i = 0; $i < 1000; $i++) {
+            $job = new class {
+                public function __construct(public int $id) {}
+            };
+            $payload = JobPayload::create(new $job($i), QueuePriority::normal());
+            $this->queue->push($payload);
+        }
+
+        expect($this->queue->size())->toBe(1000);
+
+        // Process all jobs
+        $processed = 0;
+        while ($this->queue->pop() !== null) {
+            $processed++;
+        }
+
+        expect($processed)->toBe(1000);
+        expect($this->queue->size())->toBe(0);
+
+        $elapsed = microtime(true) - $start;
+        expect($elapsed)->toBeLessThan(1.0); // Should complete within 1 second
+    });
+});

tests/Framework/Queue/Services/ProgressManagerTest.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\Services\ProgressManager;
+use App\Framework\Queue\Contracts\JobProgressTrackerInterface;
+use App\Framework\Queue\ValueObjects\JobProgress;
+use App\Framework\Core\ValueObjects\Percentage;
+
+beforeEach(function () {
+    // Mock the progress tracker interface instead of final classes
+    $this->progressTracker = mock(JobProgressTrackerInterface::class);
+    $this->progressManager = new ProgressManager($this->progressTracker);
+});
+
+it('can start a job', function () {
+    $jobId = 'test-job-123';
+
+    $this->progressTracker
+        ->shouldReceive('updateProgress')
+        ->once()
+        ->with($jobId, \Mockery::type(JobProgress::class), null)
+        ->andReturn(null);
+
+    $this->progressManager->startJob($jobId);
+
+    expect(true)->toBeTrue(); // If no exception thrown, test passes
+});
+
+it('can update job progress', function () {
+    $jobId = 'test-job-123';
+    $percentage = 50.0;
+    $message = 'Halfway done';
+
+    $this->progressTracker
+        ->shouldReceive('updateProgress')
+        ->once()
+        ->with($jobId, \Mockery::type(JobProgress::class), null)
+        ->andReturn(null);
+
+    $this->progressManager->updateJobProgress($jobId, $percentage, $message);
+
+    expect(true)->toBeTrue(); // If no exception thrown, test passes
+});
+
+it('can complete a job', function () {
+    $jobId = 'test-job-123';
+    $message = 'Job completed successfully';
+
+    $this->progressTracker
+        ->shouldReceive('markJobCompleted')
+        ->once()
+        ->with($jobId, $message)
+        ->andReturn(null);
+
+    $this->progressManager->completeJob($jobId, $message);
+
+    expect(true)->toBeTrue(); // If no exception thrown, test passes
+});
+
+it('can create step tracker', function () {
+    $jobId = 'test-job-123';
+    $steps = [
+        ['name' => 'step1', 'description' => 'First step'],
+        ['name' => 'step2', 'description' => 'Second step']
+    ];
+
+    $stepTracker = $this->progressManager->createStepTracker($jobId, $steps);
+
+    expect($stepTracker)->toBeInstanceOf(\App\Framework\Queue\Services\StepProgressTracker::class);
+    expect($stepTracker->getCurrentStep())->toBe($steps[0]);
+    expect($stepTracker->isComplete())->toBeFalse();
+    expect($stepTracker->getProgress())->toBe(0.0);
+});
+
+it('throws exception for empty steps array', function () {
+    $jobId = 'test-job-123';
+    $steps = [];
+
+    expect(fn() => $this->progressManager->createStepTracker($jobId, $steps))
+        ->toThrow(\InvalidArgumentException::class, 'Steps array cannot be empty');
+});
+
+it('throws exception for invalid step structure', function () {
+    $jobId = 'test-job-123';
+    $steps = [
+        ['name' => 'step1'], // Missing description
+    ];
+
+    expect(fn() => $this->progressManager->createStepTracker($jobId, $steps))
+        ->toThrow(\InvalidArgumentException::class);
+});

tests/Framework/Queue/ValueObjects/JobIdTest.php

@@ -0,0 +1,345 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\ValueObjects\JobId;
+use App\Framework\Ulid\Ulid;
+
+describe('JobId Value Object', function () {
+
+    describe('Creation and Validation', function () {
+        it('can generate unique JobIds', function () {
+            $id1 = JobId::generate();
+            $id2 = JobId::generate();
+
+            expect($id1)->toBeInstanceOf(JobId::class);
+            expect($id2)->toBeInstanceOf(JobId::class);
+            expect($id1->toString())->not->toBe($id2->toString());
+        });
+
+        it('can create from string', function () {
+            $idString = 'job_test_123';
+            $jobId = JobId::fromString($idString);
+
+            expect($jobId->toString())->toBe($idString);
+            expect($jobId->getValue())->toBe($idString);
+        });
+
+        it('can create from ULID object', function () {
+            $ulid = Ulid::generate();
+            $jobId = JobId::fromUlid($ulid);
+
+            expect($jobId->toString())->toBe($ulid->toString());
+            expect($jobId->toUlid()->toString())->toBe($ulid->toString());
+        });
+
+        it('rejects empty JobId', function () {
+            expect(fn() => JobId::fromString(''))
+                ->toThrow(\InvalidArgumentException::class, 'JobId cannot be empty');
+        });
+
+        it('validates JobId format correctly', function () {
+            // Valid formats should work
+            expect(fn() => JobId::fromString('job_12345'))->not->toThrow();
+            expect(fn() => JobId::fromString('01FXYZ0123456789ABCDEF1234'))->not->toThrow(); // ULID format
+            expect(fn() => JobId::fromString('simple-id'))->not->toThrow();
+
+            // Any non-empty string is currently accepted
+            expect(fn() => JobId::fromString('a'))->not->toThrow();
+            expect(fn() => JobId::fromString('very-long-job-identifier-12345'))->not->toThrow();
+        });
+
+        it('is readonly and immutable', function () {
+            $jobId = JobId::fromString('test-job-123');
+
+            // Verify the class is readonly
+            $reflection = new ReflectionClass($jobId);
+            expect($reflection->isReadOnly())->toBeTrue();
+
+            // The value property should be readonly
+            $valueProperty = $reflection->getProperty('value');
+            expect($valueProperty->isReadOnly())->toBeTrue();
+        });
+    });
+
+    describe('String Representation', function () {
+        it('toString() returns the internal value', function () {
+            $value = 'test-job-456';
+            $jobId = JobId::fromString($value);
+
+            expect($jobId->toString())->toBe($value);
+        });
+
+        it('getValue() is alias for toString()', function () {
+            $value = 'another-test-job';
+            $jobId = JobId::fromString($value);
+
+            expect($jobId->getValue())->toBe($jobId->toString());
+            expect($jobId->getValue())->toBe($value);
+        });
+
+        it('__toString() magic method works', function () {
+            $value = 'magic-method-test';
+            $jobId = JobId::fromString($value);
+
+            expect((string) $jobId)->toBe($value);
+            expect("Job ID: {$jobId}")->toBe("Job ID: {$value}");
+        });
+
+        it('jsonSerialize() returns string value', function () {
+            $value = 'json-test-job';
+            $jobId = JobId::fromString($value);
+
+            expect($jobId->jsonSerialize())->toBe($value);
+            expect(json_encode($jobId))->toBe('"' . $value . '"');
+        });
+    });
+
+    describe('Equality and Comparison', function () {
+        it('equals() compares JobIds correctly', function () {
+            $id1 = JobId::fromString('same-id');
+            $id2 = JobId::fromString('same-id');
+            $id3 = JobId::fromString('different-id');
+
+            expect($id1->equals($id2))->toBeTrue();
+            expect($id1->equals($id3))->toBeFalse();
+            expect($id2->equals($id3))->toBeFalse();
+        });
+
+        it('isBefore() and isAfter() compare string values', function () {
+            $idA = JobId::fromString('aaa');
+            $idB = JobId::fromString('bbb');
+            $idC = JobId::fromString('ccc');
+
+            expect($idA->isBefore($idB))->toBeTrue();
+            expect($idB->isBefore($idC))->toBeTrue();
+            expect($idA->isBefore($idC))->toBeTrue();
+
+            expect($idC->isAfter($idB))->toBeTrue();
+            expect($idB->isAfter($idA))->toBeTrue();
+            expect($idC->isAfter($idA))->toBeTrue();
+
+            expect($idB->isBefore($idA))->toBeFalse();
+            expect($idA->isAfter($idB))->toBeFalse();
+        });
+
+        it('comparison works with numeric-like strings', function () {
+            $id1 = JobId::fromString('job_001');
+            $id2 = JobId::fromString('job_002');
+            $id10 = JobId::fromString('job_010');
+
+            expect($id1->isBefore($id2))->toBeTrue();
+            expect($id2->isBefore($id10))->toBeTrue();
+            expect($id10->isAfter($id1))->toBeTrue();
+        });
+    });
+
+    describe('ULID Integration', function () {
+        it('can convert to ULID when valid format', function () {
+            $originalUlid = Ulid::generate();
+            $jobId = JobId::fromUlid($originalUlid);
+            $convertedUlid = $jobId->toUlid();
+
+            expect($convertedUlid->toString())->toBe($originalUlid->toString());
+        });
+
+        it('getTimestamp() extracts timestamp from ULID', function () {
+            $ulid = Ulid::generate();
+            $jobId = JobId::fromUlid($ulid);
+
+            $timestamp = $jobId->getTimestamp();
+            expect($timestamp)->toBeInstanceOf(\DateTimeImmutable::class);
+
+            // Should be very recent
+            $now = new \DateTimeImmutable();
+            $diff = $now->getTimestamp() - $timestamp->getTimestamp();
+            expect($diff)->toBeLessThan(5); // Within 5 seconds
+        });
+
+        it('generateForQueue() creates ULID-based JobId', function () {
+            $jobId = JobId::generateForQueue('email-queue');
+
+            expect($jobId)->toBeInstanceOf(JobId::class);
+            expect(strlen($jobId->toString()))->toBe(26); // ULID length
+        });
+
+        it('getTimePrefix() extracts time portion', function () {
+            $jobId = JobId::generateForQueue('test-queue');
+            $timePrefix = $jobId->getTimePrefix();
+
+            expect($timePrefix)->toBeString();
+            expect(strlen($timePrefix))->toBe(10);
+        });
+
+        it('getRandomSuffix() extracts random portion', function () {
+            $jobId = JobId::generateForQueue('test-queue');
+            $randomSuffix = $jobId->getRandomSuffix();
+
+            expect($randomSuffix)->toBeString();
+            expect(strlen($randomSuffix))->toBe(16);
+        });
+    });
+
+    describe('Edge Cases and Error Handling', function () {
+        it('handles very long job IDs', function () {
+            $longId = str_repeat('a', 1000);
+            $jobId = JobId::fromString($longId);
+
+            expect($jobId->toString())->toBe($longId);
+            expect(strlen($jobId->toString()))->toBe(1000);
+        });
+
+        it('handles special characters in job IDs', function () {
+            $specialId = 'job-with_special.chars@123!';
+            $jobId = JobId::fromString($specialId);
+
+            expect($jobId->toString())->toBe($specialId);
+        });
+
+        it('handles unicode characters', function () {
+            $unicodeId = 'job-测试-🚀-123';
+            $jobId = JobId::fromString($unicodeId);
+
+            expect($jobId->toString())->toBe($unicodeId);
+        });
+
+        it('toUlid() may fail for non-ULID format strings', function () {
+            $nonUlidJobId = JobId::fromString('not-a-ulid-format');
+
+            // This should throw an exception since it's not a valid ULID
+            expect(fn() => $nonUlidJobId->toUlid())
+                ->toThrow();
+        });
+
+        it('getTimestamp() may fail for non-ULID format', function () {
+            $nonUlidJobId = JobId::fromString('simple-job-id');
+
+            // This should throw an exception since it's not a valid ULID
+            expect(fn() => $nonUlidJobId->getTimestamp())
+                ->toThrow();
+        });
+    });
+
+    describe('Performance and Uniqueness', function () {
+        it('generates unique IDs in rapid succession', function () {
+            $ids = [];
+            $count = 1000;
+
+            $start = microtime(true);
+
+            for ($i = 0; $i < $count; $i++) {
+                $id = JobId::generate();
+                $ids[] = $id->toString();
+            }
+
+            $elapsed = microtime(true) - $start;
+
+            // All IDs should be unique
+            $unique = array_unique($ids);
+            expect(count($unique))->toBe($count);
+
+            // Should generate quickly
+            expect($elapsed)->toBeLessThan(1.0); // Within 1 second
+        });
+
+        it('ULID-based IDs are time-ordered', function () {
+            $ids = [];
+
+            // Generate several IDs with small delays
+            for ($i = 0; $i < 5; $i++) {
+                $ids[] = JobId::generateForQueue('test');
+                if ($i < 4) {
+                    usleep(1000); // 1ms delay
+                }
+            }
+
+            // Each ID should be "after" the previous one (time-ordered)
+            for ($i = 1; $i < count($ids); $i++) {
+                expect($ids[$i]->isAfter($ids[$i - 1]))->toBeTrue();
+            }
+        });
+
+        it('maintains consistent string representation', function () {
+            $jobId = JobId::fromString('consistent-test');
+
+            // Multiple calls should return the same result
+            expect($jobId->toString())->toBe($jobId->toString());
+            expect($jobId->getValue())->toBe($jobId->toString());
+            expect((string) $jobId)->toBe($jobId->toString());
+            expect($jobId->jsonSerialize())->toBe($jobId->toString());
+        });
+    });
+});
+
+describe('JobId in Queue Context', function () {
+
+    it('can be used as array keys', function () {
+        $id1 = JobId::fromString('job-1');
+        $id2 = JobId::fromString('job-2');
+
+        $jobs = [];
+        $jobs[$id1->toString()] = 'First Job';
+        $jobs[$id2->toString()] = 'Second Job';
+
+        expect($jobs[$id1->toString()])->toBe('First Job');
+        expect($jobs[$id2->toString()])->toBe('Second Job');
+        expect(count($jobs))->toBe(2);
+    });
+
+    it('works with job tracking scenarios', function () {
+        $processingJobs = [];
+        $completedJobs = [];
+
+        // Simulate job lifecycle
+        $jobId = JobId::generate();
+
+        // Job starts processing
+        $processingJobs[$jobId->toString()] = time();
+        expect(isset($processingJobs[$jobId->toString()]))->toBeTrue();
+
+        // Job completes
+        $completedJobs[$jobId->toString()] = [
+            'started_at' => $processingJobs[$jobId->toString()],
+            'completed_at' => time(),
+            'status' => 'success'
+        ];
+        unset($processingJobs[$jobId->toString()]);
+
+        expect(isset($processingJobs[$jobId->toString()]))->toBeFalse();
+        expect(isset($completedJobs[$jobId->toString()]))->toBeTrue();
+        expect($completedJobs[$jobId->toString()]['status'])->toBe('success');
+    });
+
+    it('demonstrates time-based job identification', function () {
+        // Generate jobs for different queues
+        $emailJobId = JobId::generateForQueue('email');
+        $reportJobId = JobId::generateForQueue('reports');
+        $backgroundJobId = JobId::generateForQueue('background');
+
+        // All should be unique
+        expect($emailJobId->toString())->not->toBe($reportJobId->toString());
+        expect($reportJobId->toString())->not->toBe($backgroundJobId->toString());
+        expect($backgroundJobId->toString())->not->toBe($emailJobId->toString());
+
+        // All should have ULID format (26 characters)
+        expect(strlen($emailJobId->toString()))->toBe(26);
+        expect(strlen($reportJobId->toString()))->toBe(26);
+        expect(strlen($backgroundJobId->toString()))->toBe(26);
+    });
+
+    it('supports job priority scenarios', function () {
+        // Generate jobs with time component
+        $urgentJob = JobId::generateForQueue('urgent');
+        sleep(1); // Ensure different timestamp
+        $normalJob = JobId::generateForQueue('normal');
+
+        // Later job should have later timestamp
+        expect($normalJob->isAfter($urgentJob))->toBeTrue();
+
+        // Can use timestamps for ordering
+        $urgentTime = $urgentJob->getTimestamp();
+        $normalTime = $normalJob->getTimestamp();
+
+        expect($normalTime > $urgentTime)->toBeTrue();
+    });
+});

tests/Framework/Queue/ValueObjects/JobPayloadTest.php

@@ -0,0 +1,484 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\ValueObjects\JobPayload;
+use App\Framework\Queue\ValueObjects\QueuePriority;
+use App\Framework\Queue\ValueObjects\JobMetadata;
+use App\Framework\Core\ValueObjects\Duration;
+use App\Framework\Retry\Strategies\ExponentialBackoffStrategy;
+use App\Framework\Retry\Strategies\FixedDelayStrategy;
+
+describe('JobPayload Value Object', function () {
+
+    beforeEach(function () {
+        $this->simpleJob = new class {
+            public function handle(): string {
+                return 'executed';
+            }
+        };
+
+        $this->complexJob = new class {
+            public function __construct(
+                public string $id = 'test-123',
+                public array $data = ['key' => 'value']
+            ) {}
+
+            public function process(): array {
+                return $this->data;
+            }
+        };
+    });
+
+    describe('Basic Construction', function () {
+        it('can be created with minimal parameters', function () {
+            $payload = JobPayload::create($this->simpleJob);
+
+            expect($payload->job)->toBe($this->simpleJob);
+            expect($payload->priority->isNormal())->toBeTrue();
+            expect($payload->delay->toSeconds())->toBe(0);
+            expect($payload->timeout)->toBeNull();
+            expect($payload->retryStrategy)->toBeNull();
+            expect($payload->metadata)->not->toBeNull();
+        });
+
+        it('accepts all configuration parameters', function () {
+            $priority = QueuePriority::high();
+            $delay = Duration::fromMinutes(5);
+            $timeout = Duration::fromSeconds(30);
+            $retryStrategy = new ExponentialBackoffStrategy(maxAttempts: 3);
+            $metadata = JobMetadata::create(['user_id' => 123]);
+
+            $payload = JobPayload::create(
+                $this->complexJob,
+                $priority,
+                $delay,
+                $timeout,
+                $retryStrategy,
+                $metadata
+            );
+
+            expect($payload->job)->toBe($this->complexJob);
+            expect($payload->priority)->toBe($priority);
+            expect($payload->delay)->toBe($delay);
+            expect($payload->timeout)->toBe($timeout);
+            expect($payload->retryStrategy)->toBe($retryStrategy);
+            expect($payload->metadata)->toBe($metadata);
+        });
+
+        it('is immutable - readonly properties cannot be changed', function () {
+            $payload = JobPayload::create($this->simpleJob);
+
+            // This would cause a PHP error if attempted:
+            // $payload->job = new stdClass(); // Fatal error: Cannot modify readonly property
+            // $payload->priority = QueuePriority::high(); // Fatal error: Cannot modify readonly property
+
+            // Test that the properties are indeed readonly
+            $reflection = new ReflectionClass($payload);
+            foreach (['job', 'priority', 'delay', 'timeout', 'retryStrategy', 'metadata'] as $prop) {
+                $property = $reflection->getProperty($prop);
+                expect($property->isReadOnly())->toBeTrue("Property {$prop} should be readonly");
+            }
+        });
+    });
+
+    describe('Factory Methods', function () {
+        it('creates immediate jobs with high priority and no delay', function () {
+            $payload = JobPayload::immediate($this->simpleJob);
+
+            expect($payload->priority->isHigh())->toBeTrue();
+            expect($payload->delay->toSeconds())->toBe(0);
+            expect($payload->isReady())->toBeTrue();
+        });
+
+        it('creates delayed jobs with specified delay', function () {
+            $delay = Duration::fromMinutes(15);
+            $payload = JobPayload::delayed($this->simpleJob, $delay);
+
+            expect($payload->delay)->toBe($delay);
+            expect($payload->isDelayed())->toBeTrue();
+            expect($payload->isReady())->toBeFalse();
+        });
+
+        it('creates critical jobs with critical priority and short timeout', function () {
+            $payload = JobPayload::critical($this->simpleJob);
+
+            expect($payload->priority->isCritical())->toBeTrue();
+            expect($payload->delay->toSeconds())->toBe(0);
+            expect($payload->timeout->toSeconds())->toBe(30);
+            expect($payload->hasTimeout())->toBeTrue();
+        });
+
+        it('creates background jobs with low priority and retry strategy', function () {
+            $payload = JobPayload::background($this->simpleJob);
+
+            expect($payload->priority->isLow())->toBeTrue();
+            expect($payload->timeout->toMinutes())->toBe(30);
+            expect($payload->hasRetryStrategy())->toBeTrue();
+            expect($payload->retryStrategy->getMaxAttempts())->toBe(5);
+        });
+    });
+
+    describe('Immutable Transformations', function () {
+        beforeEach(function () {
+            $this->originalPayload = JobPayload::create(
+                $this->simpleJob,
+                QueuePriority::normal(),
+                Duration::zero()
+            );
+        });
+
+        it('withPriority() creates new instance with different priority', function () {
+            $newPriority = QueuePriority::high();
+            $newPayload = $this->originalPayload->withPriority($newPriority);
+
+            expect($newPayload)->not->toBe($this->originalPayload);
+            expect($newPayload->priority)->toBe($newPriority);
+            expect($newPayload->job)->toBe($this->originalPayload->job);
+            expect($newPayload->delay)->toBe($this->originalPayload->delay);
+
+            // Original should be unchanged
+            expect($this->originalPayload->priority->isNormal())->toBeTrue();
+        });
+
+        it('withDelay() creates new instance with different delay', function () {
+            $newDelay = Duration::fromMinutes(10);
+            $newPayload = $this->originalPayload->withDelay($newDelay);
+
+            expect($newPayload)->not->toBe($this->originalPayload);
+            expect($newPayload->delay)->toBe($newDelay);
+            expect($newPayload->job)->toBe($this->originalPayload->job);
+            expect($newPayload->priority)->toBe($this->originalPayload->priority);
+
+            // Original should be unchanged
+            expect($this->originalPayload->delay->toSeconds())->toBe(0);
+        });
+
+        it('withTimeout() creates new instance with timeout', function () {
+            $timeout = Duration::fromSeconds(45);
+            $newPayload = $this->originalPayload->withTimeout($timeout);
+
+            expect($newPayload)->not->toBe($this->originalPayload);
+            expect($newPayload->timeout)->toBe($timeout);
+            expect($newPayload->hasTimeout())->toBeTrue();
+
+            // Original should be unchanged
+            expect($this->originalPayload->timeout)->toBeNull();
+        });
+
+        it('withRetryStrategy() creates new instance with retry strategy', function () {
+            $retryStrategy = new FixedDelayStrategy(Duration::fromSeconds(30), 3);
+            $newPayload = $this->originalPayload->withRetryStrategy($retryStrategy);
+
+            expect($newPayload)->not->toBe($this->originalPayload);
+            expect($newPayload->retryStrategy)->toBe($retryStrategy);
+            expect($newPayload->hasRetryStrategy())->toBeTrue();
+
+            // Original should be unchanged
+            expect($this->originalPayload->retryStrategy)->toBeNull();
+        });
+
+        it('withMetadata() creates new instance with metadata', function () {
+            $metadata = JobMetadata::create(['source' => 'test', 'version' => '1.0']);
+            $newPayload = $this->originalPayload->withMetadata($metadata);
+
+            expect($newPayload)->not->toBe($this->originalPayload);
+            expect($newPayload->metadata)->toBe($metadata);
+
+            // Original should be unchanged
+            expect($this->originalPayload->metadata)->not->toBe($metadata);
+        });
+
+        it('can chain multiple transformations', function () {
+            $finalPayload = $this->originalPayload
+                ->withPriority(QueuePriority::critical())
+                ->withDelay(Duration::fromSeconds(30))
+                ->withTimeout(Duration::fromMinutes(5))
+                ->withRetryStrategy(new ExponentialBackoffStrategy(maxAttempts: 3));
+
+            expect($finalPayload->priority->isCritical())->toBeTrue();
+            expect($finalPayload->delay->toSeconds())->toBe(30);
+            expect($finalPayload->timeout->toMinutes())->toBe(5);
+            expect($finalPayload->hasRetryStrategy())->toBeTrue();
+
+            // Original should be completely unchanged
+            expect($this->originalPayload->priority->isNormal())->toBeTrue();
+            expect($this->originalPayload->delay->toSeconds())->toBe(0);
+            expect($this->originalPayload->timeout)->toBeNull();
+            expect($this->originalPayload->retryStrategy)->toBeNull();
+        });
+    });
+
+    describe('Status Checking Methods', function () {
+        it('isReady() returns true for jobs with no delay', function () {
+            $payload = JobPayload::create($this->simpleJob, delay: Duration::zero());
+            expect($payload->isReady())->toBeTrue();
+
+            $immediate = JobPayload::immediate($this->simpleJob);
+            expect($immediate->isReady())->toBeTrue();
+        });
+
+        it('isReady() returns false for delayed jobs', function () {
+            $payload = JobPayload::delayed($this->simpleJob, Duration::fromSeconds(30));
+            expect($payload->isReady())->toBeFalse();
+        });
+
+        it('isDelayed() returns true for jobs with delay', function () {
+            $payload = JobPayload::delayed($this->simpleJob, Duration::fromMinutes(1));
+            expect($payload->isDelayed())->toBeTrue();
+        });
+
+        it('isDelayed() returns false for immediate jobs', function () {
+            $payload = JobPayload::immediate($this->simpleJob);
+            expect($payload->isDelayed())->toBeFalse();
+        });
+
+        it('hasRetryStrategy() reflects retry strategy presence', function () {
+            $withoutRetry = JobPayload::create($this->simpleJob);
+            expect($withoutRetry->hasRetryStrategy())->toBeFalse();
+
+            $withRetry = JobPayload::background($this->simpleJob);
+            expect($withRetry->hasRetryStrategy())->toBeTrue();
+        });
+
+        it('hasTimeout() reflects timeout presence', function () {
+            $withoutTimeout = JobPayload::create($this->simpleJob);
+            expect($withoutTimeout->hasTimeout())->toBeFalse();
+
+            $withTimeout = JobPayload::critical($this->simpleJob);
+            expect($withTimeout->hasTimeout())->toBeTrue();
+        });
+    });
+
+    describe('Time Calculations', function () {
+        it('getAvailableTime() returns current time for immediate jobs', function () {
+            $payload = JobPayload::immediate($this->simpleJob);
+            $available = $payload->getAvailableTime();
+            $now = time();
+
+            expect($available)->toBeGreaterThanOrEqual($now - 1);
+            expect($available)->toBeLessThanOrEqual($now + 1);
+        });
+
+        it('getAvailableTime() returns future time for delayed jobs', function () {
+            $delay = Duration::fromSeconds(300); // 5 minutes
+            $payload = JobPayload::delayed($this->simpleJob, $delay);
+
+            $available = $payload->getAvailableTime();
+            $expected = time() + 300;
+
+            expect($available)->toBeGreaterThanOrEqual($expected - 1);
+            expect($available)->toBeLessThanOrEqual($expected + 1);
+        });
+    });
+
+    describe('Serialization and Array Conversion', function () {
+        it('can serialize job objects', function () {
+            $payload = JobPayload::create($this->complexJob);
+            $serialized = $payload->serialize();
+
+            expect($serialized)->toBeString();
+            expect(strlen($serialized))->toBeGreaterThan(0);
+
+            // Should be able to unserialize
+            $unserialized = unserialize($serialized);
+            expect($unserialized)->toBeInstanceOf(get_class($this->complexJob));
+            expect($unserialized->id)->toBe('test-123');
+        });
+
+        it('getJobClass() returns correct class name', function () {
+            $payload = JobPayload::create($this->complexJob);
+            $className = $payload->getJobClass();
+
+            expect($className)->toBeString();
+            expect($className)->toContain('class@anonymous');
+        });
+
+        it('toArray() provides comprehensive job information', function () {
+            $retryStrategy = new ExponentialBackoffStrategy(maxAttempts: 5);
+            $payload = JobPayload::create(
+                $this->complexJob,
+                QueuePriority::high(),
+                Duration::fromSeconds(120),
+                Duration::fromMinutes(10),
+                $retryStrategy,
+                JobMetadata::create(['source' => 'api'])
+            );
+
+            $array = $payload->toArray();
+
+            expect($array)->toHaveKey('job_class');
+            expect($array)->toHaveKey('priority');
+            expect($array)->toHaveKey('priority_value');
+            expect($array)->toHaveKey('delay_seconds');
+            expect($array)->toHaveKey('timeout_seconds');
+            expect($array)->toHaveKey('has_retry_strategy');
+            expect($array)->toHaveKey('max_attempts');
+            expect($array)->toHaveKey('available_at');
+            expect($array)->toHaveKey('metadata');
+
+            expect($array['priority'])->toBe('high');
+            expect($array['priority_value'])->toBe(100);
+            expect($array['delay_seconds'])->toBe(120);
+            expect($array['timeout_seconds'])->toBe(600);
+            expect($array['has_retry_strategy'])->toBeTrue();
+            expect($array['max_attempts'])->toBe(5);
+            expect($array['available_at'])->toBeInt();
+            expect($array['metadata'])->toBeArray();
+        });
+
+        it('toArray() handles null values correctly', function () {
+            $payload = JobPayload::create($this->simpleJob);
+            $array = $payload->toArray();
+
+            expect($array['timeout_seconds'])->toBeNull();
+            expect($array['has_retry_strategy'])->toBeFalse();
+            expect($array['max_attempts'])->toBeNull();
+        });
+    });
+
+    describe('Edge Cases and Error Handling', function () {
+        it('maintains object reference integrity', function () {
+            $job = new stdClass();
+            $job->property = 'value';
+
+            $payload = JobPayload::create($job);
+
+            // Same object reference should be maintained
+            expect($payload->job)->toBe($job);
+            expect($payload->job->property)->toBe('value');
+
+            // Modifying original object should affect payload job (reference)
+            $job->property = 'modified';
+            expect($payload->job->property)->toBe('modified');
+        });
+
+        it('handles complex job objects with dependencies', function () {
+            $complexJob = new class {
+                public array $config;
+                public \DateTime $created;
+
+                public function __construct() {
+                    $this->config = ['timeout' => 30, 'retries' => 3];
+                    $this->created = new \DateTime();
+                }
+
+                public function getData(): array {
+                    return [
+                        'config' => $this->config,
+                        'created' => $this->created->format('Y-m-d H:i:s')
+                    ];
+                }
+            };
+
+            $payload = JobPayload::create($complexJob);
+            expect($payload->job->getData())->toBeArray();
+            expect($payload->job->config['timeout'])->toBe(30);
+        });
+
+        it('preserves metadata across transformations', function () {
+            $originalMetadata = JobMetadata::create(['initial' => 'data']);
+            $payload = JobPayload::create($this->simpleJob, metadata: $originalMetadata);
+
+            // Transform without changing metadata
+            $newPayload = $payload->withPriority(QueuePriority::critical());
+
+            expect($newPayload->metadata)->toBe($originalMetadata);
+        });
+    });
+});
+
+describe('JobPayload Integration Scenarios', function () {
+
+    beforeEach(function () {
+        $this->emailJob = new class {
+            public function __construct(
+                public string $to = 'test@example.com',
+                public string $subject = 'Test Email',
+                public string $body = 'Hello World'
+            ) {}
+
+            public function send(): bool {
+                // Simulate email sending
+                return true;
+            }
+        };
+
+        $this->reportJob = new class {
+            public function __construct(
+                public array $criteria = ['period' => 'monthly'],
+                public string $format = 'pdf'
+            ) {}
+
+            public function generate(): string {
+                return "Report generated with format: {$this->format}";
+            }
+        };
+    });
+
+    it('handles email job scenarios', function () {
+        // Immediate notification
+        $urgent = JobPayload::immediate($this->emailJob);
+        expect($urgent->priority->isHigh())->toBeTrue();
+        expect($urgent->isReady())->toBeTrue();
+
+        // Delayed newsletter
+        $newsletter = JobPayload::delayed($this->emailJob, Duration::fromHours(2));
+        expect($newsletter->isDelayed())->toBeTrue();
+
+        // Critical alert with timeout
+        $alert = JobPayload::critical($this->emailJob);
+        expect($alert->priority->isCritical())->toBeTrue();
+        expect($alert->hasTimeout())->toBeTrue();
+    });
+
+    it('handles report generation scenarios', function () {
+        // Background monthly report
+        $monthlyReport = JobPayload::background($this->reportJob);
+        expect($monthlyReport->priority->isLow())->toBeTrue();
+        expect($monthlyReport->hasRetryStrategy())->toBeTrue();
+
+        // Add custom metadata for tracking
+        $metadata = JobMetadata::create([
+            'user_id' => 123,
+            'report_type' => 'financial',
+            'department' => 'accounting'
+        ]);
+
+        $customReport = $monthlyReport->withMetadata($metadata);
+        expect($customReport->metadata->get('user_id'))->toBe(123);
+        expect($customReport->metadata->get('report_type'))->toBe('financial');
+    });
+
+    it('handles job priority escalation scenarios', function () {
+        // Start as normal priority
+        $job = JobPayload::create($this->emailJob, QueuePriority::normal());
+        expect($job->priority->isNormal())->toBeTrue();
+
+        // Escalate to high priority (customer complaint)
+        $escalated = $job->withPriority(QueuePriority::high());
+        expect($escalated->priority->isHigh())->toBeTrue();
+
+        // Further escalate to critical (system outage notification)
+        $critical = $escalated->withPriority(QueuePriority::critical());
+        expect($critical->priority->isCritical())->toBeTrue();
+
+        // Original should remain unchanged
+        expect($job->priority->isNormal())->toBeTrue();
+    });
+
+    it('demonstrates retry strategy configuration', function () {
+        // Simple retry for transient failures
+        $simpleRetry = new FixedDelayStrategy(Duration::fromSeconds(30), 3);
+        $payload = JobPayload::create($this->emailJob)->withRetryStrategy($simpleRetry);
+
+        expect($payload->retryStrategy->getMaxAttempts())->toBe(3);
+
+        // Exponential backoff for rate limiting
+        $exponentialRetry = new ExponentialBackoffStrategy(maxAttempts: 5);
+        $rateLimitedPayload = $payload->withRetryStrategy($exponentialRetry);
+
+        expect($rateLimitedPayload->retryStrategy->getMaxAttempts())->toBe(5);
+        expect($rateLimitedPayload->retryStrategy)->toBeInstanceOf(ExponentialBackoffStrategy::class);
+    });
+});

tests/Framework/Queue/ValueObjects/LockKeyTest.php

@@ -0,0 +1,155 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\ValueObjects\LockKey;
+use App\Framework\Queue\ValueObjects\JobId;
+use App\Framework\Queue\ValueObjects\WorkerId;
+use App\Framework\Queue\ValueObjects\QueueName;
+
+describe('LockKey Value Object', function () {
+    it('can create lock keys from strings', function () {
+        $key = 'test.lock.key';
+        $lockKey = LockKey::fromString($key);
+
+        expect($lockKey->toString())->toBe($key);
+        expect((string) $lockKey)->toBe($key);
+    });
+
+    it('validates lock key constraints', function () {
+        // Empty key
+        expect(fn() => LockKey::fromString(''))
+            ->toThrow(\InvalidArgumentException::class, 'Lock key cannot be empty');
+
+        // Too long
+        expect(fn() => LockKey::fromString(str_repeat('a', 256)))
+            ->toThrow(\InvalidArgumentException::class, 'Lock key cannot exceed 255 characters');
+
+        // Invalid characters
+        expect(fn() => LockKey::fromString('invalid@key!'))
+            ->toThrow(\InvalidArgumentException::class, 'Lock key contains invalid characters');
+
+        expect(fn() => LockKey::fromString('key with spaces'))
+            ->toThrow(\InvalidArgumentException::class, 'Lock key contains invalid characters');
+    });
+
+    it('allows valid characters only', function () {
+        $validKeys = [
+            'simple-key',
+            'key_with_underscores',
+            'key.with.dots',
+            'key123',
+            'UPPERCASE-key',
+            'mixed-Key_123.test'
+        ];
+
+        foreach ($validKeys as $key) {
+            $lockKey = LockKey::fromString($key);
+            expect($lockKey->toString())->toBe($key);
+        }
+    });
+
+    it('can create job-specific lock keys', function () {
+        $jobId = JobId::generate();
+        $lockKey = LockKey::forJob($jobId);
+
+        expect($lockKey->toString())->toStartWith('job.');
+        expect($lockKey->toString())->toContain($jobId->toString());
+    });
+
+    it('can create queue-specific lock keys', function () {
+        $queueName = QueueName::defaultQueue();
+        $lockKey = LockKey::forQueue($queueName);
+
+        expect($lockKey->toString())->toStartWith('queue.');
+        expect($lockKey->toString())->toContain($queueName->toString());
+    });
+
+    it('can create worker-specific lock keys', function () {
+        $workerId = WorkerId::generate();
+        $lockKey = LockKey::forWorker($workerId);
+
+        expect($lockKey->toString())->toStartWith('worker.');
+        expect($lockKey->toString())->toContain($workerId->toString());
+    });
+
+    it('can create resource-specific lock keys', function () {
+        $lockKey = LockKey::forResource('database', 'user-table');
+
+        expect($lockKey->toString())->toBe('database.user-table');
+    });
+
+    it('can create batch-specific lock keys', function () {
+        $batchId = 'batch-123-abc';
+        $lockKey = LockKey::forBatch($batchId);
+
+        expect($lockKey->toString())->toBe('batch.' . $batchId);
+    });
+
+    it('supports prefix modification', function () {
+        $lockKey = LockKey::fromString('original.key');
+        $prefixed = $lockKey->withPrefix('tenant-1');
+
+        expect($prefixed->toString())->toBe('tenant-1.original.key');
+        expect($lockKey->toString())->toBe('original.key'); // Original unchanged
+    });
+
+    it('supports suffix modification', function () {
+        $lockKey = LockKey::fromString('original.key');
+        $suffixed = $lockKey->withSuffix('processing');
+
+        expect($suffixed->toString())->toBe('original.key.processing');
+        expect($lockKey->toString())->toBe('original.key'); // Original unchanged
+    });
+
+    it('supports pattern matching', function () {
+        $lockKey = LockKey::fromString('job.email-queue.123');
+
+        expect($lockKey->matches('job.*'))->toBeTrue();
+        expect($lockKey->matches('job.email-queue.*'))->toBeTrue();
+        expect($lockKey->matches('worker.*'))->toBeFalse();
+        expect($lockKey->matches('*.123'))->toBeTrue();
+    });
+
+    it('supports equality comparison', function () {
+        $key = 'test.lock.key';
+        $lockKey1 = LockKey::fromString($key);
+        $lockKey2 = LockKey::fromString($key);
+        $lockKey3 = LockKey::fromString('different.key');
+
+        expect($lockKey1->equals($lockKey2))->toBeTrue();
+        expect($lockKey1->equals($lockKey3))->toBeFalse();
+    });
+
+    it('supports JSON serialization', function () {
+        $key = 'serializable.lock.key';
+        $lockKey = LockKey::fromString($key);
+
+        expect($lockKey->jsonSerialize())->toBe($key);
+        expect(json_encode($lockKey))->toBe('"' . $key . '"');
+    });
+
+    it('can chain modifications', function () {
+        $lockKey = LockKey::fromString('base.key')
+            ->withPrefix('tenant-1')
+            ->withSuffix('processing')
+            ->withSuffix('active');
+
+        expect($lockKey->toString())->toBe('tenant-1.base.key.processing.active');
+    });
+
+    it('handles complex resource hierarchies', function () {
+        // Simulate nested resource locks
+        $databaseLock = LockKey::forResource('database', 'users');
+        $tableLock = $databaseLock->withSuffix('table-lock');
+        $rowLock = $tableLock->withSuffix('row-123');
+
+        expect($databaseLock->toString())->toBe('database.users');
+        expect($tableLock->toString())->toBe('database.users.table-lock');
+        expect($rowLock->toString())->toBe('database.users.table-lock.row-123');
+
+        // Pattern matching for hierarchical locks
+        expect($rowLock->matches('database.users.*'))->toBeTrue();
+        expect($rowLock->matches('*.row-123'))->toBeTrue();
+    });
+});

tests/Framework/Queue/ValueObjects/WorkerIdTest.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\ValueObjects\WorkerId;
+
+describe('WorkerId Value Object', function () {
+    it('can generate unique worker IDs', function () {
+        $workerId1 = WorkerId::generate();
+        $workerId2 = WorkerId::generate();
+
+        expect($workerId1->toString())->not->toBe($workerId2->toString());
+        expect($workerId1->equals($workerId2))->toBeFalse();
+    });
+
+    it('can create deterministic IDs for host and process combinations', function () {
+        $workerId1 = WorkerId::forHost('app-server-1', 1001);
+        $workerId2 = WorkerId::forHost('app-server-1', 1001);
+        $workerId3 = WorkerId::forHost('app-server-2', 1001);
+
+        // Same host/PID should create different IDs (due to ULID component)
+        expect($workerId1->toString())->not->toBe($workerId2->toString());
+
+        // Different hosts should create different IDs
+        expect($workerId1->toString())->not->toBe($workerId3->toString());
+    });
+
+    it('can create worker ID from existing string', function () {
+        $originalId = 'test-worker-id-123';
+        $workerId = WorkerId::fromString($originalId);
+
+        expect($workerId->toString())->toBe($originalId);
+        expect($workerId->getValue())->toBe($originalId);
+    });
+
+    it('validates worker ID is not empty', function () {
+        expect(fn() => WorkerId::fromString(''))
+            ->toThrow(\InvalidArgumentException::class, 'WorkerId cannot be empty');
+    });
+
+    it('supports equality comparison', function () {
+        $id = 'same-worker-id';
+        $workerId1 = WorkerId::fromString($id);
+        $workerId2 = WorkerId::fromString($id);
+        $workerId3 = WorkerId::fromString('different-id');
+
+        expect($workerId1->equals($workerId2))->toBeTrue();
+        expect($workerId1->equals($workerId3))->toBeFalse();
+    });
+
+    it('provides string conversion methods', function () {
+        $id = 'test-worker-id';
+        $workerId = WorkerId::fromString($id);
+
+        expect($workerId->toString())->toBe($id);
+        expect($workerId->getValue())->toBe($id);
+        expect((string) $workerId)->toBe($id);
+    });
+
+    it('supports JSON serialization', function () {
+        $id = 'json-serializable-worker-id';
+        $workerId = WorkerId::fromString($id);
+
+        expect($workerId->jsonSerialize())->toBe($id);
+        expect(json_encode($workerId))->toBe('"' . $id . '"');
+    });
+});

tests/Framework/Queue/WorkerManagementTest.php

@@ -0,0 +1,893 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Queue\Entities\Worker;
+use App\Framework\Queue\ValueObjects\WorkerId;
+use App\Framework\Queue\ValueObjects\QueueName;
+use App\Framework\Queue\Services\WorkerRegistry;
+use App\Framework\Queue\Services\WorkerHealthCheckService;
+use App\Framework\Core\ValueObjects\Percentage;
+use App\Framework\Core\ValueObjects\Byte;
+use App\Framework\Core\ValueObjects\Duration;
+
+describe('Worker Management System', function () {
+    beforeEach(function () {
+        // Mock database connection for testing
+        $this->mockConnection = new class {
+            private array $data = [];
+            private int $lastInsertId = 0;
+            private int $rowCount = 0;
+
+            public function prepare(string $sql): object
+            {
+                return new class($sql, $this) {
+                    public function __construct(
+                        private string $sql,
+                        private object $connection
+                    ) {}
+
+                    public function execute(array $params = []): bool
+                    {
+                        // Simulate different SQL operations
+                        if (str_contains($this->sql, 'INSERT INTO queue_workers')) {
+                            $this->connection->rowCount = 1;
+                            $this->connection->data['workers'][$params['id']] = $params;
+                        } elseif (str_contains($this->sql, 'UPDATE queue_workers')) {
+                            if (str_contains($this->sql, 'is_active = 0')) {
+                                // Deregister operation
+                                if (isset($this->connection->data['workers'][$params['id']])) {
+                                    $this->connection->data['workers'][$params['id']]['is_active'] = 0;
+                                    $this->connection->rowCount = 1;
+                                }
+                            } else {
+                                // Heartbeat update
+                                if (isset($this->connection->data['workers'][$params['id']])) {
+                                    $worker = &$this->connection->data['workers'][$params['id']];
+                                    $worker['cpu_usage'] = $params['cpu_usage'];
+                                    $worker['memory_usage_bytes'] = $params['memory_usage_bytes'];
+                                    $worker['current_jobs'] = $params['current_jobs'];
+                                    $worker['last_heartbeat'] = date('Y-m-d H:i:s');
+                                    $this->connection->rowCount = 1;
+                                }
+                            }
+                        } elseif (str_contains($this->sql, 'INSERT INTO worker_health_checks')) {
+                            $this->connection->data['health_checks'][] = $params;
+                            $this->connection->rowCount = 1;
+                        }
+                        return true;
+                    }
+
+                    public function fetch(): array|false
+                    {
+                        if (str_contains($this->sql, 'SELECT * FROM queue_workers WHERE id = :id')) {
+                            $id = func_get_args()[0]['id'] ?? null;
+                            return $this->connection->data['workers'][$id] ?? false;
+                        }
+
+                        if (str_contains($this->sql, 'SELECT * FROM queue_workers') && str_contains($this->sql, 'is_active = 1')) {
+                            // Return first active worker for testing
+                            foreach ($this->connection->data['workers'] ?? [] as $worker) {
+                                if ($worker['is_active']) {
+                                    return $worker;
+                                }
+                            }
+                            return false;
+                        }
+
+                        // Statistics query
+                        if (str_contains($this->sql, 'COUNT(*) as total_workers')) {
+                            return [
+                                'total_workers' => count($this->connection->data['workers'] ?? []),
+                                'active_workers' => count(array_filter($this->connection->data['workers'] ?? [], fn($w) => $w['is_active'])),
+                                'healthy_workers' => count(array_filter($this->connection->data['workers'] ?? [], fn($w) => $w['is_active'])),
+                                'total_capacity' => 100,
+                                'current_load' => 50,
+                                'avg_cpu_usage' => 25.5,
+                                'avg_memory_usage' => 1024 * 1024 * 512, // 512MB
+                                'unique_hosts' => 2
+                            ];
+                        }
+
+                        return false;
+                    }
+
+                    public function fetchAll(): array
+                    {
+                        if (str_contains($this->sql, 'worker_health_checks') && str_contains($this->sql, 'GROUP BY')) {
+                            return [
+                                [
+                                    'check_date' => '2024-01-01',
+                                    'check_hour' => '14',
+                                    'avg_score' => 85.5,
+                                    'total_checks' => 10,
+                                    'healthy_count' => 8,
+                                    'warning_count' => 2,
+                                    'critical_count' => 0
+                                ]
+                            ];
+                        }
+                        return [];
+                    }
+
+                    public function rowCount(): int
+                    {
+                        return $this->connection->rowCount;
+                    }
+                };
+            }
+
+            public function setWorkerData(array $workers): void
+            {
+                $this->data['workers'] = $workers;
+            }
+        };
+
+        // Mock logger for testing
+        $this->mockLogger = new class {
+            public array $logs = [];
+
+            public function info(string $message, array $context = []): void
+            {
+                $this->logs[] = ['level' => 'info', 'message' => $message, 'context' => $context];
+            }
+
+            public function debug(string $message, array $context = []): void
+            {
+                $this->logs[] = ['level' => 'debug', 'message' => $message, 'context' => $context];
+            }
+
+            public function error(string $message, array $context = []): void
+            {
+                $this->logs[] = ['level' => 'error', 'message' => $message, 'context' => $context];
+            }
+
+            public function warning(string $message, array $context = []): void
+            {
+                $this->logs[] = ['level' => 'warning', 'message' => $message, 'context' => $context];
+            }
+        };
+
+        $this->workerRegistry = new WorkerRegistry($this->mockConnection, $this->mockLogger);
+        $this->healthCheckService = new WorkerHealthCheckService($this->workerRegistry, $this->mockConnection, $this->mockLogger);
+    });
+
+    describe('WorkerId Value Object', function () {
+        it('can generate unique worker IDs', function () {
+            $id1 = WorkerId::generate();
+            $id2 = WorkerId::generate();
+
+            expect($id1->toString())->not()->toBe($id2->toString());
+            expect($id1->getValue())->not()->toBeEmpty();
+        });
+
+        it('can create deterministic IDs for host and process', function () {
+            $id1 = WorkerId::forHost('localhost', 1234);
+            $id2 = WorkerId::forHost('localhost', 1234);
+
+            expect($id1->toString())->toBe($id2->toString());
+            expect($id1->getValue())->toHaveLength(16);
+        });
+
+        it('can create from string and validate', function () {
+            $original = 'worker_123_test';
+            $id = WorkerId::fromString($original);
+
+            expect($id->toString())->toBe($original);
+            expect($id->getValue())->toBe($original);
+            expect((string) $id)->toBe($original);
+        });
+
+        it('throws exception for empty worker ID', function () {
+            expect(fn() => WorkerId::fromString(''))
+                ->toThrow(\InvalidArgumentException::class, 'WorkerId cannot be empty');
+        });
+
+        it('can compare worker IDs for equality', function () {
+            $id1 = WorkerId::fromString('worker_123');
+            $id2 = WorkerId::fromString('worker_123');
+            $id3 = WorkerId::fromString('worker_456');
+
+            expect($id1->equals($id2))->toBeTrue();
+            expect($id1->equals($id3))->toBeFalse();
+        });
+
+        it('supports JSON serialization', function () {
+            $id = WorkerId::fromString('worker_test_123');
+            $json = json_encode($id);
+
+            expect($json)->toBe('"worker_test_123"');
+        });
+    });
+
+    describe('Worker Entity', function () {
+        it('can register a new worker with valid parameters', function () {
+            $queues = [QueueName::default(), QueueName::high()];
+            $capabilities = ['pdf_processing', 'email_sending'];
+
+            $worker = Worker::register(
+                hostname: 'worker-01',
+                processId: 1234,
+                queues: $queues,
+                maxJobs: 5,
+                capabilities: $capabilities
+            );
+
+            expect($worker->hostname)->toBe('worker-01');
+            expect($worker->processId)->toBe(1234);
+            expect($worker->queues)->toBe($queues);
+            expect($worker->maxJobs)->toBe(5);
+            expect($worker->isActive)->toBeTrue();
+            expect($worker->capabilities)->toBe($capabilities);
+            expect($worker->currentJobs)->toBe(0);
+            expect($worker->version)->toBe('1.0.0');
+            expect($worker->registeredAt)->toBeInstanceOf(\DateTimeImmutable::class);
+            expect($worker->lastHeartbeat)->toBeInstanceOf(\DateTimeImmutable::class);
+        });
+
+        it('throws exception when no queues provided', function () {
+            expect(fn() => new Worker(
+                id: WorkerId::generate(),
+                hostname: 'test',
+                processId: 1234,
+                queues: [], // Empty queues
+                maxJobs: 5,
+                registeredAt: new \DateTimeImmutable()
+            ))->toThrow(\InvalidArgumentException::class, 'Worker must handle at least one queue');
+        });
+
+        it('validates job constraints during construction', function () {
+            $baseWorker = fn($maxJobs, $currentJobs) => new Worker(
+                id: WorkerId::generate(),
+                hostname: 'test',
+                processId: 1234,
+                queues: [QueueName::default()],
+                maxJobs: $maxJobs,
+                registeredAt: new \DateTimeImmutable(),
+                currentJobs: $currentJobs
+            );
+
+            // Invalid max jobs
+            expect(fn() => $baseWorker(0, 0))
+                ->toThrow(\InvalidArgumentException::class, 'Max jobs must be greater than 0');
+            expect(fn() => $baseWorker(-1, 0))
+                ->toThrow(\InvalidArgumentException::class, 'Max jobs must be greater than 0');
+
+            // Invalid current jobs
+            expect(fn() => $baseWorker(5, -1))
+                ->toThrow(\InvalidArgumentException::class, 'Current jobs cannot be negative');
+            expect(fn() => $baseWorker(5, 10))
+                ->toThrow(\InvalidArgumentException::class, 'Current jobs cannot exceed max jobs');
+        });
+
+        it('can update heartbeat with new metrics', function () {
+            $worker = Worker::register('worker-01', 1234, [QueueName::default()]);
+            $newCpuUsage = new Percentage(75.5);
+            $newMemoryUsage = Byte::fromMegabytes(512);
+            $newCurrentJobs = 3;
+
+            $updatedWorker = $worker->updateHeartbeat($newCpuUsage, $newMemoryUsage, $newCurrentJobs);
+
+            expect($updatedWorker->cpuUsage)->toBe($newCpuUsage);
+            expect($updatedWorker->memoryUsage)->toBe($newMemoryUsage);
+            expect($updatedWorker->currentJobs)->toBe($newCurrentJobs);
+            expect($updatedWorker->isActive)->toBeTrue();
+            expect($updatedWorker->lastHeartbeat->getTimestamp())->toBeGreaterThan($worker->lastHeartbeat->getTimestamp());
+        });
+
+        it('can mark worker as inactive', function () {
+            $worker = Worker::register('worker-01', 1234, [QueueName::default()]);
+            $inactiveWorker = $worker->markInactive();
+
+            expect($inactiveWorker->isActive)->toBeFalse();
+            expect($inactiveWorker->id)->toBe($worker->id);
+            expect($inactiveWorker->hostname)->toBe($worker->hostname);
+        });
+
+        it('correctly determines worker availability for jobs', function () {
+            $queues = [QueueName::default()];
+
+            // Healthy active worker with capacity
+            $healthyWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'healthy-worker',
+                processId: 1234,
+                queues: $queues,
+                maxJobs: 5,
+                registeredAt: new \DateTimeImmutable(),
+                lastHeartbeat: new \DateTimeImmutable(),
+                isActive: true,
+                cpuUsage: new Percentage(50),
+                memoryUsage: Byte::fromMegabytes(500),
+                currentJobs: 2
+            );
+
+            expect($healthyWorker->isAvailableForJobs())->toBeTrue();
+
+            // Inactive worker
+            $inactiveWorker = $healthyWorker->markInactive();
+            expect($inactiveWorker->isAvailableForJobs())->toBeFalse();
+
+            // Worker at max capacity
+            $maxCapacityWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'maxed-worker',
+                processId: 1234,
+                queues: $queues,
+                maxJobs: 5,
+                registeredAt: new \DateTimeImmutable(),
+                lastHeartbeat: new \DateTimeImmutable(),
+                isActive: true,
+                currentJobs: 5 // At max capacity
+            );
+
+            expect($maxCapacityWorker->isAvailableForJobs())->toBeFalse();
+
+            // Unhealthy worker (high CPU)
+            $unhealthyWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'unhealthy-worker',
+                processId: 1234,
+                queues: $queues,
+                maxJobs: 5,
+                registeredAt: new \DateTimeImmutable(),
+                lastHeartbeat: new \DateTimeImmutable(),
+                isActive: true,
+                cpuUsage: new Percentage(95), // Too high
+                currentJobs: 2
+            );
+
+            expect($unhealthyWorker->isAvailableForJobs())->toBeFalse();
+        });
+
+        it('can check queue handling capability', function () {
+            $defaultQueue = QueueName::default();
+            $highQueue = QueueName::high();
+            $lowQueue = QueueName::low();
+
+            $worker = Worker::register('worker-01', 1234, [$defaultQueue, $highQueue]);
+
+            expect($worker->handlesQueue($defaultQueue))->toBeTrue();
+            expect($worker->handlesQueue($highQueue))->toBeTrue();
+            expect($worker->handlesQueue($lowQueue))->toBeFalse();
+        });
+
+        it('determines health status based on multiple factors', function () {
+            $queues = [QueueName::default()];
+
+            // Healthy worker
+            $healthyWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'healthy',
+                processId: 1234,
+                queues: $queues,
+                maxJobs: 5,
+                registeredAt: new \DateTimeImmutable(),
+                lastHeartbeat: new \DateTimeImmutable(), // Recent heartbeat
+                isActive: true,
+                cpuUsage: new Percentage(50),
+                memoryUsage: Byte::fromMegabytes(500) // 500MB < 2GB limit
+            );
+
+            expect($healthyWorker->isHealthy())->toBeTrue();
+
+            // Worker with old heartbeat
+            $staleWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'stale',
+                processId: 1234,
+                queues: $queues,
+                maxJobs: 5,
+                registeredAt: new \DateTimeImmutable(),
+                lastHeartbeat: new \DateTimeImmutable('-2 minutes'), // Too old
+                isActive: true
+            );
+
+            expect($staleWorker->isHealthy())->toBeFalse();
+
+            // Worker with high CPU
+            $highCpuWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'high-cpu',
+                processId: 1234,
+                queues: $queues,
+                maxJobs: 5,
+                registeredAt: new \DateTimeImmutable(),
+                lastHeartbeat: new \DateTimeImmutable(),
+                isActive: true,
+                cpuUsage: new Percentage(95) // Too high
+            );
+
+            expect($highCpuWorker->isHealthy())->toBeFalse();
+
+            // Worker with high memory
+            $highMemoryWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'high-memory',
+                processId: 1234,
+                queues: $queues,
+                maxJobs: 5,
+                registeredAt: new \DateTimeImmutable(),
+                lastHeartbeat: new \DateTimeImmutable(),
+                isActive: true,
+                memoryUsage: Byte::fromGigabytes(3) // > 2GB limit
+            );
+
+            expect($highMemoryWorker->isHealthy())->toBeFalse();
+        });
+
+        it('calculates load percentage correctly', function () {
+            $queues = [QueueName::default()];
+
+            // Job load higher than CPU load
+            $jobLoadWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'job-load',
+                processId: 1234,
+                queues: $queues,
+                maxJobs: 10,
+                registeredAt: new \DateTimeImmutable(),
+                currentJobs: 8, // 80% job load
+                cpuUsage: new Percentage(30) // 30% CPU load
+            );
+
+            expect($jobLoadWorker->getLoadPercentage()->getValue())->toBe(80.0);
+
+            // CPU load higher than job load
+            $cpuLoadWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'cpu-load',
+                processId: 1234,
+                queues: $queues,
+                maxJobs: 10,
+                registeredAt: new \DateTimeImmutable(),
+                currentJobs: 3, // 30% job load
+                cpuUsage: new Percentage(70) // 70% CPU load
+            );
+
+            expect($cpuLoadWorker->getLoadPercentage()->getValue())->toBe(70.0);
+
+            // Zero max jobs edge case
+            $zeroMaxWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'zero-max',
+                processId: 1234,
+                queues: $queues,
+                maxJobs: 1,
+                registeredAt: new \DateTimeImmutable(),
+                currentJobs: 1 // 100% job load
+            );
+
+            expect($zeroMaxWorker->getLoadPercentage()->getValue())->toBe(100.0);
+        });
+
+        it('can check capabilities', function () {
+            $worker = Worker::register('worker-01', 1234, [QueueName::default()], 5, ['pdf', 'email', 'resize']);
+
+            expect($worker->hasCapability('pdf'))->toBeTrue();
+            expect($worker->hasCapability('email'))->toBeTrue();
+            expect($worker->hasCapability('video'))->toBeFalse();
+        });
+
+        it('can convert to monitoring array format', function () {
+            $worker = Worker::register('worker-01', 1234, [QueueName::default()], 5, ['pdf']);
+            $monitoring = $worker->toMonitoringArray();
+
+            expect($monitoring)->toHaveKey('id');
+            expect($monitoring)->toHaveKey('hostname');
+            expect($monitoring)->toHaveKey('process_id');
+            expect($monitoring)->toHaveKey('queues');
+            expect($monitoring)->toHaveKey('is_healthy');
+            expect($monitoring)->toHaveKey('is_available');
+            expect($monitoring)->toHaveKey('load_percentage');
+            expect($monitoring)->toHaveKey('capabilities');
+
+            expect($monitoring['hostname'])->toBe('worker-01');
+            expect($monitoring['process_id'])->toBe(1234);
+            expect($monitoring['capabilities'])->toBe(['pdf']);
+        });
+
+        it('can serialize to and from array', function () {
+            $queues = [QueueName::default(), QueueName::high()];
+            $capabilities = ['pdf', 'email'];
+
+            $worker = Worker::register('worker-01', 1234, $queues, 5, $capabilities);
+            $array = $worker->toArray();
+
+            expect($array)->toHaveKey('id');
+            expect($array)->toHaveKey('hostname');
+            expect($array)->toHaveKey('queues');
+            expect($array)->toHaveKey('capabilities');
+
+            // Test that queues and capabilities are JSON encoded
+            expect($array['queues'])->toBeString();
+            expect($array['capabilities'])->toBeString();
+
+            // Note: fromArray() is simplified in the implementation
+            // In real testing, you'd want to test full serialization/deserialization
+            $restoredWorker = Worker::fromArray($array);
+            expect($restoredWorker->hostname)->toBe('worker-01');
+            expect($restoredWorker->processId)->toBe(1234);
+        });
+    });
+
+    describe('WorkerRegistry Service', function () {
+        it('can register a worker successfully', function () {
+            $worker = Worker::register('test-host', 1234, [QueueName::default()]);
+
+            $this->workerRegistry->register($worker);
+
+            expect($this->mockLogger->logs)->toContain([
+                'level' => 'info',
+                'message' => 'Registering worker',
+                'context' => [
+                    'worker_id' => $worker->id->toString(),
+                    'hostname' => 'test-host',
+                    'process_id' => 1234,
+                    'queues' => [QueueName::default()],
+                    'max_jobs' => 10
+                ]
+            ]);
+
+            expect($this->mockLogger->logs)->toContain([
+                'level' => 'debug',
+                'message' => 'Worker registered successfully',
+                'context' => ['worker_id' => $worker->id->toString()]
+            ]);
+        });
+
+        it('can deregister a worker', function () {
+            $workerId = WorkerId::generate();
+
+            // Setup worker data in mock
+            $this->mockConnection->setWorkerData([
+                $workerId->toString() => [
+                    'id' => $workerId->toString(),
+                    'is_active' => 1
+                ]
+            ]);
+
+            $this->workerRegistry->deregister($workerId);
+
+            expect($this->mockLogger->logs)->toContain([
+                'level' => 'info',
+                'message' => 'Deregistering worker',
+                'context' => ['worker_id' => $workerId->toString()]
+            ]);
+        });
+
+        it('can update worker heartbeat', function () {
+            $workerId = WorkerId::generate();
+            $cpuUsage = new Percentage(45.5);
+            $memoryUsage = Byte::fromMegabytes(256);
+            $currentJobs = 3;
+
+            // Setup worker data in mock
+            $this->mockConnection->setWorkerData([
+                $workerId->toString() => [
+                    'id' => $workerId->toString(),
+                    'is_active' => 1
+                ]
+            ]);
+
+            $this->workerRegistry->updateHeartbeat($workerId, $cpuUsage, $memoryUsage, $currentJobs);
+
+            // Should not log warnings when worker found and updated
+            $warningLogs = array_filter($this->mockLogger->logs, fn($log) => $log['level'] === 'warning');
+            expect($warningLogs)->toBeEmpty();
+        });
+
+        it('logs warning when heartbeat update fails for non-existent worker', function () {
+            $workerId = WorkerId::generate();
+            $cpuUsage = new Percentage(50);
+            $memoryUsage = Byte::fromMegabytes(512);
+
+            // No worker data setup - worker doesn't exist
+
+            $this->workerRegistry->updateHeartbeat($workerId, $cpuUsage, $memoryUsage, 2);
+
+            $warningLogs = array_filter($this->mockLogger->logs, fn($log) => $log['level'] === 'warning');
+            expect($warningLogs)->not()->toBeEmpty();
+        });
+
+        it('can find worker by ID', function () {
+            $workerId = WorkerId::generate();
+            $workerData = [
+                'id' => $workerId->toString(),
+                'hostname' => 'test-worker',
+                'process_id' => 1234,
+                'queues' => json_encode(['default']),
+                'max_jobs' => 5,
+                'current_jobs' => 2,
+                'is_active' => 1,
+                'cpu_usage' => 50,
+                'memory_usage_bytes' => 512 * 1024 * 1024,
+                'registered_at' => '2024-01-01 12:00:00',
+                'last_heartbeat' => '2024-01-01 12:05:00',
+                'capabilities' => json_encode(['pdf']),
+                'version' => '1.0.0'
+            ];
+
+            $this->mockConnection->setWorkerData([$workerId->toString() => $workerData]);
+
+            $foundWorker = $this->workerRegistry->findById($workerId);
+
+            expect($foundWorker)->toBeInstanceOf(Worker::class);
+            expect($foundWorker->hostname)->toBe('test-worker');
+            expect($foundWorker->processId)->toBe(1234);
+        });
+
+        it('returns null when worker not found by ID', function () {
+            $workerId = WorkerId::generate();
+
+            $foundWorker = $this->workerRegistry->findById($workerId);
+
+            expect($foundWorker)->toBeNull();
+        });
+
+        it('can get worker statistics', function () {
+            $stats = $this->workerRegistry->getWorkerStatistics();
+
+            expect($stats)->toHaveKey('total_workers');
+            expect($stats)->toHaveKey('active_workers');
+            expect($stats)->toHaveKey('healthy_workers');
+            expect($stats)->toHaveKey('total_capacity');
+            expect($stats)->toHaveKey('current_load');
+            expect($stats)->toHaveKey('capacity_utilization');
+            expect($stats)->toHaveKey('avg_cpu_usage');
+            expect($stats)->toHaveKey('avg_memory_usage_mb');
+            expect($stats)->toHaveKey('unique_hosts');
+            expect($stats)->toHaveKey('queue_distribution');
+
+            expect($stats['capacity_utilization'])->toBe(50.0);
+            expect($stats['avg_memory_usage_mb'])->toBe(512.0);
+        });
+
+        it('can cleanup inactive workers', function () {
+            $cleanedCount = $this->workerRegistry->cleanupInactiveWorkers(5);
+
+            expect($cleanedCount)->toBeInt();
+
+            expect($this->mockLogger->logs)->toContain([
+                'level' => 'info',
+                'message' => 'Starting cleanup of inactive workers',
+                'context' => ['inactive_minutes' => 5]
+            ]);
+        });
+    });
+
+    describe('WorkerHealthCheckService', function () {
+        it('can perform health check on individual worker', function () {
+            $worker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'test-worker',
+                processId: 1234,
+                queues: [QueueName::default()],
+                maxJobs: 10,
+                registeredAt: new \DateTimeImmutable(),
+                lastHeartbeat: new \DateTimeImmutable(),
+                isActive: true,
+                cpuUsage: new Percentage(45),
+                memoryUsage: Byte::fromMegabytes(800),
+                currentJobs: 5
+            );
+
+            $health = $this->healthCheckService->checkWorkerHealth($worker);
+
+            expect($health)->toHaveKey('worker_id');
+            expect($health)->toHaveKey('hostname');
+            expect($health)->toHaveKey('status');
+            expect($health)->toHaveKey('score');
+            expect($health)->toHaveKey('metrics');
+            expect($health)->toHaveKey('issues');
+            expect($health)->toHaveKey('warnings');
+            expect($health)->toHaveKey('checked_at');
+
+            expect($health['worker_id'])->toBe($worker->id->toString());
+            expect($health['hostname'])->toBe('test-worker');
+            expect($health['status'])->toBe('healthy');
+            expect($health['score'])->toBeGreaterThanOrEqual(80);
+            expect($health['issues'])->toBeEmpty();
+        });
+
+        it('detects critical health issues', function () {
+            $criticalWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'critical-worker',
+                processId: 1234,
+                queues: [QueueName::default()],
+                maxJobs: 5,
+                registeredAt: new \DateTimeImmutable(),
+                lastHeartbeat: new \DateTimeImmutable('-5 minutes'), // Very old heartbeat
+                isActive: true,
+                cpuUsage: new Percentage(95), // Critical CPU
+                memoryUsage: Byte::fromGigabytes(3), // Critical memory
+                currentJobs: 5 // Overloaded
+            );
+
+            $health = $this->healthCheckService->checkWorkerHealth($criticalWorker);
+
+            expect($health['status'])->toBe('critical');
+            expect($health['score'])->toBeLessThan(50);
+            expect($health['issues'])->not()->toBeEmpty();
+            expect($health['issues'])->toContain('No heartbeat for 300 seconds');
+            expect($health['issues'])->toContain('Critical CPU usage: 95%');
+            expect($health['issues'])->toContain('Critical memory usage: 3.000GB');
+            expect($health['issues'])->toContain('Worker overloaded: 95%');
+        });
+
+        it('detects warning conditions', function () {
+            $warningWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'warning-worker',
+                processId: 1234,
+                queues: [QueueName::default()],
+                maxJobs: 10,
+                registeredAt: new \DateTimeImmutable(),
+                lastHeartbeat: new \DateTimeImmutable('-70 seconds'), // Slightly delayed
+                isActive: true,
+                cpuUsage: new Percentage(80), // Warning level CPU
+                memoryUsage: Byte::fromGigabytes(1.8), // Warning level memory
+                currentJobs: 9 // High load
+            );
+
+            $health = $this->healthCheckService->checkWorkerHealth($warningWorker);
+
+            expect($health['status'])->toBe('warning');
+            expect($health['score'])->toBeGreaterThan(30);
+            expect($health['score'])->toBeLessThan(80);
+            expect($health['warnings'])->not()->toBeEmpty();
+            expect($health['warnings'])->toContain('Heartbeat delayed (70s)');
+            expect($health['warnings'])->toContain('High CPU usage: 80%');
+            expect($health['warnings'])->toContain('High memory usage: 1.800GB');
+            expect($health['warnings'])->toContain('High worker load: 90%');
+        });
+
+        it('handles inactive workers correctly', function () {
+            $inactiveWorker = new Worker(
+                id: WorkerId::generate(),
+                hostname: 'inactive-worker',
+                processId: 1234,
+                queues: [QueueName::default()],
+                maxJobs: 5,
+                registeredAt: new \DateTimeImmutable(),
+                isActive: false // Inactive
+            );
+
+            $health = $this->healthCheckService->checkWorkerHealth($inactiveWorker);
+
+            expect($health['status'])->toBe('critical');
+            expect($health['score'])->toBe(0);
+            expect($health['issues'])->toContain('Worker marked as inactive');
+        });
+
+        it('can generate system health report', function () {
+            // Setup some test workers in the mock
+            $this->mockConnection->setWorkerData([
+                'worker1' => [
+                    'id' => 'worker1',
+                    'hostname' => 'test1',
+                    'process_id' => 1234,
+                    'queues' => json_encode(['default']),
+                    'max_jobs' => 5,
+                    'current_jobs' => 2,
+                    'is_active' => 1,
+                    'cpu_usage' => 50,
+                    'memory_usage_bytes' => 512 * 1024 * 1024,
+                    'registered_at' => '2024-01-01 12:00:00',
+                    'last_heartbeat' => date('Y-m-d H:i:s'),
+                    'capabilities' => json_encode([]),
+                    'version' => '1.0.0'
+                ]
+            ]);
+
+            $report = $this->healthCheckService->generateSystemHealthReport();
+
+            expect($report)->toHaveKey('current_health');
+            expect($report)->toHaveKey('trends_24h');
+            expect($report)->toHaveKey('top_issues_24h');
+            expect($report)->toHaveKey('generated_at');
+
+            expect($report['current_health'])->toHaveKey('workers');
+            expect($report['current_health'])->toHaveKey('overall');
+        });
+
+        it('can cleanup old health check records', function () {
+            $deletedCount = $this->healthCheckService->cleanupHealthChecks(Duration::fromDays(7));
+
+            expect($deletedCount)->toBeInt();
+
+            expect($this->mockLogger->logs)->toContain([
+                'level' => 'info',
+                'message' => 'Health check cleanup completed',
+                'context' => [
+                    'deleted_records' => $deletedCount,
+                    'retention_days' => 7.0
+                ]
+            ]);
+        });
+    });
+
+    describe('Integration Testing', function () {
+        it('can perform full worker lifecycle management', function () {
+            // 1. Register worker
+            $worker = Worker::register('integration-host', 9999, [QueueName::default(), QueueName::high()], 8, ['pdf']);
+            $this->workerRegistry->register($worker);
+
+            // 2. Update heartbeat
+            $this->workerRegistry->updateHeartbeat(
+                $worker->id,
+                new Percentage(65),
+                Byte::fromMegabytes(1024),
+                3
+            );
+
+            // 3. Perform health check
+            $health = $this->healthCheckService->checkWorkerHealth($worker);
+            expect($health['status'])->toBeIn(['healthy', 'warning']);
+
+            // 4. Find worker
+            $foundWorker = $this->workerRegistry->findById($worker->id);
+            expect($foundWorker)->not()->toBeNull();
+
+            // 5. Get statistics
+            $stats = $this->workerRegistry->getWorkerStatistics();
+            expect($stats['total_workers'])->toBeGreaterThanOrEqual(1);
+
+            // 6. Deregister worker
+            $this->workerRegistry->deregister($worker->id);
+
+            // Verify all operations logged appropriately
+            $logCount = count($this->mockLogger->logs);
+            expect($logCount)->toBeGreaterThan(0);
+        });
+
+        it('handles edge cases and error conditions gracefully', function () {
+            // Test with non-existent worker ID
+            $nonExistentId = WorkerId::generate();
+            $foundWorker = $this->workerRegistry->findById($nonExistentId);
+            expect($foundWorker)->toBeNull();
+
+            // Test heartbeat update for non-existent worker
+            $this->workerRegistry->updateHeartbeat(
+                $nonExistentId,
+                new Percentage(50),
+                Byte::fromMegabytes(512),
+                1
+            );
+
+            // Should log warning
+            $warningLogs = array_filter($this->mockLogger->logs, fn($log) => $log['level'] === 'warning');
+            expect($warningLogs)->not()->toBeEmpty();
+        });
+
+        it('maintains data consistency across operations', function () {
+            $worker = Worker::register('consistency-test', 7777, [QueueName::default()]);
+
+            // Test immutability - operations should return new instances
+            $originalId = $worker->id;
+            $originalHostname = $worker->hostname;
+
+            $updatedWorker = $worker->updateHeartbeat(
+                new Percentage(30),
+                Byte::fromMegabytes(256),
+                1
+            );
+
+            // Original worker unchanged
+            expect($worker->id)->toBe($originalId);
+            expect($worker->hostname)->toBe($originalHostname);
+            expect($worker->currentJobs)->toBe(0);
+
+            // Updated worker has new values
+            expect($updatedWorker->id)->toBe($originalId); // Same ID
+            expect($updatedWorker->hostname)->toBe($originalHostname); // Same hostname
+            expect($updatedWorker->currentJobs)->toBe(1); // Updated jobs
+            expect($updatedWorker->cpuUsage->getValue())->toBe(30.0);
+
+            $inactiveWorker = $updatedWorker->markInactive();
+            expect($updatedWorker->isActive)->toBeTrue(); // Original still active
+            expect($inactiveWorker->isActive)->toBeFalse(); // New instance inactive
+        });
+    });
+});