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/Admin/CrudServiceTest.php

@@ -0,0 +1,278 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Admin\Factories\AdminFormFactory;
+use App\Framework\Admin\Services\CrudService;
+use App\Framework\Admin\ValueObjects\CrudConfig;
+use App\Framework\Http\HttpRequest;
+use App\Framework\Http\Method;
+use App\Framework\Http\Responses\Redirect;
+use App\Framework\Http\Responses\ViewResult;
+use App\Framework\View\TemplateRenderer;
+
+beforeEach(function () {
+    $this->renderer = Mockery::mock(TemplateRenderer::class);
+    $this->formFactory = Mockery::mock(AdminFormFactory::class);
+    $this->service = new CrudService($this->renderer, $this->formFactory);
+
+    $this->config = CrudConfig::forResource(
+        resource: 'campaigns',
+        resourceName: 'Campaign',
+        title: 'Campaigns'
+    )->withColumns([
+        ['field' => 'name', 'label' => 'Name'],
+        ['field' => 'status', 'label' => 'Status'],
+    ]);
+});
+
+afterEach(function () {
+    Mockery::close();
+});
+
+describe('CrudService', function () {
+    describe('renderIndex', function () {
+        it('renders index view with items and pagination', function () {
+            $items = [
+                ['id' => '1', 'name' => 'Campaign 1', 'status' => 'active'],
+                ['id' => '2', 'name' => 'Campaign 2', 'status' => 'draft'],
+            ];
+
+            $pagination = [
+                'current_page' => 1,
+                'total_pages' => 5,
+                'per_page' => 10,
+            ];
+
+            $request = Mockery::mock(HttpRequest::class);
+            $request->shouldReceive('uri')->andReturn('/admin/campaigns');
+
+            $result = $this->service->renderIndex(
+                $this->config,
+                $items,
+                $request,
+                $pagination
+            );
+
+            expect($result)->toBeInstanceOf(ViewResult::class);
+            expect($result->template)->toBe('crud-index');
+            expect($result->data['items'])->toBe($items);
+            expect($result->data['pagination'])->toBe($pagination);
+            expect($result->data['resource'])->toBe('campaigns');
+            expect($result->data['createUrl'])->toBe('/admin/campaigns/create');
+        });
+    });
+
+    describe('renderCreate', function () {
+        it('renders create form with default configuration', function () {
+            $formFields = [
+                ['type' => 'text', 'name' => 'name', 'label' => 'Name'],
+            ];
+
+            $mockForm = Mockery::mock();
+            $mockForm->shouldReceive('build')->andReturn('<form>...</form>');
+            $mockForm->shouldReceive('getId')->andReturn('campaign-form');
+
+            $this->formFactory->shouldReceive('create')
+                ->once()
+                ->andReturn($mockForm);
+
+            $result = $this->service->renderCreate(
+                $this->config,
+                $formFields
+            );
+
+            expect($result)->toBeInstanceOf(ViewResult::class);
+            expect($result->template)->toBe('crud-create');
+            expect($result->data['title'])->toBe('Create Campaign');
+            expect($result->data['formId'])->toBe('campaign-form');
+            expect($result->data['backUrl'])->toBe('/admin/campaigns');
+        });
+
+        it('renders create form with help text', function () {
+            $formFields = [];
+            $helpText = 'Fill in the campaign details carefully.';
+
+            $mockForm = Mockery::mock();
+            $mockForm->shouldReceive('build')->andReturn('');
+            $mockForm->shouldReceive('getId')->andReturn('form-id');
+
+            $this->formFactory->shouldReceive('create')->andReturn($mockForm);
+
+            $result = $this->service->renderCreate(
+                $this->config,
+                $formFields,
+                null,
+                $helpText
+            );
+
+            expect($result->data['helpText'])->toBe($helpText);
+        });
+    });
+
+    describe('renderEdit', function () {
+        it('renders edit form with item data and metadata', function () {
+            $formFields = [
+                ['type' => 'text', 'name' => 'name', 'label' => 'Name'],
+            ];
+
+            $itemData = [
+                'id' => '123',
+                'name' => 'Test Campaign',
+                'status' => 'active',
+            ];
+
+            $metadata = [
+                'id' => '123',
+                'createdAt' => '2024-01-01 10:00:00',
+                'updatedAt' => '2024-01-02 15:30:00',
+            ];
+
+            $mockForm = Mockery::mock();
+            $mockForm->shouldReceive('build')->andReturn('<form>...</form>');
+            $mockForm->shouldReceive('getId')->andReturn('edit-form');
+
+            $this->formFactory->shouldReceive('create')
+                ->once()
+                ->andReturn($mockForm);
+
+            $result = $this->service->renderEdit(
+                $this->config,
+                '123',
+                $formFields,
+                $itemData,
+                $metadata
+            );
+
+            expect($result)->toBeInstanceOf(ViewResult::class);
+            expect($result->template)->toBe('crud-edit');
+            expect($result->data['title'])->toBe('Edit Campaign');
+            expect($result->data['metadata'])->toBe($metadata);
+            expect($result->data['deleteUrl'])->toBe('/admin/campaigns/delete/123');
+        });
+    });
+
+    describe('renderShow', function () {
+        it('renders show view with fields and metadata', function () {
+            $fields = [
+                ['label' => 'Name', 'value' => 'Test Campaign', 'type' => 'text'],
+                ['label' => 'Status', 'value' => 'Active', 'type' => 'badge', 'color' => 'success'],
+            ];
+
+            $metadata = [
+                'id' => '123',
+                'createdAt' => '2024-01-01',
+            ];
+
+            $result = $this->service->renderShow(
+                $this->config,
+                '123',
+                $fields,
+                $metadata
+            );
+
+            expect($result)->toBeInstanceOf(ViewResult::class);
+            expect($result->template)->toBe('crud-show');
+            expect($result->data['fields'])->toBe($fields);
+            expect($result->data['metadata'])->toBe($metadata);
+            expect($result->data['editUrl'])->toBe('/admin/campaigns/edit/123');
+        });
+    });
+
+    describe('redirectAfterCreate', function () {
+        it('redirects to index after successful create', function () {
+            $request = Mockery::mock(HttpRequest::class);
+            $request->parsedBody = Mockery::mock();
+            $request->parsedBody->shouldReceive('get')
+                ->with('action')
+                ->andReturn(null);
+
+            $result = $this->service->redirectAfterCreate(
+                $this->config,
+                $request,
+                '123'
+            );
+
+            expect($result)->toBeInstanceOf(Redirect::class);
+            expect($result->url)->toBe('/admin/campaigns');
+        });
+
+        it('redirects to create form when save-and-continue is requested', function () {
+            $request = Mockery::mock(HttpRequest::class);
+            $request->parsedBody = Mockery::mock();
+            $request->parsedBody->shouldReceive('get')
+                ->with('action')
+                ->andReturn('save-and-continue');
+
+            $result = $this->service->redirectAfterCreate(
+                $this->config,
+                $request,
+                '123'
+            );
+
+            expect($result->url)->toBe('/admin/campaigns/create');
+        });
+    });
+
+    describe('redirectAfterUpdate', function () {
+        it('redirects to index after successful update', function () {
+            $request = Mockery::mock(HttpRequest::class);
+            $request->parsedBody = Mockery::mock();
+            $request->parsedBody->shouldReceive('get')
+                ->with('action')
+                ->andReturn(null);
+
+            $result = $this->service->redirectAfterUpdate(
+                $this->config,
+                $request,
+                '123'
+            );
+
+            expect($result->url)->toBe('/admin/campaigns');
+        });
+
+        it('redirects to show view when save-and-view is requested', function () {
+            $request = Mockery::mock(HttpRequest::class);
+            $request->parsedBody = Mockery::mock();
+            $request->parsedBody->shouldReceive('get')
+                ->with('action')
+                ->andReturn('save-and-view');
+
+            $result = $this->service->redirectAfterUpdate(
+                $this->config,
+                $request,
+                '123'
+            );
+
+            expect($result->url)->toBe('/admin/campaigns/view/123');
+        });
+    });
+
+    describe('redirectAfterDelete', function () {
+        it('redirects to index after successful delete', function () {
+            $result = $this->service->redirectAfterDelete($this->config);
+
+            expect($result)->toBeInstanceOf(Redirect::class);
+            expect($result->url)->toBe('/admin/campaigns');
+        });
+    });
+
+    describe('redirectWithError', function () {
+        it('redirects back with error message', function () {
+            $result = $this->service->redirectWithError('Something went wrong');
+
+            expect($result)->toBeInstanceOf(Redirect::class);
+        });
+
+        it('redirects with error message and input data', function () {
+            $inputData = ['name' => 'Test', 'email' => 'test@example.com'];
+
+            $result = $this->service->redirectWithError(
+                'Validation failed',
+                $inputData
+            );
+
+            expect($result)->toBeInstanceOf(Redirect::class);
+        });
+    });
+});

tests/Framework/Admin/ValueObjects/CrudConfigTest.php

@@ -0,0 +1,177 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Admin\ValueObjects\CrudConfig;
+
+describe('CrudConfig', function () {
+    it('creates config with basic resource information', function () {
+        $config = CrudConfig::forResource(
+            resource: 'campaigns',
+            resourceName: 'Campaign',
+            title: 'Campaigns'
+        );
+
+        expect($config->resource)->toBe('campaigns');
+        expect($config->resourceName)->toBe('Campaign');
+        expect($config->title)->toBe('Campaigns');
+        expect($config->canCreate)->toBeTrue();
+        expect($config->canEdit)->toBeTrue();
+        expect($config->canView)->toBeTrue();
+        expect($config->canDelete)->toBeTrue();
+        expect($config->searchable)->toBeTrue();
+    });
+
+    it('creates config with columns', function () {
+        $columns = [
+            ['field' => 'name', 'label' => 'Name', 'sortable' => true],
+            ['field' => 'status', 'label' => 'Status', 'sortable' => true],
+        ];
+
+        $config = CrudConfig::forResource('campaigns', 'Campaign', 'Campaigns')
+            ->withColumns($columns);
+
+        expect($config->columns)->toBe($columns);
+        expect($config->resource)->toBe('campaigns');
+    });
+
+    it('creates config with custom permissions', function () {
+        $config = CrudConfig::forResource('campaigns', 'Campaign', 'Campaigns')
+            ->withPermissions(
+                canCreate: true,
+                canEdit: true,
+                canView: false,
+                canDelete: false
+            );
+
+        expect($config->canCreate)->toBeTrue();
+        expect($config->canEdit)->toBeTrue();
+        expect($config->canView)->toBeFalse();
+        expect($config->canDelete)->toBeFalse();
+    });
+
+    it('creates config with filters', function () {
+        $filters = [
+            ['field' => 'status', 'type' => 'select', 'options' => ['active', 'draft']],
+            ['field' => 'category', 'type' => 'select', 'options' => ['music', 'podcast']],
+        ];
+
+        $config = CrudConfig::forResource('campaigns', 'Campaign', 'Campaigns')
+            ->withFilters($filters);
+
+        expect($config->filters)->toBe($filters);
+    });
+
+    it('creates config with bulk actions', function () {
+        $bulkActions = [
+            ['name' => 'activate', 'label' => 'Activate Selected'],
+            ['name' => 'archive', 'label' => 'Archive Selected'],
+        ];
+
+        $config = CrudConfig::forResource('campaigns', 'Campaign', 'Campaigns')
+            ->withBulkActions($bulkActions);
+
+        expect($config->bulkActions)->toBe($bulkActions);
+    });
+
+    it('converts to array with all properties', function () {
+        $config = CrudConfig::forResource('campaigns', 'Campaign', 'Campaigns')
+            ->withColumns([
+                ['field' => 'name', 'label' => 'Name'],
+            ])
+            ->withPermissions(
+                canCreate: true,
+                canEdit: true,
+                canView: true,
+                canDelete: false
+            );
+
+        $array = $config->toArray();
+
+        expect($array)->toHaveKey('resource');
+        expect($array)->toHaveKey('resourceName');
+        expect($array)->toHaveKey('title');
+        expect($array)->toHaveKey('columns');
+        expect($array)->toHaveKey('canCreate');
+        expect($array)->toHaveKey('canEdit');
+        expect($array)->toHaveKey('canView');
+        expect($array)->toHaveKey('canDelete');
+        expect($array)->toHaveKey('hasActions');
+        expect($array)->toHaveKey('searchable');
+
+        expect($array['resource'])->toBe('campaigns');
+        expect($array['resourceName'])->toBe('Campaign');
+        expect($array['hasActions'])->toBeTrue(); // canEdit is true
+    });
+
+    it('calculates hasActions correctly when no actions are allowed', function () {
+        $config = CrudConfig::forResource('campaigns', 'Campaign', 'Campaigns')
+            ->withPermissions(
+                canCreate: false,
+                canEdit: false,
+                canView: false,
+                canDelete: false
+            );
+
+        $array = $config->toArray();
+
+        expect($array['hasActions'])->toBeFalse();
+    });
+
+    it('calculates hasActions correctly when any action is allowed', function () {
+        $config1 = CrudConfig::forResource('campaigns', 'Campaign', 'Campaigns')
+            ->withPermissions(canCreate: false, canEdit: true, canView: false, canDelete: false);
+
+        $config2 = CrudConfig::forResource('campaigns', 'Campaign', 'Campaigns')
+            ->withPermissions(canCreate: false, canEdit: false, canView: true, canDelete: false);
+
+        $config3 = CrudConfig::forResource('campaigns', 'Campaign', 'Campaigns')
+            ->withPermissions(canCreate: false, canEdit: false, canView: false, canDelete: true);
+
+        expect($config1->toArray()['hasActions'])->toBeTrue();
+        expect($config2->toArray()['hasActions'])->toBeTrue();
+        expect($config3->toArray()['hasActions'])->toBeTrue();
+    });
+
+    it('chains multiple configuration methods', function () {
+        $config = CrudConfig::forResource('campaigns', 'Campaign', 'Campaigns')
+            ->withColumns([['field' => 'name', 'label' => 'Name']])
+            ->withPermissions(canCreate: true, canEdit: true, canView: false, canDelete: false)
+            ->withFilters([['field' => 'status', 'type' => 'select']])
+            ->withBulkActions([['name' => 'activate', 'label' => 'Activate']]);
+
+        expect($config->columns)->toHaveCount(1);
+        expect($config->filters)->toHaveCount(1);
+        expect($config->bulkActions)->toHaveCount(1);
+        expect($config->canView)->toBeFalse();
+        expect($config->canCreate)->toBeTrue();
+    });
+
+    it('creates immutable value objects', function () {
+        $original = CrudConfig::forResource('campaigns', 'Campaign', 'Campaigns');
+        $modified = $original->withColumns([['field' => 'name', 'label' => 'Name']]);
+
+        // Original should not be modified
+        expect($original->columns)->toBe([]);
+        expect($modified->columns)->toHaveCount(1);
+
+        // They should be different instances
+        expect($original !== $modified)->toBeTrue();
+    });
+
+    it('preserves all properties when using with methods', function () {
+        $filters = [['field' => 'status', 'type' => 'select']];
+        $bulkActions = [['name' => 'activate', 'label' => 'Activate']];
+
+        $original = CrudConfig::forResource('campaigns', 'Campaign', 'Campaigns')
+            ->withFilters($filters)
+            ->withBulkActions($bulkActions);
+
+        $withColumns = $original->withColumns([['field' => 'name', 'label' => 'Name']]);
+
+        // New config should have all previous properties
+        expect($withColumns->filters)->toBe($filters);
+        expect($withColumns->bulkActions)->toBe($bulkActions);
+        expect($withColumns->columns)->toHaveCount(1);
+    });
+});

tests/Framework/Attributes/RouteAttributeTest.php

@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Attributes\Route;
+use App\Framework\Http\Method;
+use App\Framework\Router\ValueObjects\Placeholder;
+use App\Framework\Router\ValueObjects\RoutePath;
+
+describe('Route Attribute', function () {
+    describe('string path support', function () {
+        it('works with traditional string paths', function () {
+            $route = new Route(path: '/api/users/{id}', method: Method::GET);
+
+            expect($route->getPathAsString())->toBe('/api/users/{id}');
+            expect($route->getRoutePath()->toString())->toBe('/api/users/{id}');
+            expect($route->getRoutePath()->isDynamic())->toBeTrue();
+        });
+
+        it('handles static string paths', function () {
+            $route = new Route(path: '/health', method: Method::GET);
+
+            expect($route->getPathAsString())->toBe('/health');
+            expect($route->getRoutePath()->isStatic())->toBeTrue();
+        });
+    });
+
+    describe('RoutePath object support', function () {
+        it('works with RoutePath objects', function () {
+            $routePath = RoutePath::fromElements(
+                'api',
+                'images',
+                Placeholder::fromString('filename')
+            );
+
+            $route = new Route(path: $routePath, method: Method::GET);
+
+            expect($route->getPathAsString())->toBe('/api/images/{filename}');
+            expect($route->getRoutePath())->toBe($routePath);
+        });
+
+        it('handles complex RoutePath objects', function () {
+            $routePath = RoutePath::fromElements(
+                'api',
+                'users',
+                Placeholder::typed('userId', 'uuid'),
+                'posts',
+                Placeholder::typed('postId', 'int')
+            );
+
+            $route = new Route(path: $routePath, method: Method::POST);
+
+            expect($route->getPathAsString())->toBe('/api/users/{userId}/posts/{postId}');
+            expect($route->method)->toBe(Method::POST);
+        });
+
+        it('handles wildcard parameters', function () {
+            $routePath = RoutePath::fromElements(
+                'files',
+                Placeholder::wildcard('path')
+            );
+
+            $route = new Route(path: $routePath, method: Method::GET);
+
+            expect($route->getPathAsString())->toBe('/files/{path*}');
+        });
+    });
+
+    describe('mixed usage compatibility', function () {
+        it('provides consistent interface regardless of input type', function () {
+            $stringRoute = new Route(path: '/api/users/{id}', method: Method::GET);
+            $objectRoute = new Route(
+                path: RoutePath::fromElements('api', 'users', Placeholder::fromString('id')),
+                method: Method::GET
+            );
+
+            expect($stringRoute->getPathAsString())->toBe($objectRoute->getPathAsString());
+            expect($stringRoute->getRoutePath()->toString())->toBe($objectRoute->getRoutePath()->toString());
+        });
+    });
+
+    describe('route compilation', function () {
+        it('compiles to CompiledRoute correctly', function () {
+            $routePath = RoutePath::fromElements(
+                'api',
+                'users',
+                Placeholder::typed('id', 'int')
+            );
+
+            $route = new Route(path: $routePath, method: Method::GET, name: 'users.show');
+
+            // Note: This test would need CompiledRoute to be available
+            // For now, we just test the path conversion
+            expect($route->getPathAsString())->toBe('/api/users/{id}');
+        });
+    });
+});

tests/Framework/CommandBus/DefaultCommandBusTest.php

@@ -10,8 +10,13 @@ use App\Framework\CommandBus\ShouldQueue;
 use App\Framework\Context\ContextType;
 use App\Framework\Context\ExecutionContext;
 use App\Framework\DI\DefaultContainer;
+use App\Framework\Logging\ChannelLogger;
+use App\Framework\Logging\LogChannel;
 use App\Framework\Logging\Logger;
+use App\Framework\Logging\LogLevel;
+use App\Framework\Logging\ValueObjects\LogContext;
 use App\Framework\Queue\Queue;
+use App\Framework\Queue\ValueObjects\JobPayload;
 
 beforeEach(function () {
     $this->container = new DefaultContainer();
@@ -153,17 +158,39 @@ class TestQueue implements Queue
 
     private array $jobs = [];
 
-    public function push(object $job): void
+    public function push(JobPayload $payload): void
     {
         $this->used = true;
-        $this->jobs[] = $job;
+        $this->jobs[] = $payload;
     }
 
-    public function pop(): ?object
+    public function pop(): ?JobPayload
     {
         return array_shift($this->jobs);
     }
 
+    public function peek(): ?JobPayload
+    {
+        return $this->jobs[0] ?? null;
+    }
+
+    public function size(): int
+    {
+        return count($this->jobs);
+    }
+
+    public function clear(): int
+    {
+        $count = count($this->jobs);
+        $this->jobs = [];
+        return $count;
+    }
+
+    public function getStats(): array
+    {
+        return ['size' => count($this->jobs)];
+    }
+
     public function wasUsed(): bool
     {
         return $this->used;
@@ -172,35 +199,112 @@ class TestQueue implements Queue
 
 class TestLogger implements Logger
 {
-    public function emergency(string $message, array $context = []): void
+    private ?ChannelLogger $mockChannelLogger = null;
+
+    public function emergency(string $message, ?LogContext $context = null): void
     {
     }
 
-    public function alert(string $message, array $context = []): void
+    public function alert(string $message, ?LogContext $context = null): void
     {
     }
 
-    public function critical(string $message, array $context = []): void
+    public function critical(string $message, ?LogContext $context = null): void
     {
     }
 
-    public function error(string $message, array $context = []): void
+    public function error(string $message, ?LogContext $context = null): void
     {
     }
 
-    public function warning(string $message, array $context = []): void
+    public function warning(string $message, ?LogContext $context = null): void
     {
     }
 
-    public function notice(string $message, array $context = []): void
+    public function notice(string $message, ?LogContext $context = null): void
     {
     }
 
-    public function info(string $message, array $context = []): void
+    public function info(string $message, ?LogContext $context = null): void
     {
     }
 
-    public function debug(string $message, array $context = []): void
+    public function debug(string $message, ?LogContext $context = null): void
     {
     }
+
+    public function log(LogLevel $level, string $message, ?LogContext $context = null): void
+    {
+    }
+
+    public function logToChannel(LogChannel $channel, LogLevel $level, string $message, ?LogContext $context = null): void
+    {
+    }
+
+    public ChannelLogger $security {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    public ChannelLogger $cache {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    public ChannelLogger $database {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    public ChannelLogger $framework {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    public ChannelLogger $error {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    private function createMockChannelLogger(): ChannelLogger
+    {
+        return new class () implements ChannelLogger {
+            public function emergency(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function alert(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function critical(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function error(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function warning(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function notice(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function info(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function debug(string $message, ?LogContext $context = null): void
+            {
+            }
+        };
+    }
 }

tests/Framework/Database/Migration/MigrationPerformanceTest.php

@@ -0,0 +1,457 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Core\ValueObjects\Percentage;
+use App\Framework\Database\ConnectionInterface;
+use App\Framework\Database\Migration\Exception\MemoryThresholdExceededException;
+use App\Framework\Database\Migration\Migration;
+use App\Framework\Database\Migration\MigrationCollection;
+use App\Framework\Database\Migration\MigrationRunner;
+use App\Framework\Database\Migration\MigrationVersion;
+use App\Framework\Database\Migration\ValueObjects\MemoryThresholds;
+use App\Framework\Database\Platform\MySQLPlatform;
+use App\Framework\Database\ResultInterface;
+use App\Framework\Database\ValueObjects\SqlQuery;
+use App\Framework\DateTime\SystemClock;
+use App\Framework\Performance\MemoryMonitor;
+use App\Framework\Performance\OperationTracker;
+use App\Framework\Performance\PerformanceReporter;
+
+describe('Migration Performance Integration', function () {
+    beforeEach(function () {
+        $this->connection = new MigrationPerformanceMockConnection();
+        $this->platform = new MySQLPlatform();
+        $this->clock = new SystemClock();
+        $this->memoryMonitor = new MemoryMonitor();
+        $this->operationTracker = new OperationTracker($this->clock, $this->memoryMonitor);
+
+        $this->migrationRunner = new MigrationRunner(
+            $this->connection,
+            $this->platform,
+            $this->clock,
+            null, // tableConfig
+            null, // logger
+            $this->operationTracker,
+            $this->memoryMonitor
+        );
+    });
+
+    test('migration runner integrates with performance monitoring', function () {
+        $migration = new MigrationPerformanceTestMigration();
+        $migrations = new MigrationCollection($migration);
+
+        // Set no applied migrations initially
+        $this->connection->setAppliedMigrations([]);
+
+        $result = $this->migrationRunner->migrate($migrations);
+
+        expect($result)->toContain('2024_01_01_000000');
+        expect($migration->wasExecuted())->toBeTrue();
+
+        // Verify performance tracking was used
+        expect($this->operationTracker)->toBeInstanceOf(OperationTracker::class);
+        expect($this->memoryMonitor)->toBeInstanceOf(MemoryMonitor::class);
+    });
+
+    test('memory monitor provides memory summary', function () {
+        $memorySummary = $this->memoryMonitor->getSummary();
+
+        expect($memorySummary)->toHaveProperties([
+            'current',
+            'peak',
+            'limit',
+            'usagePercentage',
+            'isApproachingLimit',
+        ]);
+
+        expect($memorySummary->getCurrentHumanReadable())->toBeString();
+        expect($memorySummary->getPeakHumanReadable())->toBeString();
+        expect($memorySummary->getUsagePercentageFormatted())->toBeString();
+    });
+
+    test('operation tracker can track operations', function () {
+        $operationId = 'test_migration_batch_' . uniqid();
+
+        $snapshot = $this->operationTracker->startOperation(
+            $operationId,
+            \App\Framework\Performance\PerformanceCategory::DATABASE,
+            ['operation_type' => 'migration_test']
+        );
+
+        expect($snapshot)->toBeInstanceOf(\App\Framework\Performance\ValueObjects\PerformanceSnapshot::class);
+
+        // Complete the operation
+        $finalSnapshot = $this->operationTracker->completeOperation($operationId);
+
+        expect($finalSnapshot)->toBeInstanceOf(\App\Framework\Performance\ValueObjects\PerformanceSnapshot::class);
+        expect($finalSnapshot->duration)->toBeInstanceOf(\App\Framework\Core\ValueObjects\Duration::class);
+    });
+
+    test('memory thresholds can be configured with custom values', function () {
+        $customThresholds = new MemoryThresholds(
+            warning: Percentage::from(60.0),
+            critical: Percentage::from(75.0),
+            abort: Percentage::from(90.0)
+        );
+
+        expect($customThresholds->warning->getValue())->toBe(60.0);
+        expect($customThresholds->critical->getValue())->toBe(75.0);
+        expect($customThresholds->abort->getValue())->toBe(90.0);
+    });
+
+    test('memory thresholds default configuration is valid', function () {
+        $defaultThresholds = MemoryThresholds::default();
+
+        expect($defaultThresholds->warning->getValue())->toBe(75.0);
+        expect($defaultThresholds->critical->getValue())->toBe(85.0);
+        expect($defaultThresholds->abort->getValue())->toBe(95.0);
+    });
+
+    test('memory thresholds conservative configuration is valid', function () {
+        $conservativeThresholds = MemoryThresholds::conservative();
+
+        expect($conservativeThresholds->warning->getValue())->toBe(60.0);
+        expect($conservativeThresholds->critical->getValue())->toBe(70.0);
+        expect($conservativeThresholds->abort->getValue())->toBe(80.0);
+    });
+
+    test('memory thresholds relaxed configuration is valid', function () {
+        $relaxedThresholds = MemoryThresholds::relaxed();
+
+        expect($relaxedThresholds->warning->getValue())->toBe(80.0);
+        expect($relaxedThresholds->critical->getValue())->toBe(90.0);
+        expect($relaxedThresholds->abort->getValue())->toBe(98.0);
+    });
+
+    test('memory threshold exception can be created for migration', function () {
+        $currentUsage = Percentage::from(96.0);
+        $threshold = Percentage::from(95.0);
+        $currentMemory = \App\Framework\Core\ValueObjects\Byte::fromBytes(256 * 1024 * 1024);
+        $memoryLimit = \App\Framework\Core\ValueObjects\Byte::fromBytes(256 * 1024 * 1024);
+
+        $exception = MemoryThresholdExceededException::forMigration(
+            '2024_01_01_000001',
+            $currentUsage,
+            $threshold,
+            $currentMemory,
+            $memoryLimit
+        );
+
+        expect($exception->getMessage())->toContain('Memory threshold exceeded during migration 2024_01_01_000001');
+        expect($exception->getMessage())->toContain('96.0%');
+        expect($exception->getMessage())->toContain('95.0%');
+    });
+
+    test('memory threshold exception can be created for batch abort', function () {
+        $currentUsage = Percentage::from(97.0);
+        $abortThreshold = Percentage::from(95.0);
+        $currentMemory = \App\Framework\Core\ValueObjects\Byte::fromBytes(248 * 1024 * 1024);
+        $memoryLimit = \App\Framework\Core\ValueObjects\Byte::fromBytes(256 * 1024 * 1024);
+
+        $exception = MemoryThresholdExceededException::batchAborted(
+            $currentUsage,
+            $abortThreshold,
+            $currentMemory,
+            $memoryLimit,
+            3,
+            10
+        );
+
+        expect($exception->getMessage())->toContain('Migration batch aborted due to critical memory usage');
+        expect($exception->getMessage())->toContain('97.0%');
+        expect($exception->getMessage())->toContain('95.0%');
+    });
+
+    test('migration runner with memory thresholds can handle normal operation', function () {
+        $memoryThresholds = MemoryThresholds::conservative();
+
+        $migrationRunner = new MigrationRunner(
+            $this->connection,
+            $this->platform,
+            $this->clock,
+            null, // tableConfig
+            null, // logger
+            $this->operationTracker,
+            $this->memoryMonitor,
+            null, // performanceReporter
+            $memoryThresholds
+        );
+
+        $migration = new MigrationPerformanceTestMigration();
+        $migrations = new MigrationCollection($migration);
+
+        // Set no applied migrations initially
+        $this->connection->setAppliedMigrations([]);
+
+        $result = $migrationRunner->migrate($migrations);
+
+        expect($result)->toContain('2024_01_01_000000');
+        expect($migration->wasExecuted())->toBeTrue();
+    });
+
+    test('rollback operation includes performance tracking', function () {
+        $migration = new MigrationPerformanceTestMigration();
+        $migrations = new MigrationCollection($migration);
+
+        // Set migration as already applied
+        $this->connection->setAppliedMigrations([
+            ['version' => '2024_01_01_000000', 'description' => 'Performance Test Migration'],
+        ]);
+
+        $result = $this->migrationRunner->rollback($migrations, 1);
+
+        expect($result)->toContain($migration);
+
+        // Verify performance tracking was used during rollback
+        expect($this->operationTracker)->toBeInstanceOf(OperationTracker::class);
+        expect($this->memoryMonitor)->toBeInstanceOf(MemoryMonitor::class);
+    });
+
+    test('operation tracker can track multiple operations', function () {
+        $operationId1 = 'test_migration_1';
+        $operationId2 = 'test_migration_2';
+
+        // Start first operation
+        $snapshot1 = $this->operationTracker->startOperation(
+            $operationId1,
+            \App\Framework\Performance\PerformanceCategory::DATABASE,
+            ['operation_type' => 'migration_execution']
+        );
+
+        // Start second operation
+        $snapshot2 = $this->operationTracker->startOperation(
+            $operationId2,
+            \App\Framework\Performance\PerformanceCategory::DATABASE,
+            ['operation_type' => 'migration_execution']
+        );
+
+        usleep(1000); // Small delay to ensure duration > 0
+
+        // Complete both operations
+        $finalSnapshot1 = $this->operationTracker->completeOperation($operationId1);
+        $finalSnapshot2 = $this->operationTracker->completeOperation($operationId2);
+
+        expect($finalSnapshot1)->toBeInstanceOf(\App\Framework\Performance\ValueObjects\PerformanceSnapshot::class);
+        expect($finalSnapshot2)->toBeInstanceOf(\App\Framework\Performance\ValueObjects\PerformanceSnapshot::class);
+        expect($finalSnapshot1->operationId)->toBe($operationId1);
+        expect($finalSnapshot2->operationId)->toBe($operationId2);
+    });
+
+    test('migration runner validates memory threshold order', function () {
+        expect(function () {
+            new MemoryThresholds(
+                warning: Percentage::from(90.0),  // Warning higher than critical
+                critical: Percentage::from(80.0),
+                abort: Percentage::from(95.0)
+            );
+        })->toThrow(\InvalidArgumentException::class, 'Warning threshold cannot be higher than critical threshold');
+
+        expect(function () {
+            new MemoryThresholds(
+                warning: Percentage::from(70.0),
+                critical: Percentage::from(90.0),  // Critical higher than abort
+                abort: Percentage::from(80.0)
+            );
+        })->toThrow(\InvalidArgumentException::class, 'Critical threshold cannot be higher than abort threshold');
+    });
+
+    test('migration runner can handle pre-flight checks', function () {
+        $migration = new MigrationPerformanceTestMigration();
+        $migrations = new MigrationCollection($migration);
+
+        // Set no applied migrations initially
+        $this->connection->setAppliedMigrations([]);
+
+        // Should pass pre-flight checks for mock connection
+        $result = $this->migrationRunner->migrate($migrations);
+
+        expect($result)->toContain('2024_01_01_000000');
+        expect($migration->wasExecuted())->toBeTrue();
+    });
+});
+
+// Test fixtures
+class MigrationPerformanceTestMigration implements Migration
+{
+    private bool $executed = false;
+
+    public function up(ConnectionInterface $connection): void
+    {
+        $this->executed = true;
+        // Simulate migration execution
+        $connection->execute(SqlQuery::create('CREATE TABLE performance_test (id INT)'));
+    }
+
+    public function down(ConnectionInterface $connection): void
+    {
+        $connection->execute(SqlQuery::create('DROP TABLE performance_test'));
+    }
+
+    public function getDescription(): string
+    {
+        return 'Performance Test Migration';
+    }
+
+    public function getVersion(): MigrationVersion
+    {
+        return MigrationVersion::fromTimestamp('2024_01_01_000000');
+    }
+
+    public function wasExecuted(): bool
+    {
+        return $this->executed;
+    }
+}
+
+class MigrationPerformanceMockConnection implements ConnectionInterface
+{
+    private array $queries = [];
+
+    private array $appliedMigrations = [];
+
+    private bool $inTransaction = false;
+
+    public function setAppliedMigrations(array $migrations): void
+    {
+        $this->appliedMigrations = $migrations;
+    }
+
+    public function execute(SqlQuery $query): int
+    {
+        $this->queries[] = ['type' => 'execute', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
+
+        return 1;
+    }
+
+    public function query(SqlQuery $query): ResultInterface
+    {
+        $this->queries[] = ['type' => 'query', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
+
+        return new MigrationPerformanceMockResult($this->appliedMigrations);
+    }
+
+    public function queryOne(SqlQuery $query): ?array
+    {
+        return null;
+    }
+
+    public function queryColumn(SqlQuery $query): array
+    {
+        $this->queries[] = ['type' => 'queryColumn', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
+
+        return array_column($this->appliedMigrations, 'version');
+    }
+
+    public function queryScalar(SqlQuery $query): mixed
+    {
+        $this->queries[] = ['type' => 'queryScalar', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
+
+        // Return '1' for connectivity test (SELECT 1)
+        if (str_contains($query->sql, 'SELECT 1')) {
+            return '1';
+        }
+
+        return null;
+    }
+
+    public function beginTransaction(): void
+    {
+        $this->inTransaction = true;
+    }
+
+    public function commit(): void
+    {
+        $this->inTransaction = false;
+    }
+
+    public function rollback(): void
+    {
+        $this->inTransaction = false;
+    }
+
+    public function inTransaction(): bool
+    {
+        return $this->inTransaction;
+    }
+
+    public function lastInsertId(): string
+    {
+        return '1';
+    }
+
+    public function getPdo(): \PDO
+    {
+        return new class () extends \PDO {
+            public function __construct()
+            {
+                // Skip parent constructor to avoid actual DB connection
+            }
+
+            public function getAttribute(int $attribute): mixed
+            {
+                return match($attribute) {
+                    \PDO::ATTR_DRIVER_NAME => 'mysql',
+                    default => null
+                };
+            }
+        };
+    }
+
+    public function getQueries(): array
+    {
+        return $this->queries;
+    }
+}
+
+class MigrationPerformanceMockResult implements ResultInterface
+{
+    private array $data;
+
+    public function __construct(array $data)
+    {
+        $this->data = $data;
+    }
+
+    public function fetch(): ?array
+    {
+        return $this->data[0] ?? null;
+    }
+
+    public function fetchAll(): array
+    {
+        return $this->data;
+    }
+
+    public function fetchOne(): ?array
+    {
+        return $this->data[0] ?? null;
+    }
+
+    public function fetchColumn(int $column = 0): array
+    {
+        return array_column($this->data, $column);
+    }
+
+    public function fetchScalar(): mixed
+    {
+        $row = $this->fetchOne();
+
+        return $row ? array_values($row)[0] : null;
+    }
+
+    public function rowCount(): int
+    {
+        return count($this->data);
+    }
+
+    public function getIterator(): \Traversable
+    {
+        return new \ArrayIterator($this->data);
+    }
+
+    public function count(): int
+    {
+        return count($this->data);
+    }
+}

tests/Framework/Database/Migration/MigrationRunnerTest.php

@@ -5,12 +5,31 @@ declare(strict_types=1);
 use App\Framework\Database\ConnectionInterface;
 use App\Framework\Database\Exception\DatabaseException;
 use App\Framework\Database\Migration\Migration;
+use App\Framework\Database\Migration\MigrationCollection;
 use App\Framework\Database\Migration\MigrationRunner;
+use App\Framework\Database\Platform\MySqlPlatform;
 use App\Framework\Database\ResultInterface;
+use App\Framework\Database\ValueObjects\SqlQuery;
+use App\Framework\DateTime\SystemClock;
+use App\Framework\Performance\MemoryMonitor;
+use App\Framework\Performance\OperationTracker;
 
 beforeEach(function () {
     $this->connection = new TestConnection();
-    $this->migrationRunner = new MigrationRunner($this->connection, 'test_migrations');
+    $this->platform = new MySqlPlatform();
+    $this->clock = new SystemClock();
+    $this->memoryMonitor = new MemoryMonitor();
+    $this->operationTracker = new OperationTracker();
+
+    $this->migrationRunner = new MigrationRunner(
+        $this->connection,
+        $this->platform,
+        $this->clock,
+        null, // tableConfig
+        null, // logger
+        $this->operationTracker,
+        $this->memoryMonitor
+    );
 });
 
 test('constructor creates migrations table', function () {
@@ -25,16 +44,12 @@ test('constructor creates migrations table', function () {
 test('migrate runs pending migrations', function () {
     // Mock migration
     $migration = new TestMigration();
-    $migrationData = (object) [
-        'version' => '2024_01_01_000000',
-        'description' => 'Test Migration',
-        'instance' => $migration,
-    ];
+    $migrations = new MigrationCollection($migration);
 
     // Set no applied migrations initially
     $this->connection->setAppliedMigrations([]);
 
-    $result = $this->migrationRunner->migrate([$migrationData]);
+    $result = $this->migrationRunner->migrate($migrations);
 
     expect($result)->toContain('2024_01_01_000000');
     expect($migration->wasExecuted())->toBeTrue();
@@ -44,7 +59,7 @@ test('migrate runs pending migrations', function () {
     $insertQueries = array_filter(
         $queries,
         fn ($q) =>
-        $q['type'] === 'execute' && str_contains($q['sql'], 'INSERT INTO test_migrations')
+        $q['type'] === 'execute' && str_contains($q['sql'], 'INSERT INTO')
     );
     expect($insertQueries)->toHaveCount(1);
 });
@@ -219,38 +234,38 @@ class TestConnection implements ConnectionInterface
         $this->shouldFail = $fail;
     }
 
-    public function execute(string $sql, array $parameters = []): int
+    public function execute(SqlQuery $query): int
     {
-        $this->queries[] = ['type' => 'execute', 'sql' => $sql, 'params' => $parameters];
+        $this->queries[] = ['type' => 'execute', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
 
-        if ($this->shouldFail && strpos($sql, 'INSERT INTO') !== false) {
+        if ($this->shouldFail && strpos($query->sql, 'INSERT INTO') !== false) {
             throw new DatabaseException('Simulated database failure');
         }
 
         return 1;
     }
 
-    public function query(string $sql, array $parameters = []): ResultInterface
+    public function query(SqlQuery $query): ResultInterface
     {
-        $this->queries[] = ['type' => 'query', 'sql' => $sql, 'params' => $parameters];
+        $this->queries[] = ['type' => 'query', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
 
         return new TestResult($this->appliedMigrations);
     }
 
-    public function queryOne(string $sql, array $parameters = []): ?array
+    public function queryOne(SqlQuery $query): ?array
     {
         return null;
     }
 
-    public function queryColumn(string $sql, array $parameters = []): array
+    public function queryColumn(SqlQuery $query): array
     {
-        $this->queries[] = ['type' => 'queryColumn', 'sql' => $sql, 'params' => $parameters];
+        $this->queries[] = ['type' => 'queryColumn', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
 
         // Return the versions from applied migrations
         return array_column($this->appliedMigrations, 'version');
     }
 
-    public function queryScalar(string $sql, array $parameters = []): mixed
+    public function queryScalar(SqlQuery $query): mixed
     {
         return null;
     }

tests/Framework/Database/ValueObjects/QueryParametersTest.php

@@ -0,0 +1,162 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Database\ValueObjects;
+
+use App\Framework\Database\ValueObjects\QueryParameters;
+use InvalidArgumentException;
+
+describe('QueryParameters Value Object', function () {
+    it('can be created empty', function () {
+        $params = QueryParameters::empty();
+        expect($params->isEmpty())->toBeTrue();
+        expect($params->count())->toBe(0);
+        expect($params->toArray())->toBe([]);
+    });
+
+    it('can be created from array', function () {
+        $data = ['id' => 123, 'name' => 'John'];
+        $params = QueryParameters::fromArray($data);
+
+        expect($params->isEmpty())->toBeFalse();
+        expect($params->count())->toBe(2);
+        expect($params->get('id'))->toBe(123);
+        expect($params->get('name'))->toBe('John');
+    });
+
+    it('can add parameters immutably', function () {
+        $params = QueryParameters::empty();
+        $newParams = $params->with('id', 123);
+
+        expect($params->has('id'))->toBeFalse(); // Original unchanged
+        expect($newParams->has('id'))->toBeTrue();
+        expect($newParams->get('id'))->toBe(123);
+    });
+
+    it('can merge parameters', function () {
+        $params1 = QueryParameters::fromArray(['id' => 123]);
+        $params2 = $params1->merge(['name' => 'John', 'active' => true]);
+
+        expect($params1->count())->toBe(1); // Original unchanged
+        expect($params2->count())->toBe(3);
+        expect($params2->get('id'))->toBe(123);
+        expect($params2->get('name'))->toBe('John');
+        expect($params2->get('active'))->toBeTrue();
+    });
+
+    it('can remove parameters immutably', function () {
+        $params = QueryParameters::fromArray(['id' => 123, 'name' => 'John']);
+        $newParams = $params->without('name');
+
+        expect($params->has('name'))->toBeTrue(); // Original unchanged
+        expect($newParams->has('name'))->toBeFalse();
+        expect($newParams->has('id'))->toBeTrue();
+    });
+
+    it('gets parameters with defaults', function () {
+        $params = QueryParameters::fromArray(['id' => 123]);
+
+        expect($params->get('id'))->toBe(123);
+        expect($params->get('missing'))->toBeNull();
+        expect($params->get('missing', 'default'))->toBe('default');
+    });
+
+    it('normalizes parameter names', function () {
+        $params = QueryParameters::fromArray([':id' => 123, 'name' => 'John']);
+
+        expect($params->has('id'))->toBeTrue();
+        expect($params->has(':id'))->toBeTrue(); // Both work
+        expect($params->get('id'))->toBe(123);
+        expect($params->get(':id'))->toBe(123);
+    });
+
+    it('converts to PDO array with colon prefixes', function () {
+        $params = QueryParameters::fromArray(['id' => 123, ':name' => 'John']);
+        $pdoArray = $params->toPdoArray();
+
+        expect($pdoArray)->toBe([':id' => 123, ':name' => 'John']);
+    });
+
+    it('finds used parameters in SQL', function () {
+        $params = QueryParameters::fromArray(['id' => 123, 'name' => 'John', 'unused' => 'test']);
+        $sql = 'SELECT * FROM users WHERE id = :id AND name = :name';
+
+        $used = $params->getUsedParameters($sql);
+        expect($used)->toBe(['id', 'name']);
+    });
+
+    it('finds unused parameters', function () {
+        $params = QueryParameters::fromArray(['id' => 123, 'name' => 'John', 'unused' => 'test']);
+        $sql = 'SELECT * FROM users WHERE id = :id';
+
+        $unused = $params->getUnusedParameters($sql);
+        expect($unused)->toBe(['name', 'unused']);
+    });
+
+    it('validates SQL parameter requirements', function () {
+        $params = QueryParameters::fromArray(['id' => 123]);
+        $sql = 'SELECT * FROM users WHERE id = :id AND name = :name';
+
+        expect(fn () => $params->validateForSql($sql))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('validates SQL parameter requirements successfully', function () {
+        $params = QueryParameters::fromArray(['id' => 123, 'name' => 'John']);
+        $sql = 'SELECT * FROM users WHERE id = :id AND name = :name';
+
+        expect(fn () => $params->validateForSql($sql))->not->toThrow(InvalidArgumentException::class);
+    });
+
+    it('determines PDO parameter types', function () {
+        $params = QueryParameters::fromArray([
+            'null_val' => null,
+            'bool_val' => true,
+            'int_val' => 123,
+            'string_val' => 'text',
+        ]);
+
+        expect($params->getPdoType('null_val'))->toBe(\PDO::PARAM_NULL);
+        expect($params->getPdoType('bool_val'))->toBe(\PDO::PARAM_BOOL);
+        expect($params->getPdoType('int_val'))->toBe(\PDO::PARAM_INT);
+        expect($params->getPdoType('string_val'))->toBe(\PDO::PARAM_STR);
+    });
+
+    it('throws exception for non-string parameter names', function () {
+        expect(fn () => QueryParameters::fromArray([123 => 'value']))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for empty parameter names', function () {
+        expect(fn () => QueryParameters::fromArray(['' => 'value']))->toThrow(InvalidArgumentException::class);
+        expect(fn () => QueryParameters::fromArray([':' => 'value']))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for invalid parameter names', function () {
+        expect(fn () => QueryParameters::fromArray(['1invalid' => 'value']))->toThrow(InvalidArgumentException::class);
+        expect(fn () => QueryParameters::fromArray(['invalid-name' => 'value']))->toThrow(InvalidArgumentException::class);
+        expect(fn () => QueryParameters::fromArray(['invalid name' => 'value']))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('allows valid parameter names', function () {
+        expect(fn () => QueryParameters::fromArray(['valid' => 'value']))->not->toThrow(InvalidArgumentException::class);
+        expect(fn () => QueryParameters::fromArray(['valid_name' => 'value']))->not->toThrow(InvalidArgumentException::class);
+        expect(fn () => QueryParameters::fromArray(['valid123' => 'value']))->not->toThrow(InvalidArgumentException::class);
+        expect(fn () => QueryParameters::fromArray(['_valid' => 'value']))->not->toThrow(InvalidArgumentException::class);
+        expect(fn () => QueryParameters::fromArray([':valid' => 'value']))->not->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for non-scalar parameter values', function () {
+        expect(fn () => QueryParameters::fromArray(['array' => [1, 2, 3]]))->toThrow(InvalidArgumentException::class);
+        expect(fn () => QueryParameters::fromArray(['object' => new \stdClass()]))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('allows scalar and null parameter values', function () {
+        expect(fn () => QueryParameters::fromArray([
+            'string' => 'text',
+            'int' => 123,
+            'float' => 12.34,
+            'bool' => true,
+            'null' => null,
+        ]))->not->toThrow(InvalidArgumentException::class);
+    });
+});

tests/Framework/Database/ValueObjects/SqlQueryTest.php

@@ -0,0 +1,128 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Database\ValueObjects;
+
+use App\Framework\Database\ValueObjects\QueryParameters;
+use App\Framework\Database\ValueObjects\SqlQuery;
+use InvalidArgumentException;
+
+describe('SqlQuery Value Object', function () {
+    it('can be created with SQL and parameters', function () {
+        $params = QueryParameters::fromArray(['id' => 123]);
+        $query = new SqlQuery('SELECT * FROM users WHERE id = :id', $params);
+
+        expect($query->sql)->toBe('SELECT * FROM users WHERE id = :id');
+        expect($query->parameters->get('id'))->toBe(123);
+    });
+
+    it('can be created with create factory method', function () {
+        $query = SqlQuery::create('SELECT * FROM users', ['limit' => 10]);
+
+        expect($query->sql)->toBe('SELECT * FROM users');
+        expect($query->parameters->get('limit'))->toBe(10);
+    });
+
+    it('can create SELECT queries', function () {
+        $query = SqlQuery::select('users', ['id', 'name'], 'active = 1');
+
+        expect($query->sql)->toBe('SELECT id, name FROM users WHERE active = 1');
+        expect($query->isSelect())->toBeTrue();
+    });
+
+    it('can create INSERT queries', function () {
+        $query = SqlQuery::insert('users', ['name' => 'John', 'email' => 'john@test.com']);
+
+        expect($query->sql)->toBe('INSERT INTO users (name, email) VALUES (:name, :email)');
+        expect($query->parameters->get('name'))->toBe('John');
+        expect($query->parameters->get('email'))->toBe('john@test.com');
+        expect($query->isInsert())->toBeTrue();
+    });
+
+    it('can create UPDATE queries', function () {
+        $query = SqlQuery::update('users', ['name' => 'Jane'], 'id = :id');
+
+        expect($query->sql)->toBe('UPDATE users SET name = :name WHERE id = :id');
+        expect($query->parameters->get('name'))->toBe('Jane');
+        expect($query->isUpdate())->toBeTrue();
+    });
+
+    it('can create DELETE queries', function () {
+        $query = SqlQuery::delete('users', 'id = :id');
+
+        expect($query->sql)->toBe('DELETE FROM users WHERE id = :id');
+        expect($query->isDelete())->toBeTrue();
+    });
+
+    it('can add parameters immutably', function () {
+        $query = SqlQuery::create('SELECT * FROM users WHERE id = :id');
+        $newQuery = $query->withParameter('id', 123);
+
+        expect($query->parameters->has('id'))->toBeFalse(); // Original unchanged
+        expect($newQuery->parameters->get('id'))->toBe(123);
+    });
+
+    it('can add multiple parameters', function () {
+        $query = SqlQuery::create('SELECT * FROM users');
+        $newQuery = $query->withParameters(['limit' => 10, 'offset' => 20]);
+
+        expect($newQuery->parameters->get('limit'))->toBe(10);
+        expect($newQuery->parameters->get('offset'))->toBe(20);
+    });
+
+    it('detects query types correctly', function () {
+        expect(SqlQuery::create('SELECT * FROM users')->isSelect())->toBeTrue();
+        expect(SqlQuery::create('INSERT INTO users VALUES (1)')->isInsert())->toBeTrue();
+        expect(SqlQuery::create('UPDATE users SET name = "test"')->isUpdate())->toBeTrue();
+        expect(SqlQuery::create('DELETE FROM users')->isDelete())->toBeTrue();
+        expect(SqlQuery::create('CREATE TABLE test (id INT)')->isDDL())->toBeTrue();
+        expect(SqlQuery::create('ALTER TABLE test ADD column')->isDDL())->toBeTrue();
+        expect(SqlQuery::create('DROP TABLE test')->isDDL())->toBeTrue();
+    });
+
+    it('detects modifying queries', function () {
+        expect(SqlQuery::create('SELECT * FROM users')->isModifying())->toBeFalse();
+        expect(SqlQuery::create('INSERT INTO users VALUES (1)')->isModifying())->toBeTrue();
+        expect(SqlQuery::create('UPDATE users SET name = "test"')->isModifying())->toBeTrue();
+        expect(SqlQuery::create('DELETE FROM users')->isModifying())->toBeTrue();
+        expect(SqlQuery::create('CREATE TABLE test (id INT)')->isModifying())->toBeTrue();
+    });
+
+    it('generates debug string correctly', function () {
+        $query = SqlQuery::create('SELECT * FROM users WHERE id = :id AND name = :name', [
+            'id' => 123,
+            'name' => 'John',
+        ]);
+
+        $debug = $query->toDebugString();
+        expect($debug)->toContain('123');
+        expect($debug)->toContain("'John'");
+        expect($debug)->not->toContain(':id');
+        expect($debug)->not->toContain(':name');
+    });
+
+    it('converts to string', function () {
+        $query = SqlQuery::create('SELECT * FROM users');
+        expect($query->toString())->toBe('SELECT * FROM users');
+        expect($query->__toString())->toBe('SELECT * FROM users');
+    });
+
+    it('throws exception for empty SQL', function () {
+        expect(fn () => new SqlQuery(''))->toThrow(InvalidArgumentException::class);
+        expect(fn () => new SqlQuery('   '))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for too large SQL', function () {
+        $largeSql = str_repeat('SELECT * FROM users; ', 100000); // > 1MB
+        expect(fn () => new SqlQuery($largeSql))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for empty insert data', function () {
+        expect(fn () => SqlQuery::insert('users', []))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for empty update data', function () {
+        expect(fn () => SqlQuery::update('users', [], 'id = 1'))->toThrow(InvalidArgumentException::class);
+    });
+});

tests/Framework/Discovery/DiscoveryServiceIntegrationTest.php

@@ -29,7 +29,9 @@ describe('DiscoveryService Integration with Console Commands', function () {
         $serializer = new PhpSerializer(PhpSerializerConfig::safe());
         $this->cache = new GeneralCache($cacheDriver, $serializer);
         $this->clock = new SystemClock();
-        $this->pathProvider = new PathProvider('/home/michael/dev/michaelschiemer');
+        // Use correct base path for Docker environment
+        $basePath = file_exists('/var/www/html/src') ? '/var/www/html' : '/home/michael/dev/michaelschiemer';
+        $this->pathProvider = new PathProvider($basePath);
 
         // Register dependencies in container
         $this->container->singleton(Cache::class, $this->cache);
@@ -228,7 +230,9 @@ describe('DiscoveryService Performance and Error Handling', function () {
         $serializer = new PhpSerializer(PhpSerializerConfig::safe());
         $this->cache = new GeneralCache($cacheDriver, $serializer);
         $this->clock = new SystemClock();
-        $this->pathProvider = new PathProvider('/home/michael/dev/michaelschiemer');
+        // Use correct base path for Docker environment
+        $basePath = file_exists('/var/www/html/src') ? '/var/www/html' : '/home/michael/dev/michaelschiemer';
+        $this->pathProvider = new PathProvider($basePath);
 
         $this->container->singleton(Cache::class, $this->cache);
         $this->container->singleton(Clock::class, $this->clock);

tests/Framework/Discovery/Processing/ClassExtractorTest.php

@@ -0,0 +1,198 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Discovery\Processing\ClassExtractor;
+use App\Framework\Filesystem\File;
+use App\Framework\Filesystem\FilePath;
+use App\Framework\Filesystem\FileSystemService;
+
+beforeEach(function () {
+    $this->fileSystem = new FileSystemService();
+    $this->extractor = new ClassExtractor($this->fileSystem);
+    $this->tmpDir = '/var/www/html/tests/tmp';
+
+    if (!is_dir($this->tmpDir)) {
+        mkdir($this->tmpDir, 0777, true);
+    }
+
+    $this->createTestFile = function (string $filename, string $content): File {
+        $filepath = $this->tmpDir . '/' . $filename;
+        file_put_contents($filepath, $content);
+
+        $spl = new SplFileInfo($filepath);
+        return File::fromSplFileInfo($spl);
+    };
+});
+
+afterEach(function () {
+    // Clean up test files
+    if (is_dir($this->tmpDir)) {
+        $files = glob($this->tmpDir . '/*');
+        foreach ($files as $file) {
+            if (is_file($file)) {
+                unlink($file);
+            }
+        }
+    }
+});
+
+describe('ClassExtractor', function () {
+    it('extracts classes from PHP file', function () {
+        $content = <<<'PHP'
+<?php
+
+namespace App\Test;
+
+final readonly class TestClass
+{
+    public function test(): void {}
+}
+PHP;
+
+        $file = ($this->createTestFile)('TestClass.php', $content);
+        $classes = $this->extractor->extractFromFile($file);
+
+        expect($classes)->toHaveCount(1);
+        expect($classes[0]->getFullyQualified())->toBe('App\Test\TestClass');
+    });
+
+    it('returns empty array for HTML template files without PHP tags', function () {
+        $content = <<<'HTML'
+<layout name="layouts/main" />
+
+<div class="section">
+    <h2>Dashboard</h2>
+    <div class="stats-grid">
+        <div class="stat-card">
+            <h3>Status</h3>
+        </div>
+    </div>
+</div>
+HTML;
+
+        $file = ($this->createTestFile)('template.view.php', $content);
+        $classes = $this->extractor->extractFromFile($file);
+
+        expect($classes)->toHaveCount(0);
+    });
+
+    it('extracts multiple classes from file', function () {
+        $content = <<<'PHP'
+<?php
+
+namespace App\Test;
+
+interface TestInterface {}
+
+final readonly class TestClass implements TestInterface {}
+
+trait TestTrait {}
+
+enum TestEnum {
+    case CASE_ONE;
+}
+PHP;
+
+        $file = ($this->createTestFile)('Multiple.php', $content);
+        $classes = $this->extractor->extractFromFile($file);
+
+        expect($classes)->toHaveCount(4);
+    });
+
+    it('handles files with short PHP tags', function () {
+        $content = <<<'PHP'
+<?= "test" ?>
+<?php
+
+class ShortTagTest {}
+PHP;
+
+        $file = ($this->createTestFile)('ShortTag.php', $content);
+        $classes = $this->extractor->extractFromFile($file);
+
+        expect($classes)->toHaveCount(1);
+    });
+
+    it('extracts detailed class information', function () {
+        $content = <<<'PHP'
+<?php
+
+namespace App\Test;
+
+final readonly class DetailedClass
+{
+    public function method(): void {}
+}
+PHP;
+
+        $file = ($this->createTestFile)('Detailed.php', $content);
+        $detailed = $this->extractor->extractDetailedFromFile($file);
+
+        expect($detailed)->toHaveCount(1);
+        expect($detailed[0]['type'])->toBe('class');
+        expect($detailed[0]['name'])->toBe('DetailedClass');
+        expect($detailed[0]['namespace'])->toBe('App\Test');
+        expect($detailed[0]['fqn'])->toBe('App\Test\DetailedClass');
+    });
+
+    it('returns empty array for files with syntax errors', function () {
+        $content = <<<'PHP'
+<?php
+
+class InvalidClass {
+    // Missing closing brace
+PHP;
+
+        $file = ($this->createTestFile)('Invalid.php', $content);
+        $classes = $this->extractor->extractFromFile($file);
+
+        expect($classes)->toHaveCount(0);
+    });
+
+    it('analyzes complete file structure', function () {
+        $content = <<<'PHP'
+<?php
+
+namespace App\Test;
+
+use App\Framework\Core\Application;
+
+final readonly class AnalysisTest
+{
+    public function __construct(
+        private Application $app
+    ) {}
+}
+PHP;
+
+        $file = ($this->createTestFile)('Analysis.php', $content);
+        $analysis = $this->extractor->analyzeFile($file);
+
+        expect($analysis)->toHaveKeys(['classes', 'functions', 'attributes', 'uses']);
+        expect($analysis['classes'])->toHaveCount(1);
+        expect($analysis['uses'])->toHaveCount(1);
+    });
+
+    it('does not extract from pure HTML without PHP tags', function () {
+        $content = <<<'HTML'
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Test</title>
+</head>
+<body>
+    <div class="container">
+        <h1>Title</h1>
+    </div>
+</body>
+</html>
+HTML;
+
+        $file = ($this->createTestFile)('pure.html', $content);
+        $classes = $this->extractor->extractFromFile($file);
+
+        expect($classes)->toHaveCount(0);
+    });
+});
+

tests/Framework/Discovery/UnifiedDiscoveryServiceTest.php

@@ -0,0 +1,194 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Discovery;
+
+use App\Framework\Cache\Cache;
+use App\Framework\Cache\Driver\InMemoryCache;
+use App\Framework\Cache\GeneralCache;
+use App\Framework\Core\PathProvider;
+use App\Framework\DateTime\SystemClock;
+use App\Framework\Discovery\Results\DiscoveryRegistry;
+use App\Framework\Discovery\UnifiedDiscoveryService;
+use App\Framework\Discovery\ValueObjects\DiscoveryConfiguration;
+use App\Framework\Reflection\CachedReflectionProvider;
+use App\Framework\Serializer\Php\PhpSerializer;
+use App\Framework\Serializer\Php\PhpSerializerConfig;
+
+describe('UnifiedDiscoveryService', function () {
+    beforeEach(function () {
+        $cacheDriver = new InMemoryCache();
+        $serializer = new PhpSerializer(PhpSerializerConfig::safe());
+        $this->cache = new GeneralCache($cacheDriver, $serializer);
+        $this->clock = new SystemClock();
+        $this->pathProvider = new PathProvider('/home/michael/dev/michaelschiemer');
+        $this->reflectionProvider = new CachedReflectionProvider();
+
+        $this->configuration = new DiscoveryConfiguration(
+            paths: ['/home/michael/dev/michaelschiemer/tests/fixtures'],
+            useCache: false, // Disable cache for tests
+            enableMemoryMonitoring: false,
+            memoryLimitMB: 64,
+            maxFilesPerBatch: 100
+        );
+
+        // Clear cache between tests
+        $this->cache->clear();
+    });
+
+    it('can be instantiated with required dependencies', function () {
+        $service = new UnifiedDiscoveryService(
+            pathProvider: $this->pathProvider,
+            cache: $this->cache,
+            clock: $this->clock,
+            reflectionProvider: $this->reflectionProvider,
+            configuration: $this->configuration
+        );
+
+        expect($service)->toBeInstanceOf(UnifiedDiscoveryService::class);
+    });
+
+    it('performs discovery and returns DiscoveryRegistry', function () {
+        $service = new UnifiedDiscoveryService(
+            pathProvider: $this->pathProvider,
+            cache: $this->cache,
+            clock: $this->clock,
+            reflectionProvider: $this->reflectionProvider,
+            configuration: $this->configuration
+        );
+
+        $registry = $service->discover();
+
+        expect($registry)->toBeInstanceOf(DiscoveryRegistry::class);
+        expect($registry->attributes)->toBeInstanceOf(\App\Framework\Discovery\Results\AttributeRegistry::class);
+        expect($registry->interfaces)->toBeInstanceOf(\App\Framework\Discovery\Results\InterfaceRegistry::class);
+    });
+
+    it('handles empty scan paths gracefully', function () {
+        $emptyConfig = new DiscoveryConfiguration(
+            paths: [],
+            useCache: false,
+            enableMemoryMonitoring: false,
+            memoryLimitMB: 64,
+            maxFilesPerBatch: 100
+        );
+
+        $service = new UnifiedDiscoveryService(
+            pathProvider: $this->pathProvider,
+            cache: $this->cache,
+            clock: $this->clock,
+            reflectionProvider: $this->reflectionProvider,
+            configuration: $emptyConfig
+        );
+
+        $registry = $service->discover();
+
+        expect($registry)->toBeInstanceOf(DiscoveryRegistry::class);
+        // Empty paths should still return a valid registry, just empty
+        expect($registry->attributes->getAll())->toBeArray();
+    });
+
+    it('supports incremental discovery', function () {
+        $service = new UnifiedDiscoveryService(
+            pathProvider: $this->pathProvider,
+            cache: $this->cache,
+            clock: $this->clock,
+            reflectionProvider: $this->reflectionProvider,
+            configuration: $this->configuration
+        );
+
+        $registry = $service->incrementalDiscover();
+
+        expect($registry)->toBeInstanceOf(DiscoveryRegistry::class);
+    });
+
+    it('validates configuration on instantiation', function () {
+        $invalidConfig = new DiscoveryConfiguration(
+            paths: ['/nonexistent/path'],
+            useCache: false,
+            enableMemoryMonitoring: false,
+            memoryLimitMB: -1, // Invalid memory limit
+            maxFilesPerBatch: 0 // Invalid batch size
+        );
+
+        expect(function () {
+            new UnifiedDiscoveryService(
+                pathProvider: $this->pathProvider,
+                cache: $this->cache,
+                clock: $this->clock,
+                reflectionProvider: $this->reflectionProvider,
+                configuration: $invalidConfig
+            );
+        })->toThrow(\InvalidArgumentException::class);
+    });
+
+    it('handles memory management configuration', function () {
+        $memoryConfig = new DiscoveryConfiguration(
+            paths: ['/home/michael/dev/michaelschiemer/src'],
+            useCache: false,
+            enableMemoryMonitoring: true,
+            memoryLimitMB: 32, // 32MB limit
+            maxFilesPerBatch: 50
+        );
+
+        $service = new UnifiedDiscoveryService(
+            pathProvider: $this->pathProvider,
+            cache: $this->cache,
+            clock: $this->clock,
+            reflectionProvider: $this->reflectionProvider,
+            configuration: $memoryConfig
+        );
+
+        expect($service)->toBeInstanceOf(UnifiedDiscoveryService::class);
+
+        // Should not throw memory errors with management enabled
+        $registry = $service->discover();
+        expect($registry)->toBeInstanceOf(DiscoveryRegistry::class);
+    });
+
+    it('respects chunk size in configuration', function () {
+        $smallChunkConfig = new DiscoveryConfiguration(
+            paths: ['/home/michael/dev/michaelschiemer/tests'],
+            useCache: false,
+            enableMemoryMonitoring: false,
+            memoryLimitMB: 64,
+            maxFilesPerBatch: 5 // Very small batches
+        );
+
+        $service = new UnifiedDiscoveryService(
+            pathProvider: $this->pathProvider,
+            cache: $this->cache,
+            clock: $this->clock,
+            reflectionProvider: $this->reflectionProvider,
+            configuration: $smallChunkConfig
+        );
+
+        $registry = $service->discover();
+
+        expect($registry)->toBeInstanceOf(DiscoveryRegistry::class);
+        // Should handle small chunks without issues
+    });
+
+    it('handles file system errors gracefully', function () {
+        $invalidPathConfig = new DiscoveryConfiguration(
+            paths: ['/completely/nonexistent/path'],
+            useCache: false,
+            enableMemoryMonitoring: false,
+            memoryLimitMB: 64,
+            maxFilesPerBatch: 100
+        );
+
+        $service = new UnifiedDiscoveryService(
+            pathProvider: $this->pathProvider,
+            cache: $this->cache,
+            clock: $this->clock,
+            reflectionProvider: $this->reflectionProvider,
+            configuration: $invalidPathConfig
+        );
+
+        // Should not throw but return empty registry
+        $registry = $service->discover();
+        expect($registry)->toBeInstanceOf(DiscoveryRegistry::class);
+    });
+});

tests/Framework/Exception/FrameworkExceptionTest.php

@@ -0,0 +1,191 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Exception;
+
+use App\Framework\Exception\ErrorCode;
+use App\Framework\Exception\ExceptionContext;
+use App\Framework\Exception\FrameworkException;
+
+describe('FrameworkException', function () {
+    it('can be created with basic message and context', function () {
+        $context = ExceptionContext::empty();
+        $exception = new FrameworkException(
+            message: 'Test error',
+            context: $context
+        );
+
+        expect($exception->getMessage())->toBe('Test error');
+        expect($exception->getContext())->toBe($context);
+        expect($exception->getErrorCode())->toBeNull();
+        expect($exception->getRetryAfter())->toBeNull();
+        expect($exception->isRecoverable())->toBeFalse();
+    });
+
+    it('can be created with ErrorCode', function () {
+        $context = ExceptionContext::empty();
+        $exception = new FrameworkException(
+            message: 'Database error',
+            context: $context,
+            errorCode: ErrorCode::DB_CONNECTION_FAILED
+        );
+
+        expect($exception->getMessage())->toBe('Database error');
+        expect($exception->getErrorCode())->toBe(ErrorCode::DB_CONNECTION_FAILED);
+        expect($exception->isErrorCode(ErrorCode::DB_CONNECTION_FAILED))->toBeTrue();
+        expect($exception->isErrorCode(ErrorCode::AUTH_TOKEN_EXPIRED))->toBeFalse();
+        expect($exception->isCategory('DB'))->toBeTrue();
+        expect($exception->isCategory('AUTH'))->toBeFalse();
+    });
+
+    it('supports simple factory method', function () {
+        $exception = FrameworkException::simple('Simple error message');
+
+        expect($exception->getMessage())->toBe('Simple error message');
+        expect($exception->getErrorCode())->toBeNull();
+        expect($exception->getContext()->toArray())->toHaveKey('operation');
+    });
+
+    it('supports create factory method with ErrorCode', function () {
+        $exception = FrameworkException::create(
+            ErrorCode::VAL_BUSINESS_RULE_VIOLATION,
+            'Custom validation error'
+        );
+
+        expect($exception->getMessage())->toBe('Custom validation error');
+        expect($exception->getErrorCode())->toBe(ErrorCode::VAL_BUSINESS_RULE_VIOLATION);
+        expect($exception->isCategory('VAL'))->toBeTrue();
+    });
+
+    it('supports forOperation factory method', function () {
+        $exception = FrameworkException::forOperation(
+            operation: 'user.create',
+            component: 'UserService',
+            message: 'Failed to create user',
+            errorCode: ErrorCode::VAL_BUSINESS_RULE_VIOLATION
+        );
+
+        expect($exception->getMessage())->toBe('Failed to create user');
+        expect($exception->getErrorCode())->toBe(ErrorCode::VAL_BUSINESS_RULE_VIOLATION);
+        expect($exception->getContext()->operation)->toBe('user.create');
+        expect($exception->getContext()->component)->toBe('UserService');
+    });
+
+    it('supports fromContext factory method', function () {
+        $context = ExceptionContext::forOperation('payment.process', 'PaymentService')
+            ->withData(['amount' => 100]);
+
+        $exception = FrameworkException::fromContext(
+            message: 'Payment failed',
+            context: $context,
+            errorCode: ErrorCode::PAYMENT_GATEWAY_ERROR
+        );
+
+        expect($exception->getMessage())->toBe('Payment failed');
+        expect($exception->getContext())->toBe($context);
+        expect($exception->getData())->toBe(['amount' => 100]);
+    });
+
+    it('supports immutable transformations', function () {
+        $original = FrameworkException::simple('Original message');
+
+        $withData = $original->withData(['key' => 'value']);
+        $withOperation = $withData->withOperation('test.operation', 'TestComponent');
+        $withDebug = $withOperation->withDebug(['debug' => 'info']);
+        $withMetadata = $withDebug->withMetadata(['meta' => 'data']);
+
+        // Original should be unchanged
+        expect($original->getData())->toBe([]);
+        expect($original->getContext()->operation)->toBeNull();
+
+        // New instance should have all data
+        expect($withMetadata->getData())->toBe(['key' => 'value']);
+        expect($withMetadata->getContext()->operation)->toBe('test.operation');
+        expect($withMetadata->getContext()->component)->toBe('TestComponent');
+        expect($withMetadata->getContext()->debug)->toBe(['debug' => 'info']);
+        expect($withMetadata->getContext()->metadata)->toBe(['meta' => 'data']);
+    });
+
+    it('supports ErrorCode modifications', function () {
+        $exception = FrameworkException::simple('Test error');
+        expect($exception->getErrorCode())->toBeNull();
+
+        $withErrorCode = $exception->withErrorCode(ErrorCode::DB_QUERY_FAILED);
+        expect($withErrorCode->getErrorCode())->toBe(ErrorCode::DB_QUERY_FAILED);
+        expect($withErrorCode->isCategory('DB'))->toBeTrue();
+
+        // Original should be unchanged
+        expect($exception->getErrorCode())->toBeNull();
+    });
+
+    it('supports retry after modifications', function () {
+        $exception = FrameworkException::create(ErrorCode::HTTP_RATE_LIMIT_EXCEEDED);
+
+        $withRetry = $exception->withRetryAfter(300);
+        expect($withRetry->getRetryAfter())->toBe(300);
+        expect($withRetry->isRecoverable())->toBeTrue();
+    });
+
+    it('converts to array with all relevant data', function () {
+        $context = ExceptionContext::forOperation('test.operation', 'TestComponent')
+            ->withData(['test' => 'data'])
+            ->withDebug(['debug' => 'info']);
+
+        $exception = FrameworkException::fromContext(
+            message: 'Test exception',
+            context: $context,
+            errorCode: ErrorCode::VAL_BUSINESS_RULE_VIOLATION
+        );
+
+        $array = $exception->toArray();
+
+        expect($array)->toHaveKey('class');
+        expect($array)->toHaveKey('message');
+        expect($array)->toHaveKey('context');
+        expect($array)->toHaveKey('error_code');
+        expect($array)->toHaveKey('error_category');
+        expect($array)->toHaveKey('description');
+        expect($array)->toHaveKey('recovery_hint');
+        expect($array)->toHaveKey('is_recoverable');
+
+        expect($array['message'])->toBe('Test exception');
+        expect($array['error_code'])->toBe(ErrorCode::VAL_BUSINESS_RULE_VIOLATION->value);
+        expect($array['error_category'])->toBe('VAL');
+    });
+
+    it('handles string representation correctly', function () {
+        $exception = FrameworkException::create(
+            ErrorCode::DB_CONNECTION_FAILED,
+            'Connection failed'
+        );
+
+        $string = (string) $exception;
+
+        expect($string)->toContain('FrameworkException');
+        expect($string)->toContain('[DB001]');
+        expect($string)->toContain('Connection failed');
+        expect($string)->toMatch('/\.php:\d+$/');
+    });
+
+    it('supports chaining operations fluently', function () {
+        $exception = FrameworkException::simple('Base error')
+            ->withErrorCode(ErrorCode::VAL_BUSINESS_RULE_VIOLATION)
+            ->withOperation('user.validate', 'UserValidator')
+            ->withData(['field' => 'email', 'value' => 'invalid'])
+            ->withDebug(['rule' => 'email_format'])
+            ->withMetadata(['attempt' => 1])
+            ->withRetryAfter(60);
+
+        expect($exception->getMessage())->toBe('Base error');
+        expect($exception->getErrorCode())->toBe(ErrorCode::VAL_BUSINESS_RULE_VIOLATION);
+        expect($exception->getContext()->operation)->toBe('user.validate');
+        expect($exception->getContext()->component)->toBe('UserValidator');
+        expect($exception->getData())->toBe(['field' => 'email', 'value' => 'invalid']);
+        expect($exception->getContext()->debug)->toBe(['rule' => 'email_format']);
+        expect($exception->getContext()->metadata)->toBe(['attempt' => 1]);
+        expect($exception->getRetryAfter())->toBe(60);
+        expect($exception->isRecoverable())->toBeTrue();
+        expect($exception->isCategory('VAL'))->toBeTrue();
+    });
+});

tests/Framework/GraphQL/GraphQLSystemTest.php

@@ -0,0 +1,223 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Core\ValueObjects\EmailAddress;
+use App\Framework\DI\DefaultContainer;
+use App\Framework\GraphQL\Attributes\GraphQLField;
+use App\Framework\GraphQL\Attributes\GraphQLQuery;
+use App\Framework\GraphQL\Attributes\GraphQLType;
+use App\Framework\GraphQL\Execution\QueryExecutor;
+use App\Framework\GraphQL\Execution\QueryParser;
+use App\Framework\GraphQL\Schema\Schema;
+use App\Framework\GraphQL\Schema\SchemaBuilder;
+use App\Framework\GraphQL\Schema\TypeResolver;
+
+describe('GraphQL System', function () {
+
+    beforeEach(function () {
+        $this->container = new DefaultContainer();
+        $this->typeResolver = new TypeResolver();
+        $this->schemaBuilder = new SchemaBuilder($this->container, $this->typeResolver);
+    });
+
+    it('builds schema from GraphQL type classes', function () {
+        $schema = $this->schemaBuilder->build([TestUserType::class]);
+
+        expect($schema)->toBeInstanceOf(Schema::class);
+        $stats = $schema->getStats();
+        expect($stats['types_count'])->toBeGreaterThan(0);
+    });
+
+    it('parses simple GraphQL query', function () {
+        $parser = new QueryParser();
+
+        $query = <<<'GRAPHQL'
+        {
+            user(id: 1) {
+                id
+                name
+                email
+            }
+        }
+        GRAPHQL;
+
+        $parsed = $parser->parse($query);
+
+        expect($parsed->fields)->toHaveCount(1);
+        expect($parsed->fields[0]->name)->toBe('user');
+        expect($parsed->fields[0]->arguments)->toBe(['id' => 1]);
+        expect($parsed->fields[0]->selections)->toHaveCount(3);
+    });
+
+    it('parses query with variables', function () {
+        $parser = new QueryParser();
+
+        $query = <<<'GRAPHQL'
+        query GetUser($id: Int!) {
+            user(id: $id) {
+                id
+                name
+            }
+        }
+        GRAPHQL;
+
+        $parsed = $parser->parse($query);
+
+        expect($parsed->variables)->toHaveKey('id');
+        expect($parsed->fields[0]->arguments)->toBe(['id' => '$id']);
+    });
+
+    it('executes simple query against schema', function () {
+        // Build schema with test query
+        $schema = $this->schemaBuilder->build([
+            TestUserType::class,
+            TestUserQueries::class
+        ]);
+
+        // Register test service
+        $this->container->singleton(TestUserService::class, new TestUserService());
+
+        $executor = new QueryExecutor($schema);
+        $parser = new QueryParser();
+
+        $query = <<<'GRAPHQL'
+        {
+            user(id: 1) {
+                id
+                name
+                email
+            }
+        }
+        GRAPHQL;
+
+        $parsed = $parser->parse($query);
+        $result = $executor->execute($parsed);
+
+        expect($result->isSuccessful())->toBeTrue();
+        expect($result->data)->toHaveKey('user');
+        expect($result->data['user']['id'])->toBe(1);
+        expect($result->data['user']['name'])->toBe('Test User');
+    });
+
+    it('handles query with variables', function () {
+        $schema = $this->schemaBuilder->build([
+            TestUserType::class,
+            TestUserQueries::class
+        ]);
+
+        $this->container->singleton(TestUserService::class, new TestUserService());
+
+        $executor = new QueryExecutor($schema);
+        $parser = new QueryParser();
+
+        $query = <<<'GRAPHQL'
+        query GetUser($userId: Int!) {
+            user(id: $userId) {
+                id
+                name
+            }
+        }
+        GRAPHQL;
+
+        $parsed = $parser->parse($query);
+        $result = $executor->execute($parsed, ['userId' => 1]);
+
+        expect($result->isSuccessful())->toBeTrue();
+        expect($result->data['user']['id'])->toBe(1);
+    });
+
+    it('generates correct GraphQL SDL', function () {
+        $schema = $this->schemaBuilder->build([
+            TestUserType::class,
+            TestUserQueries::class
+        ]);
+
+        $sdl = $schema->toSDL();
+
+        expect($sdl)->toContain('type TestUser {');
+        expect($sdl)->toContain('id: Int!');
+        expect($sdl)->toContain('name: String!');
+        expect($sdl)->toContain('type Query {');
+        expect($sdl)->toContain('user(id: Int!): TestUser');
+    });
+
+    it('handles errors gracefully', function () {
+        $schema = $this->schemaBuilder->build([
+            TestUserType::class,
+            TestUserQueries::class
+        ]);
+
+        $this->container->singleton(TestUserService::class, new TestUserService());
+
+        $executor = new QueryExecutor($schema);
+        $parser = new QueryParser();
+
+        // Query non-existent field
+        $query = '{ nonExistentField }';
+        $parsed = $parser->parse($query);
+        $result = $executor->execute($parsed);
+
+        expect($result->isSuccessful())->toBeFalse();
+        expect($result->errors)->not->toBeNull();
+    });
+});
+
+// Test classes for GraphQL system
+
+#[GraphQLType(description: 'Test user type')]
+final readonly class TestUserType
+{
+    public function __construct(
+        #[GraphQLField(description: 'User ID')]
+        public int $id,
+
+        #[GraphQLField(description: 'User name')]
+        public string $name,
+
+        #[GraphQLField(description: 'User email')]
+        public string $email
+    ) {
+    }
+}
+
+#[GraphQLQuery]
+final readonly class TestUserQueries
+{
+    public function __construct(
+        private TestUserService $userService
+    ) {
+    }
+
+    #[GraphQLField(description: 'Get user by ID')]
+    public function user(int $id): TestUserType
+    {
+        return $this->userService->findById($id);
+    }
+
+    #[GraphQLField(description: 'Get all users')]
+    public function users(int $limit = 10): array
+    {
+        return $this->userService->findAll($limit);
+    }
+}
+
+final readonly class TestUserService
+{
+    public function findById(int $id): TestUserType
+    {
+        return new TestUserType(
+            id: $id,
+            name: 'Test User',
+            email: 'test@example.com'
+        );
+    }
+
+    public function findAll(int $limit): array
+    {
+        return [
+            new TestUserType(1, 'User 1', 'user1@example.com'),
+            new TestUserType(2, 'User 2', 'user2@example.com'),
+        ];
+    }
+}

tests/Framework/Health/HealthCheckResultTest.php

@@ -0,0 +1,154 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Health;
+
+use App\Framework\Health\HealthCheckResult;
+use App\Framework\Health\HealthStatus;
+use App\Framework\Health\ValueObjects\HealthDetails;
+use App\Framework\Health\ValueObjects\HealthMessage;
+use App\Framework\Health\ValueObjects\ResponseTime;
+
+describe('HealthCheckResult with Value Objects', function () {
+    it('can be created with Value Objects', function () {
+        $result = HealthCheckResult::create(
+            HealthStatus::HEALTHY,
+            HealthMessage::success('Test Service'),
+            HealthDetails::fromArray(['version' => '1.0']),
+            ResponseTime::fromMilliseconds(50)
+        );
+
+        expect($result->status)->toBe(HealthStatus::HEALTHY);
+        expect($result->message->toString())->toBe('Test Service is working correctly');
+        expect($result->details->get('version'))->toBe('1.0');
+        expect($result->responseTime->duration->toMilliseconds())->toBe(50.0);
+    });
+
+    it('creates healthy result correctly', function () {
+        $result = HealthCheckResult::healthy(
+            'Database',
+            ['host' => 'localhost', 'port' => 3306],
+            150.5
+        );
+
+        expect($result->isHealthy())->toBeTrue();
+        expect($result->status)->toBe(HealthStatus::HEALTHY);
+        expect($result->message->isSuccess())->toBeTrue();
+        expect($result->details->get('host'))->toBe('localhost');
+        expect($result->responseTime->duration->toMilliseconds())->toBeGreaterThanOrEqual(150.0);
+        expect($result->responseTime->duration->toMilliseconds())->toBeLessThanOrEqual(151.0);
+    });
+
+    it('creates warning result correctly', function () {
+        $result = HealthCheckResult::warning(
+            'Cache',
+            'High memory usage',
+            ['usage' => '85%'],
+            300.0
+        );
+
+        expect($result->isWarning())->toBeTrue();
+        expect($result->status)->toBe(HealthStatus::WARNING);
+        expect($result->message->isWarning())->toBeTrue();
+        expect($result->message->toString())->toContain('High memory usage');
+        expect($result->details->get('usage'))->toBe('85%');
+    });
+
+    it('creates unhealthy result correctly', function () {
+        $exception = new \RuntimeException('Connection refused');
+        $result = HealthCheckResult::unhealthy(
+            'API',
+            'Connection failed',
+            ['endpoint' => 'https://api.example.com'],
+            500.0,
+            $exception
+        );
+
+        expect($result->isUnhealthy())->toBeTrue();
+        expect($result->status)->toBe(HealthStatus::UNHEALTHY);
+        expect($result->message->isError())->toBeTrue();
+        expect($result->exception)->toBe($exception);
+        expect($result->details->get('endpoint'))->toBe('https://api.example.com');
+        expect($result->details->get('error_message'))->toBe('Connection refused');
+    });
+
+    it('creates timeout result correctly', function () {
+        $result = HealthCheckResult::timeout(
+            'External API',
+            5000.0,
+            ['url' => 'https://slow.api.com']
+        );
+
+        expect($result->isUnhealthy())->toBeTrue();
+        expect($result->message->toString())->toContain('timed out after 5000ms');
+        expect($result->responseTime->duration->toMilliseconds())->toBe(5000.0);
+        expect($result->responseTime->isVerySlow())->toBeTrue();
+    });
+
+    it('creates degraded result correctly', function () {
+        $result = HealthCheckResult::degraded(
+            'Queue',
+            'Processing slowly',
+            ['pending_jobs' => 1000],
+            1500.0
+        );
+
+        expect($result->isWarning())->toBeTrue();
+        expect($result->message->toString())->toContain('degraded');
+        expect($result->details->get('pending_jobs'))->toBe(1000);
+    });
+
+    it('converts to array with all information', function () {
+        $result = HealthCheckResult::healthy(
+            'Test Service',
+            ['version' => '2.0', 'environment' => 'production'],
+            75.5
+        );
+
+        $array = $result->toArray();
+
+        expect($array)->toHaveKey('status');
+        expect($array)->toHaveKey('message');
+        expect($array)->toHaveKey('message_formatted');
+        expect($array)->toHaveKey('message_type');
+        expect($array)->toHaveKey('details');
+        expect($array)->toHaveKey('response_time_ms');
+        expect($array)->toHaveKey('response_time_formatted');
+        expect($array)->toHaveKey('response_time_level');
+
+        expect($array['status'])->toBe('healthy');
+        expect($array['message_type'])->toBe('success');
+        expect($array['response_time_ms'])->toBeGreaterThanOrEqual(75.0);
+        expect($array['response_time_ms'])->toBeLessThanOrEqual(76.0);
+        expect($array['response_time_level'])->toBe('fast');
+        expect($array['details']['version'])->toBe('2.0');
+    });
+
+    it('handles null response time correctly', function () {
+        $result = HealthCheckResult::healthy('Service', []);
+
+        expect($result->responseTime)->toBeNull();
+
+        $array = $result->toArray();
+        expect($array['response_time_ms'])->toBeNull();
+        expect($array['response_time_formatted'])->toBeNull();
+        expect($array['response_time_level'])->toBeNull();
+    });
+
+    it('merges error details with provided details', function () {
+        $exception = new \Exception('Database error', 500);
+        $result = HealthCheckResult::unhealthy(
+            'Database',
+            'Query failed',
+            ['query' => 'SELECT * FROM users'],
+            100.0,
+            $exception
+        );
+
+        expect($result->details->get('query'))->toBe('SELECT * FROM users');
+        expect($result->details->get('error_type'))->toBe('Exception');
+        expect($result->details->get('error_message'))->toBe('Database error');
+        expect($result->details->get('error_code'))->toBe(500);
+    });
+});

tests/Framework/Health/ValueObjects/HealthDetailsTest.php

@@ -0,0 +1,180 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Health\ValueObjects;
+
+use App\Framework\Health\ValueObjects\HealthDetails;
+use InvalidArgumentException;
+
+describe('HealthDetails Value Object', function () {
+    it('can be created empty', function () {
+        $details = HealthDetails::empty();
+
+        expect($details->isEmpty())->toBeTrue();
+        expect($details->count())->toBe(0);
+        expect($details->toArray())->toBe([]);
+    });
+
+    it('can be created from array', function () {
+        $data = ['host' => 'localhost', 'port' => 3306];
+        $details = HealthDetails::fromArray($data);
+
+        expect($details->isEmpty())->toBeFalse();
+        expect($details->count())->toBe(2);
+        expect($details->get('host'))->toBe('localhost');
+        expect($details->get('port'))->toBe(3306);
+    });
+
+    it('can add and remove details immutably', function () {
+        $details = HealthDetails::empty();
+        $newDetails = $details->with('key', 'value');
+
+        expect($details->has('key'))->toBeFalse(); // Original unchanged
+        expect($newDetails->has('key'))->toBeTrue();
+        expect($newDetails->get('key'))->toBe('value');
+
+        $withoutKey = $newDetails->without('key');
+        expect($withoutKey->has('key'))->toBeFalse();
+        expect($newDetails->has('key'))->toBeTrue(); // Original unchanged
+    });
+
+    it('gets values with defaults', function () {
+        $details = HealthDetails::fromArray(['existing' => 'value']);
+
+        expect($details->get('existing'))->toBe('value');
+        expect($details->get('missing'))->toBeNull();
+        expect($details->get('missing', 'default'))->toBe('default');
+    });
+
+    it('creates database details correctly', function () {
+        $details = HealthDetails::forDatabase('localhost', 3306, 'testdb', 25.5, 10);
+
+        expect($details->get('host'))->toBe('localhost');
+        expect($details->get('port'))->toBe(3306);
+        expect($details->get('database'))->toBe('testdb');
+        expect($details->get('connection_time_ms'))->toBe(25.5);
+        expect($details->get('active_connections'))->toBe(10);
+    });
+
+    it('creates cache details correctly', function () {
+        $details = HealthDetails::forCache('redis', 95, 1000, '128MB');
+
+        expect($details->get('driver'))->toBe('redis');
+        expect($details->get('hit_rate_percent'))->toBe(95);
+        expect($details->get('total_keys'))->toBe(1000);
+        expect($details->get('memory_usage'))->toBe('128MB');
+    });
+
+    it('creates disk details correctly', function () {
+        $details = HealthDetails::forDisk('/var/log', '100GB', '25GB', 75.0);
+
+        expect($details->get('path'))->toBe('/var/log');
+        expect($details->get('total_space'))->toBe('100GB');
+        expect($details->get('free_space'))->toBe('25GB');
+        expect($details->get('usage_percent'))->toBe(75.0);
+    });
+
+    it('creates system details correctly', function () {
+        $details = HealthDetails::forSystem(45.2, '8GB/16GB', 1.5, '5 days');
+
+        expect($details->get('cpu_usage_percent'))->toBe(45.2);
+        expect($details->get('memory_usage'))->toBe('8GB/16GB');
+        expect($details->get('load_average'))->toBe(1.5);
+        expect($details->get('uptime'))->toBe('5 days');
+    });
+
+    it('creates API details correctly', function () {
+        $details = HealthDetails::forApi('/health', 200, 150.5, 'v1.2.3');
+
+        expect($details->get('endpoint'))->toBe('/health');
+        expect($details->get('status_code'))->toBe(200);
+        expect($details->get('response_time_ms'))->toBe(150.5);
+        expect($details->get('version'))->toBe('v1.2.3');
+    });
+
+    it('creates error details correctly', function () {
+        $exception = new \RuntimeException('Test error', 500);
+        $details = HealthDetails::forError($exception);
+
+        expect($details->get('error_type'))->toBe('RuntimeException');
+        expect($details->get('error_message'))->toBe('Test error');
+        expect($details->get('error_code'))->toBe(500);
+        expect($details->get('error_file'))->toBeString();
+        expect($details->get('error_line'))->toBeInt();
+    });
+
+    it('can merge details', function () {
+        $details1 = HealthDetails::fromArray(['key1' => 'value1']);
+        $details2 = HealthDetails::fromArray(['key2' => 'value2']);
+
+        $merged = $details1->merge($details2);
+
+        expect($merged->get('key1'))->toBe('value1');
+        expect($merged->get('key2'))->toBe('value2');
+        expect($merged->count())->toBe(2);
+    });
+
+    it('identifies sensitive keys', function () {
+        $details = HealthDetails::fromArray([
+            'username' => 'john',
+            'password' => 'secret123',
+            'api_key' => 'abc123',
+            'database_token' => 'xyz789',
+            'normal_field' => 'value',
+        ]);
+
+        $sensitiveKeys = $details->getSensitiveKeys();
+
+        expect($sensitiveKeys)->toContain('password');
+        expect($sensitiveKeys)->toContain('api_key');
+        expect($sensitiveKeys)->toContain('database_token');
+        expect($sensitiveKeys)->not->toContain('username');
+        expect($sensitiveKeys)->not->toContain('normal_field');
+    });
+
+    it('sanitizes sensitive data', function () {
+        $details = HealthDetails::fromArray([
+            'username' => 'john',
+            'password' => 'secret123',
+            'normal_field' => 'value',
+        ]);
+
+        $sanitized = $details->toSanitizedArray();
+
+        expect($sanitized['username'])->toBe('john');
+        expect($sanitized['password'])->toBe('[REDACTED]');
+        expect($sanitized['normal_field'])->toBe('value');
+    });
+
+    it('throws exception for non-string keys', function () {
+        expect(fn () => HealthDetails::fromArray([123 => 'value']))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for empty keys', function () {
+        expect(fn () => HealthDetails::fromArray(['' => 'value']))->toThrow(InvalidArgumentException::class);
+        expect(fn () => HealthDetails::fromArray(['   ' => 'value']))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for resource values', function () {
+        $resource = fopen('php://memory', 'r');
+        expect(fn () => HealthDetails::fromArray(['resource' => $resource]))->toThrow(InvalidArgumentException::class);
+        fclose($resource);
+    });
+
+    it('allows scalar and null values', function () {
+        $details = HealthDetails::fromArray([
+            'string' => 'text',
+            'int' => 123,
+            'float' => 12.34,
+            'bool' => true,
+            'null' => null,
+        ]);
+
+        expect($details->get('string'))->toBe('text');
+        expect($details->get('int'))->toBe(123);
+        expect($details->get('float'))->toBe(12.34);
+        expect($details->get('bool'))->toBeTrue();
+        expect($details->get('null'))->toBeNull();
+    });
+});

tests/Framework/Health/ValueObjects/HealthMessageTest.php

@@ -0,0 +1,128 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Health\ValueObjects;
+
+use App\Framework\Health\ValueObjects\HealthMessage;
+use App\Framework\Health\ValueObjects\HealthMessageType;
+use InvalidArgumentException;
+
+describe('HealthMessage Value Object', function () {
+    it('can be created with message and type', function () {
+        $message = new HealthMessage('Database connection successful', HealthMessageType::SUCCESS);
+
+        expect($message->message)->toBe('Database connection successful');
+        expect($message->type)->toBe(HealthMessageType::SUCCESS);
+    });
+
+    it('can be created with plain message', function () {
+        $message = HealthMessage::plain('Simple message');
+
+        expect($message->message)->toBe('Simple message');
+        expect($message->type)->toBe(HealthMessageType::PLAIN);
+    });
+
+    it('can create success messages', function () {
+        $message = HealthMessage::success('Database');
+
+        expect($message->message)->toBe('Database is working correctly');
+        expect($message->type)->toBe(HealthMessageType::SUCCESS);
+        expect($message->isSuccess())->toBeTrue();
+    });
+
+    it('can create warning messages', function () {
+        $message = HealthMessage::warning('Cache', 'High memory usage');
+
+        expect($message->message)->toBe('Cache has issues: High memory usage');
+        expect($message->type)->toBe(HealthMessageType::WARNING);
+        expect($message->isWarning())->toBeTrue();
+    });
+
+    it('can create failure messages', function () {
+        $message = HealthMessage::failure('API', 'Connection refused');
+
+        expect($message->message)->toBe('API failed: Connection refused');
+        expect($message->type)->toBe(HealthMessageType::FAILURE);
+        expect($message->isError())->toBeTrue();
+    });
+
+    it('can create timeout messages', function () {
+        $message = HealthMessage::timeout('Service', 5000.0);
+
+        expect($message->message)->toBe('Service timed out after 5000ms');
+        expect($message->type)->toBe(HealthMessageType::TIMEOUT);
+        expect($message->isError())->toBeTrue();
+    });
+
+    it('can create degraded messages', function () {
+        $message = HealthMessage::degraded('Queue', 'Processing slowly');
+
+        expect($message->message)->toBe('Queue is degraded: Processing slowly');
+        expect($message->type)->toBe(HealthMessageType::DEGRADED);
+        expect($message->isWarning())->toBeTrue();
+    });
+
+    it('formats messages with emoji correctly', function () {
+        $success = HealthMessage::success('Test');
+        $warning = HealthMessage::warning('Test', 'Issue');
+        $failure = HealthMessage::failure('Test', 'Error');
+
+        expect($success->toFormattedString())->toBe('✓ Test is working correctly');
+        expect($warning->toFormattedString())->toBe('⚠ Test has issues: Issue');
+        expect($failure->toFormattedString())->toBe('✗ Test failed: Error');
+    });
+
+    it('can add prefix and suffix', function () {
+        $message = HealthMessage::success('Database');
+
+        $withPrefix = $message->withPrefix('MySQL');
+        expect($withPrefix->message)->toBe('MySQL: Database is working correctly');
+        expect($withPrefix->type)->toBe(HealthMessageType::SUCCESS);
+
+        $withSuffix = $message->withSuffix('port 3306');
+        expect($withSuffix->message)->toBe('Database is working correctly - port 3306');
+    });
+
+    it('can change type', function () {
+        $message = HealthMessage::plain('Database status');
+        $warningMessage = $message->withType(HealthMessageType::WARNING);
+
+        expect($warningMessage->message)->toBe('Database status');
+        expect($warningMessage->type)->toBe(HealthMessageType::WARNING);
+        expect($warningMessage->isWarning())->toBeTrue();
+    });
+
+    it('converts to array correctly', function () {
+        $message = HealthMessage::success('Test service');
+        $array = $message->toArray();
+
+        expect($array)->toHaveKey('message');
+        expect($array)->toHaveKey('type');
+        expect($array)->toHaveKey('formatted');
+        expect($array)->toHaveKey('severity');
+        expect($array)->toHaveKey('emoji');
+
+        expect($array['message'])->toBe('Test service is working correctly');
+        expect($array['type'])->toBe('success');
+        expect($array['severity'])->toBe(0);
+        expect($array['emoji'])->toBe('✓');
+    });
+
+    it('throws exception for empty message', function () {
+        expect(fn () => new HealthMessage(''))->toThrow(InvalidArgumentException::class);
+        expect(fn () => new HealthMessage('   '))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for too long message', function () {
+        $longMessage = str_repeat('a', 501);
+        expect(fn () => new HealthMessage($longMessage))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('converts to string correctly', function () {
+        $message = HealthMessage::success('Test');
+
+        expect($message->toString())->toBe('Test is working correctly');
+        expect((string) $message)->toBe('Test is working correctly');
+    });
+});

tests/Framework/Health/ValueObjects/ResponseTimeTest.php

@@ -0,0 +1,143 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Health\ValueObjects;
+
+use App\Framework\Core\ValueObjects\Duration;
+use App\Framework\Health\ValueObjects\ResponseTime;
+use App\Framework\Health\ValueObjects\ResponseTimeLevel;
+use InvalidArgumentException;
+
+describe('ResponseTime Value Object', function () {
+    it('can be created from Duration', function () {
+        $duration = Duration::fromMilliseconds(150);
+        $responseTime = ResponseTime::fromDuration($duration);
+
+        expect($responseTime->duration->toMilliseconds())->toBe(150.0);
+    });
+
+    it('can be created from seconds', function () {
+        $responseTime = ResponseTime::fromSeconds(0.5);
+
+        expect($responseTime->duration->toSeconds())->toBe(0.5);
+        expect($responseTime->duration->toMilliseconds())->toBe(500.0);
+    });
+
+    it('can be created from milliseconds', function () {
+        $responseTime = ResponseTime::fromMilliseconds(250);
+
+        expect($responseTime->duration->toMilliseconds())->toBe(250.0);
+    });
+
+    it('can measure execution time', function () {
+        $responseTime = ResponseTime::measure(function () {
+            usleep(10000); // 10ms
+        });
+
+        expect($responseTime->duration->toMilliseconds())->toBeGreaterThan(5);
+        expect($responseTime->duration->toMilliseconds())->toBeLessThan(50); // Allow some variance
+    });
+
+    it('can be created from start time', function () {
+        $startTime = microtime(true);
+        usleep(5000); // 5ms
+        $responseTime = ResponseTime::fromStartTime($startTime);
+
+        expect($responseTime->duration->toMilliseconds())->toBeGreaterThan(3);
+        expect($responseTime->duration->toMilliseconds())->toBeLessThan(20);
+    });
+
+    it('creates zero response time', function () {
+        $responseTime = ResponseTime::zero();
+
+        expect($responseTime->duration->isZero())->toBeTrue();
+        expect($responseTime->duration->toMilliseconds())->toBe(0.0);
+    });
+
+    it('classifies performance levels correctly', function () {
+        $fast = ResponseTime::fromMilliseconds(50);
+        $acceptable = ResponseTime::fromMilliseconds(300);
+        $slow = ResponseTime::fromMilliseconds(1000);
+        $verySlow = ResponseTime::fromMilliseconds(3000);
+
+        expect($fast->isFast())->toBeTrue();
+        expect($fast->getPerformanceLevel())->toBe(ResponseTimeLevel::FAST);
+
+        expect($acceptable->isAcceptable())->toBeTrue();
+        expect($acceptable->getPerformanceLevel())->toBe(ResponseTimeLevel::ACCEPTABLE);
+
+        expect($slow->isSlow())->toBeTrue();
+        expect($slow->getPerformanceLevel())->toBe(ResponseTimeLevel::SLOW);
+
+        expect($verySlow->isVerySlow())->toBeTrue();
+        expect($verySlow->getPerformanceLevel())->toBe(ResponseTimeLevel::VERY_SLOW);
+    });
+
+    it('checks threshold compliance', function () {
+        $responseTime = ResponseTime::fromMilliseconds(300);
+        $threshold = Duration::fromMilliseconds(500);
+        $strictThreshold = Duration::fromMilliseconds(200);
+
+        expect($responseTime->isWithinThreshold($threshold))->toBeTrue();
+        expect($responseTime->exceedsThreshold($threshold))->toBeFalse();
+
+        expect($responseTime->isWithinThreshold($strictThreshold))->toBeFalse();
+        expect($responseTime->exceedsThreshold($strictThreshold))->toBeTrue();
+    });
+
+    it('compares response times correctly', function () {
+        $fast = ResponseTime::fromMilliseconds(100);
+        $slow = ResponseTime::fromMilliseconds(500);
+        $same = ResponseTime::fromMilliseconds(100);
+
+        expect($slow->isSlowerThan($fast))->toBeTrue();
+        expect($fast->isFasterThan($slow))->toBeTrue();
+        expect($fast->equals($same))->toBeTrue();
+        expect($fast->equals($slow))->toBeFalse();
+    });
+
+    it('formats to string correctly', function () {
+        $fast = ResponseTime::fromMilliseconds(50);
+        $slow = ResponseTime::fromSeconds(2.5);
+
+        expect($fast->toString())->toBe('50 ms');
+        expect($slow->toString())->toBe('2.5 s');
+        expect((string) $fast)->toBe('50 ms');
+    });
+
+    it('converts to array correctly', function () {
+        $responseTime = ResponseTime::fromMilliseconds(750);
+        $array = $responseTime->toArray();
+
+        expect($array)->toHaveKey('milliseconds');
+        expect($array)->toHaveKey('seconds');
+        expect($array)->toHaveKey('formatted');
+        expect($array)->toHaveKey('level');
+        expect($array)->toHaveKey('is_fast');
+        expect($array)->toHaveKey('is_acceptable');
+        expect($array)->toHaveKey('is_slow');
+        expect($array)->toHaveKey('is_very_slow');
+
+        expect($array['milliseconds'])->toBe(750.0);
+        expect($array['seconds'])->toBe(0.75);
+        expect($array['level'])->toBe('slow');
+        expect($array['is_slow'])->toBeTrue();
+        expect($array['is_fast'])->toBeFalse();
+    });
+
+    it('throws exception for excessive response time', function () {
+        $excessiveDuration = Duration::fromSeconds(400); // > 5 minutes
+
+        expect(fn () => ResponseTime::fromDuration($excessiveDuration))
+            ->toThrow(InvalidArgumentException::class);
+    });
+
+    it('allows response times up to 5 minutes', function () {
+        $maxDuration = Duration::fromSeconds(300); // exactly 5 minutes
+        $responseTime = ResponseTime::fromDuration($maxDuration);
+
+        expect($responseTime->duration->toSeconds())->toBe(300.0);
+        expect($responseTime->duration->toMilliseconds())->toBe(300000.0);
+    });
+});

tests/Framework/Http/ValueObjects/ETagTest.php

@@ -0,0 +1,246 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Http\ValueObjects;
+
+use App\Framework\Http\ValueObjects\ETag;
+
+describe('ETag Value Object', function () {
+    it('can be created with basic value', function () {
+        $etag = new ETag('abc123');
+
+        expect($etag->getValue())->toBe('abc123');
+        expect($etag->isStrong())->toBeTrue();
+        expect($etag->isWeak())->toBeFalse();
+        expect($etag->toHeaderValue())->toBe('"abc123"');
+    });
+
+    it('can be created as weak ETag', function () {
+        $etag = new ETag('abc123', true);
+
+        expect($etag->getValue())->toBe('abc123');
+        expect($etag->isWeak())->toBeTrue();
+        expect($etag->isStrong())->toBeFalse();
+        expect($etag->toHeaderValue())->toBe('W/"abc123"');
+    });
+
+    it('rejects empty values', function () {
+        expect(fn () => new ETag(''))->toThrow(\InvalidArgumentException::class);
+    });
+
+    it('supports strong factory method', function () {
+        $etag = ETag::strong('strong-value');
+
+        expect($etag->getValue())->toBe('strong-value');
+        expect($etag->isStrong())->toBeTrue();
+        expect($etag->toHeaderValue())->toBe('"strong-value"');
+    });
+
+    it('supports weak factory method', function () {
+        $etag = ETag::weak('weak-value');
+
+        expect($etag->getValue())->toBe('weak-value');
+        expect($etag->isWeak())->toBeTrue();
+        expect($etag->toHeaderValue())->toBe('W/"weak-value"');
+    });
+
+    it('can create ETag from content hash', function () {
+        $content = 'Hello, World!';
+        $expectedHash = hash('sha256', $content);
+
+        $strongETag = ETag::fromContent($content);
+        expect($strongETag->getValue())->toBe($expectedHash);
+        expect($strongETag->isStrong())->toBeTrue();
+
+        $weakETag = ETag::fromContent($content, true);
+        expect($weakETag->getValue())->toBe($expectedHash);
+        expect($weakETag->isWeak())->toBeTrue();
+    });
+
+    it('can create ETag from file', function () {
+        // Create a temporary test file
+        $tempFile = '/tmp/claude/etag_test_file.txt';
+        if (! is_dir('/tmp/claude')) {
+            mkdir('/tmp/claude', 0755, true);
+        }
+        file_put_contents($tempFile, 'Test content');
+
+        $etag = ETag::fromFile($tempFile);
+
+        expect($etag->getValue())->toBeString();
+        expect($etag->isStrong())->toBeTrue();
+
+        // Cleanup
+        unlink($tempFile);
+    });
+
+    it('throws exception for non-existent file', function () {
+        expect(fn () => ETag::fromFile('/nonexistent/file.txt'))
+            ->toThrow(\InvalidArgumentException::class);
+    });
+
+    it('can parse strong ETag from header', function () {
+        $etag = ETag::parse('"abc123"');
+
+        expect($etag->getValue())->toBe('abc123');
+        expect($etag->isStrong())->toBeTrue();
+    });
+
+    it('can parse weak ETag from header', function () {
+        $etag = ETag::parse('W/"abc123"');
+
+        expect($etag->getValue())->toBe('abc123');
+        expect($etag->isWeak())->toBeTrue();
+    });
+
+    it('can parse ETag without quotes', function () {
+        $etag = ETag::parse('abc123');
+
+        expect($etag->getValue())->toBe('abc123');
+        expect($etag->isStrong())->toBeTrue();
+    });
+
+    it('throws exception for empty header value', function () {
+        expect(fn () => ETag::parse(''))->toThrow(\InvalidArgumentException::class);
+        expect(fn () => ETag::parse('   '))->toThrow(\InvalidArgumentException::class);
+    });
+
+    it('can parse multiple ETags from header', function () {
+        $etags = ETag::parseMultiple('"abc123", W/"def456", "ghi789"');
+
+        expect($etags)->toHaveCount(3);
+        expect($etags[0])->toBeInstanceOf(ETag::class);
+        expect($etags[0]->getValue())->toBe('abc123');
+        expect($etags[0]->isStrong())->toBeTrue();
+
+        expect($etags[1]->getValue())->toBe('def456');
+        expect($etags[1]->isWeak())->toBeTrue();
+
+        expect($etags[2]->getValue())->toBe('ghi789');
+        expect($etags[2]->isStrong())->toBeTrue();
+    });
+
+    it('handles wildcard in parseMultiple', function () {
+        $etags = ETag::parseMultiple('*');
+
+        expect($etags)->toBe(['*']);
+    });
+
+    it('handles empty parseMultiple', function () {
+        $etags = ETag::parseMultiple('');
+
+        expect($etags)->toBe([]);
+    });
+
+    it('supports strong comparison matching', function () {
+        $etag1 = ETag::strong('abc123');
+        $etag2 = ETag::strong('abc123');
+        $etag3 = ETag::weak('abc123');
+        $etag4 = ETag::strong('different');
+
+        // Strong comparison requires both to be strong
+        expect($etag1->matches($etag2, true))->toBeTrue();
+        expect($etag1->matches($etag3, true))->toBeFalse(); // One is weak
+        expect($etag1->matches($etag4, true))->toBeFalse(); // Different values
+    });
+
+    it('supports weak comparison matching', function () {
+        $etag1 = ETag::strong('abc123');
+        $etag2 = ETag::weak('abc123');
+        $etag3 = ETag::strong('different');
+
+        // Weak comparison only checks values
+        expect($etag1->matches($etag2, false))->toBeTrue();
+        expect($etag1->matches($etag3, false))->toBeFalse();
+    });
+
+    it('can match against list of ETags', function () {
+        $etag = ETag::strong('abc123');
+        $etags = [
+            ETag::strong('different'),
+            ETag::weak('abc123'),
+            ETag::strong('another'),
+        ];
+
+        expect($etag->matchesAny($etags, false))->toBeTrue(); // Weak comparison
+        expect($etag->matchesAny($etags, true))->toBeFalse(); // Strong comparison (target is weak)
+
+        // Test with wildcard
+        expect($etag->matchesAny(['*'], false))->toBeTrue();
+        expect($etag->matchesAny(['*'], true))->toBeTrue();
+    });
+
+    it('supports withWeak transformation', function () {
+        $strong = ETag::strong('abc123');
+        $weak = $strong->withWeak(true);
+        $strongAgain = $weak->withWeak(false);
+
+        expect($strong->isStrong())->toBeTrue();
+        expect($weak->isWeak())->toBeTrue();
+        expect($weak->getValue())->toBe('abc123');
+        expect($strongAgain->isStrong())->toBeTrue();
+
+        // Original should be unchanged
+        expect($strong->isStrong())->toBeTrue();
+    });
+
+    it('supports equality comparison', function () {
+        $etag1 = ETag::strong('abc123');
+        $etag2 = ETag::strong('abc123');
+        $etag3 = ETag::weak('abc123');
+        $etag4 = ETag::strong('different');
+
+        expect($etag1->equals($etag2))->toBeTrue();
+        expect($etag1->equals($etag3))->toBeFalse(); // Different weak/strong
+        expect($etag1->equals($etag4))->toBeFalse(); // Different value
+    });
+
+    it('supports string conversion', function () {
+        $strong = ETag::strong('abc123');
+        $weak = ETag::weak('def456');
+
+        expect($strong->toString())->toBe('"abc123"');
+        expect($weak->toString())->toBe('W/"def456"');
+        expect((string) $strong)->toBe('"abc123"');
+        expect((string) $weak)->toBe('W/"def456"');
+    });
+
+    it('handles same file consistently', function () {
+        // Create test file
+        $tempFile = '/tmp/claude/etag_consistency_test.txt';
+        if (! is_dir('/tmp/claude')) {
+            mkdir('/tmp/claude', 0755, true);
+        }
+        file_put_contents($tempFile, 'Consistent content');
+
+        $etag1 = ETag::fromFile($tempFile);
+        $etag2 = ETag::fromFile($tempFile);
+
+        expect($etag1->equals($etag2))->toBeTrue();
+
+        // Cleanup
+        unlink($tempFile);
+    });
+
+    it('handles content changes in file', function () {
+        // Create test file
+        $tempFile = '/tmp/claude/etag_change_test.txt';
+        if (! is_dir('/tmp/claude')) {
+            mkdir('/tmp/claude', 0755, true);
+        }
+
+        file_put_contents($tempFile, 'Original content');
+        $etag1 = ETag::fromFile($tempFile);
+
+        // Wait a moment and change content
+        sleep(1);
+        file_put_contents($tempFile, 'Modified content');
+        $etag2 = ETag::fromFile($tempFile);
+
+        expect($etag1->equals($etag2))->toBeFalse();
+
+        // Cleanup
+        unlink($tempFile);
+    });
+});

tests/Framework/Logging/DefaultLoggerTest.php

@@ -0,0 +1,293 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Logging;
+
+use App\Framework\Logging\DefaultLogger;
+use App\Framework\Logging\LogHandler;
+use App\Framework\Logging\LogLevel;
+use App\Framework\Logging\LogRecord;
+use App\Framework\Logging\ProcessorManager;
+use App\Framework\Logging\ValueObjects\LogContext;
+use App\Framework\Logging\ValueObjects\RequestContext;
+use App\Framework\Logging\ValueObjects\UserContext;
+use App\Framework\Random\SecureRandomGenerator;
+use App\Framework\Tracing\TraceContext;
+
+describe('DefaultLogger', function () {
+    beforeEach(function () {
+        // Clear any existing trace context
+        TraceContext::clear();
+    });
+
+    afterEach(function () {
+        TraceContext::clear();
+    });
+
+    it('can log with array context (legacy)', function () {
+        $handler = new TestLogHandler();
+        $logger = new DefaultLogger(
+            minLevel: LogLevel::DEBUG,
+            handlers: [$handler]
+        );
+
+        $context = ['user_id' => 123, 'action' => 'login'];
+        $logger->info('User logged in', $context);
+
+        expect($handler->records)->toHaveCount(1);
+        $record = $handler->records[0];
+
+        expect($record->getMessage())->toBe('User logged in');
+        expect($record->getContext())->toBe($context);
+        expect($record->getLevel())->toBe(LogLevel::INFO);
+    });
+
+    it('can log with LogContext', function () {
+        $handler = new TestLogHandler();
+        $logger = new DefaultLogger(
+            minLevel: LogLevel::DEBUG,
+            handlers: [$handler]
+        );
+
+        $logContext = LogContext::withData(['user_id' => 123, 'action' => 'login'])
+            ->addTags('authentication', 'user-action')
+            ->addMetadata('source', 'test');
+
+        $logger->info('User logged in', $logContext);
+
+        expect($handler->records)->toHaveCount(1);
+        $record = $handler->records[0];
+
+        expect($record->getMessage())->toBe('User logged in');
+        expect($record->getLevel())->toBe(LogLevel::INFO);
+
+        // Context should be converted to array
+        $context = $record->getContext();
+        expect($context)->toHaveKey('user_id', 123);
+        expect($context)->toHaveKey('action', 'login');
+        expect($context)->toHaveKey('_tags', ['authentication', 'user-action']);
+        expect($context)->toHaveKey('source', 'test');
+
+        // Structured data should be in extras
+        expect($record->getExtra('structured_tags'))->toBe(['authentication', 'user-action']);
+    });
+
+    it('converts LogContext with trace to array context', function () {
+        $handler = new TestLogHandler();
+        $logger = new DefaultLogger(
+            minLevel: LogLevel::DEBUG,
+            handlers: [$handler]
+        );
+
+        $trace = TraceContext::start(new SecureRandomGenerator());
+        $span = $trace->startSpan('test-span');
+
+        $logContext = LogContext::withData(['key' => 'value'])
+            ->withTrace($trace);
+
+        $logger->info('Test message', $logContext);
+
+        $record = $handler->records[0];
+        $context = $record->getContext();
+
+        expect($context)->toHaveKey('_trace_id', $trace->getTraceId());
+        expect($context)->toHaveKey('_span_id', $span->spanId);
+
+        // Trace should also be in extras
+        $traceExtra = $record->getExtra('trace_context');
+        expect($traceExtra)->toHaveKey('trace_id', $trace->getTraceId());
+        expect($traceExtra)->toHaveKey('active_span');
+    });
+
+    it('converts LogContext with user to array context', function () {
+        $handler = new TestLogHandler();
+        $logger = new DefaultLogger(
+            minLevel: LogLevel::DEBUG,
+            handlers: [$handler]
+        );
+
+        $userContext = UserContext::authenticated('123', 'john');
+        $logContext = LogContext::withData(['key' => 'value'])
+            ->withUser($userContext);
+
+        $logger->info('Test message', $logContext);
+
+        $record = $handler->records[0];
+        $context = $record->getContext();
+
+        expect($context)->toHaveKey('_user_id', '123');
+
+        // User should also be in extras
+        $userExtra = $record->getExtra('user_context');
+        expect($userExtra)->toBeArray();
+        expect($userExtra)->toHaveKey('user_id', '123');
+    });
+
+    it('converts LogContext with request to array context', function () {
+        $handler = new TestLogHandler();
+        $logger = new DefaultLogger(
+            minLevel: LogLevel::DEBUG,
+            handlers: [$handler]
+        );
+
+        $requestContext = RequestContext::empty();
+        $logContext = LogContext::withData(['key' => 'value'])
+            ->withRequest($requestContext);
+
+        $logger->info('Test message', $logContext);
+
+        $record = $handler->records[0];
+
+        // Request should be in extras
+        $requestExtra = $record->getExtra('request_context');
+        expect($requestExtra)->toBeArray();
+    });
+
+    it('logs at different levels with LogContext', function () {
+        $handler = new TestLogHandler();
+        $logger = new DefaultLogger(
+            minLevel: LogLevel::DEBUG,
+            handlers: [$handler]
+        );
+
+        $context = LogContext::withData(['test' => 'value']);
+
+        $logger->debug('Debug message', $context);
+        $logger->info('Info message', $context);
+        $logger->notice('Notice message', $context);
+        $logger->warning('Warning message', $context);
+        $logger->error('Error message', $context);
+        $logger->critical('Critical message', $context);
+        $logger->alert('Alert message', $context);
+        $logger->emergency('Emergency message', $context);
+
+        expect($handler->records)->toHaveCount(8);
+
+        $levels = array_map(fn ($record) => $record->getLevel(), $handler->records);
+        expect($levels)->toBe([
+            LogLevel::DEBUG,
+            LogLevel::INFO,
+            LogLevel::NOTICE,
+            LogLevel::WARNING,
+            LogLevel::ERROR,
+            LogLevel::CRITICAL,
+            LogLevel::ALERT,
+            LogLevel::EMERGENCY,
+        ]);
+    });
+
+    it('respects minimum log level', function () {
+        $handler = new TestLogHandler();
+        $logger = new DefaultLogger(
+            minLevel: LogLevel::WARNING,
+            handlers: [$handler]
+        );
+
+        $context = LogContext::withData(['test' => 'value']);
+
+        $logger->debug('Debug message', $context);
+        $logger->info('Info message', $context);
+        $logger->warning('Warning message', $context);
+        $logger->error('Error message', $context);
+
+        expect($handler->records)->toHaveCount(2);
+        expect($handler->records[0]->getLevel())->toBe(LogLevel::WARNING);
+        expect($handler->records[1]->getLevel())->toBe(LogLevel::ERROR);
+    });
+
+    it('calls processors on enriched record', function () {
+        $processor = new TestLogProcessor();
+        $processorManager = new ProcessorManager($processor);
+        $handler = new TestLogHandler();
+
+        $logger = new DefaultLogger(
+            minLevel: LogLevel::DEBUG,
+            handlers: [$handler],
+            processorManager: $processorManager
+        );
+
+        $context = LogContext::withData(['test' => 'value']);
+        $logger->info('Test message', $context);
+
+        expect($processor->processedRecords)->toHaveCount(1);
+        expect($handler->records)->toHaveCount(1);
+
+        // Processor should have seen the enriched record
+        $processedRecord = $processor->processedRecords[0];
+        expect($processedRecord->getExtra('structured_tags'))->toBeNull(); // No tags in this test
+    });
+
+    it('handles empty LogContext', function () {
+        $handler = new TestLogHandler();
+        $logger = new DefaultLogger(
+            minLevel: LogLevel::DEBUG,
+            handlers: [$handler]
+        );
+
+        $logger->info('Test message', LogContext::empty());
+
+        expect($handler->records)->toHaveCount(1);
+        $record = $handler->records[0];
+
+        expect($record->getContext())->toBe([]);
+        expect($record->getExtras())->toBe([]);
+    });
+
+    it('can get configuration', function () {
+        $handler = new TestLogHandler();
+        $processor = new TestLogProcessor();
+        $processorManager = new ProcessorManager($processor);
+
+        $logger = new DefaultLogger(
+            minLevel: LogLevel::INFO,
+            handlers: [$handler],
+            processorManager: $processorManager
+        );
+
+        $config = $logger->getConfiguration();
+
+        expect($config)->toHaveKey('minLevel', 200);
+        expect($config)->toHaveKey('handlers');
+        expect($config)->toHaveKey('processors');
+        expect($config['handlers'])->toBe([TestLogHandler::class]);
+    });
+});
+
+// Test helpers
+class TestLogHandler implements LogHandler
+{
+    public array $records = [];
+
+    public function isHandling(LogRecord $record): bool
+    {
+        return true;
+    }
+
+    public function handle(LogRecord $record): void
+    {
+        $this->records[] = $record;
+    }
+}
+
+class TestLogProcessor implements \App\Framework\Logging\LogProcessor
+{
+    public array $processedRecords = [];
+
+    public function processRecord(LogRecord $record): LogRecord
+    {
+        $this->processedRecords[] = $record;
+
+        return $record->addExtra('processed_by', 'TestLogProcessor');
+    }
+
+    public function getPriority(): int
+    {
+        return 100;
+    }
+
+    public function getName(): string
+    {
+        return 'test-processor';
+    }
+}

tests/Framework/Logging/LogContextManagerTest.php

@@ -0,0 +1,312 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Logging;
+
+use App\Framework\Logging\LogContextManager;
+use App\Framework\Logging\ValueObjects\LogContext;
+use App\Framework\Logging\ValueObjects\RequestContext;
+use App\Framework\Logging\ValueObjects\UserContext;
+use App\Framework\Random\SecureRandomGenerator;
+use App\Framework\Tracing\TraceContext;
+
+describe('LogContextManager', function () {
+    beforeEach(function () {
+        // Create fresh instance for each test
+        $this->contextManager = new LogContextManager();
+        TraceContext::clear();
+    });
+
+    afterEach(function () {
+        // Clean up after each test
+        TraceContext::clear();
+    });
+
+    it('starts with empty context', function () {
+        $context = $this->contextManager->getCurrentContext();
+
+        expect($context->structured)->toBe([]);
+        expect($context->tags)->toBe([]);
+        expect($context->trace)->toBeNull();
+        expect($context->user)->toBeNull();
+        expect($context->request)->toBeNull();
+    });
+
+    it('can set and get global context', function () {
+        $globalContext = LogContext::withData(['app' => 'test'])
+            ->addTags('global');
+
+        $this->contextManager->setGlobalContext($globalContext);
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->structured)->toBe(['app' => 'test']);
+        expect($current->tags)->toBe(['global']);
+    });
+
+    it('can set and get request context', function () {
+        $requestContext = LogContext::withData(['request' => 'test'])
+            ->addTags('request');
+
+        $this->contextManager->setRequestContext($requestContext);
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->structured)->toBe(['request' => 'test']);
+        expect($current->tags)->toBe(['request']);
+    });
+
+    it('merges global and request contexts', function () {
+        $globalContext = LogContext::withData(['app' => 'test'])
+            ->addTags('global');
+
+        $requestContext = LogContext::withData(['request' => 'test'])
+            ->addTags('request');
+
+        $this->contextManager->setGlobalContext($globalContext);
+        $this->contextManager->setRequestContext($requestContext);
+
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->structured)->toBe(['app' => 'test', 'request' => 'test']);
+        expect($current->tags)->toBe(['global', 'request']);
+    });
+
+    it('can add data to global context', function () {
+        $this->contextManager->addGlobalData('key1', 'value1');
+        $this->contextManager->addGlobalData('key2', 'value2');
+
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->structured)->toBe(['key1' => 'value1', 'key2' => 'value2']);
+    });
+
+    it('can add tags to global context', function () {
+        $this->contextManager->addGlobalTags('tag1', 'tag2');
+        $this->contextManager->addGlobalTags('tag3');
+
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->tags)->toBe(['tag1', 'tag2', 'tag3']);
+    });
+
+    it('can add data to request context', function () {
+        $this->contextManager->addRequestData('req1', 'value1');
+        $this->contextManager->addRequestData('req2', 'value2');
+
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->structured)->toBe(['req1' => 'value1', 'req2' => 'value2']);
+    });
+
+    it('can add tags to request context', function () {
+        $this->contextManager->addRequestTags('reqtag1', 'reqtag2');
+        $this->contextManager->addRequestTags('reqtag3');
+
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->tags)->toBe(['reqtag1', 'reqtag2', 'reqtag3']);
+    });
+
+    it('includes current trace context automatically', function () {
+        $trace = TraceContext::start(new SecureRandomGenerator());
+
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->trace)->toBe($trace);
+    });
+
+    it('can add user context', function () {
+        $userContext = UserContext::authenticated('123', 'john');
+
+        $this->contextManager->withUser($userContext);
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->user)->toBe($userContext);
+    });
+
+    it('can add request context through manager', function () {
+        $requestContext = RequestContext::empty();
+
+        $this->contextManager->withRequest($requestContext);
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->request)->toBe($requestContext);
+    });
+
+    it('can add trace context through manager', function () {
+        $traceContext = TraceContext::start(new SecureRandomGenerator());
+
+        $this->contextManager->withTrace($traceContext);
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->trace)->toBe($traceContext);
+    });
+
+    it('can clear request context only', function () {
+        $this->contextManager->setGlobalContext(LogContext::withData(['global' => 'data']));
+        $this->contextManager->setRequestContext(LogContext::withData(['request' => 'data']));
+
+        $this->contextManager->clearRequestContext();
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->structured)->toBe(['global' => 'data']);
+    });
+
+    it('can clear global context only', function () {
+        $this->contextManager->setGlobalContext(LogContext::withData(['global' => 'data']));
+        $this->contextManager->setRequestContext(LogContext::withData(['request' => 'data']));
+
+        $this->contextManager->clearGlobalContext();
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->structured)->toBe(['request' => 'data']);
+    });
+
+    it('can clear all contexts', function () {
+        $this->contextManager->setGlobalContext(LogContext::withData(['global' => 'data']));
+        $this->contextManager->setRequestContext(LogContext::withData(['request' => 'data']));
+
+        $this->contextManager->clearContext();
+        $current = $this->contextManager->getCurrentContext();
+
+        expect($current->structured)->toBe(['global' => 'data']); // Global remains
+    });
+
+    it('can execute callback with temporary context', function () {
+        $originalData = ['original' => 'data'];
+        $this->contextManager->setRequestContext(LogContext::withData($originalData));
+
+        $temporaryContext = LogContext::withData(['temp' => 'data']);
+
+        $result = $this->contextManager->withTemporaryContext($temporaryContext, function () {
+            $current = $this->contextManager->getCurrentContext();
+
+            return $current->structured;
+        });
+
+        expect($result)->toBe(['original' => 'data', 'temp' => 'data']);
+
+        // Original context should be restored
+        $current = $this->contextManager->getCurrentContext();
+        expect($current->structured)->toBe($originalData);
+    });
+
+    it('can execute callback with temporary tags', function () {
+        $this->contextManager->setRequestContext(LogContext::withTags('original'));
+
+        $result = $this->contextManager->withTemporaryTags(['temp1', 'temp2'], function () {
+            $current = $this->contextManager->getCurrentContext();
+
+            return $current->tags;
+        });
+
+        expect($result)->toBe(['original', 'temp1', 'temp2']);
+
+        // Original context should be restored
+        $current = $this->contextManager->getCurrentContext();
+        expect($current->tags)->toBe(['original']);
+    });
+
+    it('can execute callback with temporary data', function () {
+        $this->contextManager->setRequestContext(LogContext::withData(['original' => 'value']));
+
+        $result = $this->contextManager->withTemporaryData(['temp' => 'value'], function () {
+            $current = $this->contextManager->getCurrentContext();
+
+            return $current->structured;
+        });
+
+        expect($result)->toBe(['original' => 'value', 'temp' => 'value']);
+
+        // Original context should be restored
+        $current = $this->contextManager->getCurrentContext();
+        expect($current->structured)->toBe(['original' => 'value']);
+    });
+
+    it('restores context even when callback throws exception', function () {
+        $originalContext = LogContext::withData(['original' => 'data']);
+        $this->contextManager->setRequestContext($originalContext);
+
+        $temporaryContext = LogContext::withData(['temp' => 'data']);
+
+        try {
+            $this->contextManager->withTemporaryContext($temporaryContext, function () {
+                throw new \RuntimeException('Test exception');
+            });
+        } catch (\RuntimeException $e) {
+            // Expected
+        }
+
+        // Original context should be restored
+        $current = $this->contextManager->getCurrentContext();
+        expect($current->structured)->toBe(['original' => 'data']);
+    });
+
+    it('can initialize request context from globals', function () {
+        // Mock global variables
+        $_SERVER['REQUEST_METHOD'] = 'GET';
+        $_SERVER['REQUEST_URI'] = '/test';
+        $_SERVER['HTTP_HOST'] = 'example.com';
+        $_SERVER['SERVER_NAME'] = 'example.com';
+        $_SERVER['SERVER_PORT'] = '80';
+
+        // Test direct RequestContext creation first
+        $requestContext = \App\Framework\Logging\ValueObjects\RequestContext::fromGlobals();
+        expect($requestContext)->not->toBeNull();
+        expect($requestContext->getMethod())->toBe('GET');
+
+        $context = $this->contextManager->initializeRequestContext();
+
+        expect($context->request)->not->toBeNull();
+        expect($context->request->getMethod())->toBe('GET');
+        expect($context->request->getUri())->toBe('/test');
+        expect($context->request->getHost())->toBe('example.com');
+
+        // Should be set as current request context
+        $current = $this->contextManager->getCurrentContext();
+        expect($current->request)->toBe($context->request);
+
+        // Cleanup
+        unset($_SERVER['REQUEST_METHOD'], $_SERVER['REQUEST_URI'], $_SERVER['HTTP_HOST'], $_SERVER['SERVER_NAME'], $_SERVER['SERVER_PORT']);
+    });
+
+    it('provides debug information', function () {
+        $this->contextManager->setGlobalContext(LogContext::withData(['global' => 'data']));
+        $this->contextManager->setRequestContext(LogContext::withData(['request' => 'data']));
+
+        $debug = $this->contextManager->getDebugInfo();
+
+        expect($debug)->toHaveKeys([
+            'has_global_context',
+            'has_request_context',
+            'global_context',
+            'request_context',
+            'current_trace',
+            'combined_context',
+        ]);
+
+        expect($debug['has_global_context'])->toBeTrue();
+        expect($debug['has_request_context'])->toBeTrue();
+    });
+
+    it('can check for trace context', function () {
+        expect($this->contextManager->hasTraceContext())->toBeFalse();
+
+        TraceContext::start(new SecureRandomGenerator());
+        expect($this->contextManager->hasTraceContext())->toBeTrue();
+    });
+
+    it('can check for user context', function () {
+        expect($this->contextManager->hasUserContext())->toBeFalse();
+
+        $this->contextManager->withUser(UserContext::authenticated('123'));
+        expect($this->contextManager->hasUserContext())->toBeTrue();
+    });
+
+    it('can check for request context', function () {
+        expect($this->contextManager->hasRequestContext())->toBeFalse();
+
+        $this->contextManager->withRequest(RequestContext::empty());
+        expect($this->contextManager->hasRequestContext())->toBeTrue();
+    });
+});

tests/Framework/Logging/ValueObjects/LogContextTest.php

@@ -0,0 +1,215 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Logging\ValueObjects;
+
+use App\Framework\Logging\ValueObjects\LogContext;
+use App\Framework\Logging\ValueObjects\RequestContext;
+use App\Framework\Logging\ValueObjects\UserContext;
+use App\Framework\Random\SecureRandomGenerator;
+use App\Framework\Tracing\TraceContext;
+
+describe('LogContext', function () {
+    it('can be created empty', function () {
+        $context = LogContext::empty();
+
+        expect($context->structured)->toBe([]);
+        expect($context->tags)->toBe([]);
+        expect($context->trace)->toBeNull();
+        expect($context->user)->toBeNull();
+        expect($context->request)->toBeNull();
+        expect($context->metadata)->toBe([]);
+    });
+
+    it('can be created with structured data', function () {
+        $data = ['user_id' => 123, 'action' => 'login'];
+        $context = LogContext::withData($data);
+
+        expect($context->structured)->toBe($data);
+        expect($context->hasStructuredData())->toBeTrue();
+    });
+
+    it('can be created with tags', function () {
+        $context = LogContext::withTags('auth', 'user-action');
+
+        expect($context->tags)->toBe(['auth', 'user-action']);
+        expect($context->hasTags())->toBeTrue();
+        expect($context->hasTag('auth'))->toBeTrue();
+        expect($context->hasTag('missing'))->toBeFalse();
+    });
+
+    it('can add structured data immutably', function () {
+        $original = LogContext::withData(['key1' => 'value1']);
+        $modified = $original->addData('key2', 'value2');
+
+        expect($original->structured)->toBe(['key1' => 'value1']);
+        expect($modified->structured)->toBe(['key1' => 'value1', 'key2' => 'value2']);
+    });
+
+    it('can merge structured data immutably', function () {
+        $original = LogContext::withData(['key1' => 'value1']);
+        $modified = $original->mergeData(['key2' => 'value2', 'key3' => 'value3']);
+
+        expect($original->structured)->toBe(['key1' => 'value1']);
+        expect($modified->structured)->toBe([
+            'key1' => 'value1',
+            'key2' => 'value2',
+            'key3' => 'value3',
+        ]);
+    });
+
+    it('can add tags immutably', function () {
+        $original = LogContext::withTags('tag1');
+        $modified = $original->addTags('tag2', 'tag3');
+
+        expect($original->tags)->toBe(['tag1']);
+        expect($modified->tags)->toBe(['tag1', 'tag2', 'tag3']);
+    });
+
+    it('removes duplicate tags when adding', function () {
+        $original = LogContext::withTags('tag1', 'tag2');
+        $modified = $original->addTags('tag2', 'tag3');
+
+        expect($modified->tags)->toBe(['tag1', 'tag2', 'tag3']);
+    });
+
+    it('can add user context immutably', function () {
+        $userContext = UserContext::authenticated('123', 'john');
+        $original = LogContext::empty();
+        $modified = $original->withUser($userContext);
+
+        expect($original->user)->toBeNull();
+        expect($modified->user)->toBe($userContext);
+    });
+
+    it('can add request context immutably', function () {
+        $requestContext = RequestContext::empty();
+        $original = LogContext::empty();
+        $modified = $original->withRequest($requestContext);
+
+        expect($original->request)->toBeNull();
+        expect($modified->request)->toBe($requestContext);
+    });
+
+    it('can add trace context immutably', function () {
+        $traceContext = TraceContext::start(new SecureRandomGenerator());
+        $original = LogContext::empty();
+        $modified = $original->withTrace($traceContext);
+
+        expect($original->trace)->toBeNull();
+        expect($modified->trace)->toBe($traceContext);
+    });
+
+    it('can add metadata immutably', function () {
+        $original = LogContext::empty();
+        $modified = $original->addMetadata('source', 'test');
+
+        expect($original->metadata)->toBe([]);
+        expect($modified->metadata)->toBe(['source' => 'test']);
+    });
+
+    it('can merge two contexts', function () {
+        $context1 = LogContext::withData(['key1' => 'value1'])
+            ->addTags('tag1')
+            ->addMetadata('meta1', 'value1');
+
+        $context2 = LogContext::withData(['key2' => 'value2'])
+            ->addTags('tag2')
+            ->addMetadata('meta2', 'value2');
+
+        $merged = $context1->merge($context2);
+
+        expect($merged->structured)->toBe(['key1' => 'value1', 'key2' => 'value2']);
+        expect($merged->tags)->toBe(['tag1', 'tag2']);
+        expect($merged->metadata)->toBe(['meta1' => 'value1', 'meta2' => 'value2']);
+    });
+
+    it('prioritizes second context in merge for trace, user, request', function () {
+        $user1 = UserContext::authenticated('123');
+        $user2 = UserContext::authenticated('456');
+        $request1 = RequestContext::empty();
+        $request2 = RequestContext::empty();
+        $trace1 = TraceContext::start(new SecureRandomGenerator());
+        $trace2 = TraceContext::start(new SecureRandomGenerator());
+
+        $context1 = LogContext::empty()
+            ->withUser($user1)
+            ->withRequest($request1)
+            ->withTrace($trace1);
+
+        $context2 = LogContext::empty()
+            ->withUser($user2)
+            ->withRequest($request2)
+            ->withTrace($trace2);
+
+        $merged = $context1->merge($context2);
+
+        expect($merged->user)->toBe($user2);
+        expect($merged->request)->toBe($request2);
+        expect($merged->trace)->toBe($trace2);
+    });
+
+    it('can convert to array', function () {
+        $userContext = UserContext::authenticated('123', 'john');
+        $requestContext = RequestContext::empty();
+        $traceContext = TraceContext::start(new SecureRandomGenerator());
+
+        $context = LogContext::withData(['key' => 'value'])
+            ->addTags('tag1', 'tag2')
+            ->withUser($userContext)
+            ->withRequest($requestContext)
+            ->withTrace($traceContext)
+            ->addMetadata('source', 'test');
+
+        $array = $context->toArray();
+
+        expect($array)->toHaveKeys([
+            'structured',
+            'tags',
+            'trace',
+            'user',
+            'request',
+            'metadata',
+        ]);
+
+        expect($array['structured'])->toBe(['key' => 'value']);
+        expect($array['tags'])->toBe(['tag1', 'tag2']);
+        expect($array['metadata'])->toBe(['source' => 'test']);
+    });
+
+    it('only includes non-empty sections in toArray', function () {
+        $context = LogContext::withData(['key' => 'value']);
+        $array = $context->toArray();
+
+        expect($array)->toHaveKey('structured');
+        expect($array)->not->toHaveKey('tags');
+        expect($array)->not->toHaveKey('trace');
+        expect($array)->not->toHaveKey('user');
+        expect($array)->not->toHaveKey('request');
+        expect($array)->not->toHaveKey('metadata');
+    });
+
+    it('can create context with current trace', function () {
+        // Clear any existing trace
+        TraceContext::clear();
+
+        // Start a new trace
+        $trace = TraceContext::start(new SecureRandomGenerator());
+
+        $context = LogContext::withCurrentTrace();
+
+        expect($context->trace)->toBe($trace);
+
+        // Cleanup
+        TraceContext::clear();
+    });
+
+    it('creates context with null trace when no current trace', function () {
+        TraceContext::clear();
+
+        $context = LogContext::withCurrentTrace();
+
+        expect($context->trace)->toBeNull();
+    });
+});

tests/Framework/Logging/ValueObjects/UserContextTest.php

@@ -0,0 +1,271 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Logging\ValueObjects;
+
+use App\Framework\Logging\ValueObjects\UserContext;
+
+describe('UserContext', function () {
+    it('can create authenticated user context', function () {
+        $context = UserContext::authenticated(
+            userId: '123',
+            username: 'john_doe',
+            email: 'john@example.com',
+            sessionId: 'sess_123',
+            roles: ['user', 'admin'],
+            permissions: ['read', 'write'],
+            authMethod: 'session'
+        );
+
+        expect($context->userId)->toBe('123');
+        expect($context->username)->toBe('john_doe');
+        expect($context->email)->toBe('john@example.com');
+        expect($context->sessionId)->toBe('sess_123');
+        expect($context->roles)->toBe(['user', 'admin']);
+        expect($context->permissions)->toBe(['read', 'write']);
+        expect($context->authMethod)->toBe('session');
+        expect($context->isAuthenticated)->toBeTrue();
+    });
+
+    it('can create anonymous user context', function () {
+        $context = UserContext::anonymous('sess_456');
+
+        expect($context->userId)->toBeNull();
+        expect($context->username)->toBeNull();
+        expect($context->email)->toBeNull();
+        expect($context->sessionId)->toBe('sess_456');
+        expect($context->roles)->toBe([]);
+        expect($context->permissions)->toBe([]);
+        expect($context->authMethod)->toBeNull();
+        expect($context->isAuthenticated)->toBeFalse();
+    });
+
+    it('can create from session data with user_id key', function () {
+        $sessionData = [
+            'user_id' => '123',
+            'username' => 'john',
+            'email' => 'john@example.com',
+            'roles' => ['user'],
+            'permissions' => ['read'],
+            'session_id' => 'sess_123',
+            'auth_method' => 'oauth',
+            'extra_data' => 'some_value',
+        ];
+
+        $context = UserContext::fromSession($sessionData);
+
+        expect($context->userId)->toBe('123');
+        expect($context->username)->toBe('john');
+        expect($context->email)->toBe('john@example.com');
+        expect($context->roles)->toBe(['user']);
+        expect($context->permissions)->toBe(['read']);
+        expect($context->sessionId)->toBe('sess_123');
+        expect($context->authMethod)->toBe('oauth');
+        expect($context->isAuthenticated)->toBeTrue();
+        expect($context->metadata)->toBe(['extra_data' => 'some_value']);
+    });
+
+    it('can create from session data with alternative user id keys', function () {
+        $sessionData = [
+            'id' => '456',
+            'name' => 'jane',
+        ];
+
+        $context = UserContext::fromSession($sessionData);
+
+        expect($context->userId)->toBe('456');
+        expect($context->username)->toBe('jane');
+        expect($context->isAuthenticated)->toBeTrue();
+    });
+
+    it('creates anonymous context when no user id in session', function () {
+        $sessionData = [
+            'some_other_data' => 'value',
+        ];
+
+        $context = UserContext::fromSession($sessionData);
+
+        expect($context->userId)->toBeNull();
+        expect($context->isAuthenticated)->toBeFalse();
+        expect($context->metadata)->toBe(['some_other_data' => 'value']);
+    });
+
+    it('can add role immutably', function () {
+        $original = UserContext::authenticated('123', roles: ['user']);
+        $modified = $original->withRole('admin');
+
+        expect($original->roles)->toBe(['user']);
+        expect($modified->roles)->toBe(['user', 'admin']);
+    });
+
+    it('removes duplicate roles when adding', function () {
+        $original = UserContext::authenticated('123', roles: ['user', 'admin']);
+        $modified = $original->withRole('user');
+
+        expect($modified->roles)->toBe(['user', 'admin']);
+    });
+
+    it('can add permission immutably', function () {
+        $original = UserContext::authenticated('123', permissions: ['read']);
+        $modified = $original->withPermission('write');
+
+        expect($original->permissions)->toBe(['read']);
+        expect($modified->permissions)->toBe(['read', 'write']);
+    });
+
+    it('removes duplicate permissions when adding', function () {
+        $original = UserContext::authenticated('123', permissions: ['read', 'write']);
+        $modified = $original->withPermission('read');
+
+        expect($modified->permissions)->toBe(['read', 'write']);
+    });
+
+    it('can add metadata immutably', function () {
+        $original = UserContext::authenticated('123');
+        $modified = $original->withMetadata('source', 'api');
+
+        expect($original->metadata)->toBe([]);
+        expect($modified->metadata)->toBe(['source' => 'api']);
+    });
+
+    it('can check if user has role', function () {
+        $context = UserContext::authenticated('123', roles: ['user', 'admin']);
+
+        expect($context->hasRole('user'))->toBeTrue();
+        expect($context->hasRole('admin'))->toBeTrue();
+        expect($context->hasRole('superuser'))->toBeFalse();
+    });
+
+    it('can check if user has permission', function () {
+        $context = UserContext::authenticated('123', permissions: ['read', 'write']);
+
+        expect($context->hasPermission('read'))->toBeTrue();
+        expect($context->hasPermission('write'))->toBeTrue();
+        expect($context->hasPermission('delete'))->toBeFalse();
+    });
+
+    it('generates anonymized id from user id', function () {
+        $context = UserContext::authenticated('123456789');
+        $anonymizedId = $context->getAnonymizedId();
+
+        expect($anonymizedId)->not->toBeNull();
+        expect($anonymizedId)->toHaveLength(8);
+        expect($anonymizedId)->not->toBe('123456789');
+
+        // Same user ID should generate same anonymized ID
+        $context2 = UserContext::authenticated('123456789');
+        expect($context2->getAnonymizedId())->toBe($anonymizedId);
+    });
+
+    it('returns null anonymized id for anonymous users', function () {
+        $context = UserContext::anonymous();
+        expect($context->getAnonymizedId())->toBeNull();
+    });
+
+    it('masks email addresses', function () {
+        $context = UserContext::authenticated('123', email: 'john.doe@example.com');
+        $maskedEmail = $context->getMaskedEmail();
+
+        expect($maskedEmail)->toBe('j******e@example.com');
+    });
+
+    it('masks short email addresses', function () {
+        $context = UserContext::authenticated('123', email: 'a@b.com');
+        $maskedEmail = $context->getMaskedEmail();
+
+        expect($maskedEmail)->toBe('*@b.com');
+    });
+
+    it('handles invalid email format', function () {
+        $context = UserContext::authenticated('123', email: 'invalid-email');
+        $maskedEmail = $context->getMaskedEmail();
+
+        expect($maskedEmail)->toBe('***@***');
+    });
+
+    it('returns null masked email when no email', function () {
+        $context = UserContext::authenticated('123');
+        expect($context->getMaskedEmail())->toBeNull();
+    });
+
+    it('converts to array with all data', function () {
+        $context = UserContext::authenticated(
+            userId: '123',
+            username: 'john',
+            email: 'john@example.com',
+            sessionId: 'sess_123',
+            roles: ['user'],
+            permissions: ['read'],
+            authMethod: 'session'
+        )->withMetadata('source', 'test');
+
+        $array = $context->toArray();
+
+        expect($array)->toBe([
+            'user_id' => '123',
+            'is_authenticated' => true,
+            'username' => 'john',
+            'email_masked' => 'j**n@example.com',
+            'session_id' => 'sess_123',
+            'roles' => ['user'],
+            'permissions' => ['read'],
+            'auth_method' => 'session',
+            'metadata' => ['source' => 'test'],
+        ]);
+    });
+
+    it('converts to array with minimal data', function () {
+        $context = UserContext::authenticated('123');
+        $array = $context->toArray();
+
+        expect($array)->toBe([
+            'user_id' => '123',
+            'is_authenticated' => true,
+            'auth_method' => 'session',
+        ]);
+    });
+
+    it('converts to privacy safe array', function () {
+        $context = UserContext::authenticated(
+            userId: '123',
+            username: 'john',
+            email: 'john@example.com',
+            sessionId: 'sess_123',
+            roles: ['user', 'admin'],
+            permissions: ['read', 'write', 'delete'],
+            authMethod: 'oauth'
+        );
+
+        $array = $context->toPrivacySafeArray();
+
+        expect($array)->toBe([
+            'user_id_anonymized' => $context->getAnonymizedId(),
+            'is_authenticated' => true,
+            'roles_count' => 2,
+            'permissions_count' => 3,
+            'auth_method' => 'oauth',
+            'has_session' => true,
+        ]);
+    });
+
+    it('extracts user id from object in session data', function () {
+        $userObject = new class () {
+            public $id = '789';
+        };
+
+        $sessionData = ['user' => $userObject];
+        $context = UserContext::fromSession($sessionData);
+
+        expect($context->userId)->toBe('789');
+        expect($context->isAuthenticated)->toBeTrue();
+    });
+
+    it('extracts user id from array in session data', function () {
+        $sessionData = ['logged_in_user' => ['id' => '999']];
+        $context = UserContext::fromSession($sessionData);
+
+        expect($context->userId)->toBe('999');
+        expect($context->isAuthenticated)->toBeTrue();
+    });
+});

tests/Framework/MagicLinks/Actions/ActionResultTest.php

@@ -0,0 +1,72 @@
+<?php
+
+use App\Framework\MagicLinks\Actions\ActionResult;
+use App\Framework\MagicLinks\ValueObjects\ActionResultData;
+use App\Framework\MagicLinks\ValueObjects\ErrorCollection;
+
+describe('ActionResult', function () {
+    it('creates success result', function () {
+        $result = ActionResult::success('Operation successful');
+
+        expect($result->isSuccess())->toBeTrue();
+        expect($result->success)->toBeTrue();
+        expect($result->message)->toBe('Operation successful');
+        expect($result->data)->toBeInstanceOf(ActionResultData::class);
+        expect($result->data->isEmpty())->toBeTrue();
+        expect($result->errors)->toBeInstanceOf(ErrorCollection::class);
+        expect($result->errors->isEmpty())->toBeTrue();
+    });
+
+    it('creates success result with data', function () {
+        $data = ActionResultData::fromArray(['user_id' => 123]);
+        $result = ActionResult::success('Success', $data);
+
+        expect($result->isSuccess())->toBeTrue();
+        expect($result->data)->toBe($data);
+        expect($result->data->get('user_id'))->toBe(123);
+    });
+
+    it('creates success result with redirect', function () {
+        $result = ActionResult::success('Success', null, '/dashboard');
+
+        expect($result->isSuccess())->toBeTrue();
+        expect($result->redirectUrl)->toBe('/dashboard');
+        expect($result->hasRedirect())->toBeTrue();
+    });
+
+    it('creates failure result', function () {
+        $result = ActionResult::failure('Operation failed');
+
+        expect($result->isSuccess())->toBeFalse();
+        expect($result->success)->toBeFalse();
+        expect($result->message)->toBe('Operation failed');
+        expect($result->data->isEmpty())->toBeTrue();
+        expect($result->errors->isEmpty())->toBeTrue();
+    });
+
+    it('creates failure result with errors', function () {
+        $errors = ErrorCollection::fromArray(['Error 1', 'Error 2']);
+        $result = ActionResult::failure('Failed', $errors);
+
+        expect($result->isSuccess())->toBeFalse();
+        expect($result->errors)->toBe($errors);
+        expect($result->hasErrors())->toBeTrue();
+        expect($result->errors->count())->toBe(2);
+    });
+
+    it('checks for redirect', function () {
+        $withRedirect = ActionResult::success('Success', null, '/dashboard');
+        $withoutRedirect = ActionResult::success('Success');
+
+        expect($withRedirect->hasRedirect())->toBeTrue();
+        expect($withoutRedirect->hasRedirect())->toBeFalse();
+    });
+
+    it('checks for errors', function () {
+        $withErrors = ActionResult::failure('Failed', ErrorCollection::single('Error'));
+        $withoutErrors = ActionResult::failure('Failed');
+
+        expect($withErrors->hasErrors())->toBeTrue();
+        expect($withoutErrors->hasErrors())->toBeFalse();
+    });
+});

tests/Framework/MagicLinks/Commands/ExecuteMagicLinkCommandTest.php

@@ -0,0 +1,37 @@
+<?php
+
+use App\Framework\MagicLinks\Commands\ExecuteMagicLinkCommand;
+use App\Framework\MagicLinks\MagicLinkToken;
+use App\Framework\MagicLinks\ValueObjects\ExecutionContext;
+
+describe('ExecuteMagicLinkCommand', function () {
+    it('creates command with token and context', function () {
+        $token = new MagicLinkToken('test-token-12345678');
+        $context = ExecutionContext::fromArray(['ip' => '127.0.0.1']);
+
+        $command = new ExecuteMagicLinkCommand($token, $context);
+
+        expect($command->token)->toBe($token);
+        expect($command->context)->toBe($context);
+    });
+
+    it('creates command with factory method', function () {
+        $token = new MagicLinkToken('test-token-12345678');
+
+        $command = ExecuteMagicLinkCommand::withToken($token);
+
+        expect($command->token)->toBe($token);
+        expect($command->context)->toBeInstanceOf(ExecutionContext::class);
+        expect($command->context->isEmpty())->toBeTrue();
+    });
+
+    it('context is ExecutionContext value object', function () {
+        $token = new MagicLinkToken('test-token-12345678');
+        $context = ExecutionContext::fromArray(['test' => 'value']);
+
+        $command = new ExecuteMagicLinkCommand($token, $context);
+
+        expect($command->context)->toBeInstanceOf(ExecutionContext::class);
+        expect($command->context->toArray())->toBe(['test' => 'value']);
+    });
+});

tests/Framework/MagicLinks/Commands/GenerateMagicLinkCommandTest.php

@@ -0,0 +1,58 @@
+<?php
+
+use App\Framework\MagicLinks\Commands\GenerateMagicLinkCommand;
+use App\Framework\MagicLinks\TokenAction;
+use App\Framework\MagicLinks\TokenConfig;
+use App\Framework\MagicLinks\ValueObjects\MagicLinkPayload;
+
+describe('GenerateMagicLinkCommand', function () {
+    it('creates command with required parameters', function () {
+        $action = new TokenAction('email_verification');
+        $payload = MagicLinkPayload::fromArray(['email' => 'test@example.com']);
+
+        $command = new GenerateMagicLinkCommand(
+            action: $action,
+            payload: $payload
+        );
+
+        expect($command->action)->toBe($action);
+        expect($command->payload)->toBe($payload);
+        expect($command->config)->toBeNull();
+        expect($command->baseUrl)->toBeNull();
+    });
+
+    it('creates command with all parameters', function () {
+        $action = new TokenAction('email_verification');
+        $payload = MagicLinkPayload::fromArray(['email' => 'test@example.com']);
+        $config = new TokenConfig(expiryHours: 24);
+
+        $command = new GenerateMagicLinkCommand(
+            action: $action,
+            payload: $payload,
+            config: $config,
+            baseUrl: 'https://example.com',
+            createdByIp: '127.0.0.1',
+            userAgent: 'Test Agent'
+        );
+
+        expect($command->action)->toBe($action);
+        expect($command->payload)->toBe($payload);
+        expect($command->config)->toBe($config);
+        expect($command->baseUrl)->toBe('https://example.com');
+        expect($command->createdByIp)->toBe('127.0.0.1');
+        expect($command->userAgent)->toBe('Test Agent');
+    });
+
+    it('payload is MagicLinkPayload value object', function () {
+        $action = new TokenAction('test');
+        $payload = MagicLinkPayload::fromArray(['test' => 'value']);
+
+        $command = new GenerateMagicLinkCommand(
+            action: $action,
+            payload: $payload
+        );
+
+        expect($command->payload)->toBeInstanceOf(MagicLinkPayload::class);
+        expect($command->payload->toArray())->toBe(['test' => 'value']);
+    });
+});

tests/Framework/MagicLinks/ValueObjects/ActionResultDataTest.php

@@ -0,0 +1,53 @@
+<?php
+
+use App\Framework\MagicLinks\ValueObjects\ActionResultData;
+
+describe('ActionResultData', function () {
+    it('creates empty result data', function () {
+        $data = ActionResultData::empty();
+
+        expect($data->isEmpty())->toBeTrue();
+        expect($data->toArray())->toBe([]);
+    });
+
+    it('creates from array', function () {
+        $data = ActionResultData::fromArray(['user_id' => 123, 'email' => 'test@example.com']);
+
+        expect($data->isEmpty())->toBeFalse();
+        expect($data->toArray())->toBe(['user_id' => 123, 'email' => 'test@example.com']);
+    });
+
+    it('adds values immutably', function () {
+        $data = ActionResultData::empty();
+        $updated = $data->with('status', 'success');
+
+        expect($data->has('status'))->toBeFalse();
+        expect($updated->has('status'))->toBeTrue();
+        expect($updated->get('status'))->toBe('success');
+    });
+
+    it('retrieves values with defaults', function () {
+        $data = ActionResultData::fromArray(['status' => 'success']);
+
+        expect($data->get('status'))->toBe('success');
+        expect($data->get('missing', 'default'))->toBe('default');
+    });
+
+    it('merges data', function () {
+        $data1 = ActionResultData::fromArray(['user_id' => 123]);
+        $data2 = ActionResultData::fromArray(['email' => 'test@example.com']);
+        $merged = $data1->merge($data2);
+
+        expect($merged->toArray())->toBe([
+            'user_id' => 123,
+            'email' => 'test@example.com',
+        ]);
+    });
+
+    it('checks key existence', function () {
+        $data = ActionResultData::fromArray(['user_id' => 123]);
+
+        expect($data->has('user_id'))->toBeTrue();
+        expect($data->has('missing'))->toBeFalse();
+    });
+});

tests/Framework/MagicLinks/ValueObjects/ErrorCollectionTest.php

@@ -0,0 +1,64 @@
+<?php
+
+use App\Framework\MagicLinks\ValueObjects\ErrorCollection;
+
+describe('ErrorCollection', function () {
+    it('creates empty collection', function () {
+        $errors = ErrorCollection::empty();
+
+        expect($errors->isEmpty())->toBeTrue();
+        expect($errors->hasErrors())->toBeFalse();
+        expect($errors->count())->toBe(0);
+    });
+
+    it('creates collection from array', function () {
+        $errors = ErrorCollection::fromArray(['Error 1', 'Error 2']);
+
+        expect($errors->isEmpty())->toBeFalse();
+        expect($errors->hasErrors())->toBeTrue();
+        expect($errors->count())->toBe(2);
+    });
+
+    it('creates single error collection', function () {
+        $errors = ErrorCollection::single('Test error');
+
+        expect($errors->count())->toBe(1);
+        expect($errors->first())->toBe('Test error');
+    });
+
+    it('adds error immutably', function () {
+        $errors = ErrorCollection::empty();
+        $updated = $errors->add('New error');
+
+        expect($errors->count())->toBe(0);
+        expect($updated->count())->toBe(1);
+        expect($updated->first())->toBe('New error');
+    });
+
+    it('adds multiple errors', function () {
+        $errors = ErrorCollection::single('Error 1');
+        $updated = $errors->addMultiple(['Error 2', 'Error 3']);
+
+        expect($updated->count())->toBe(3);
+        expect($updated->toArray())->toBe(['Error 1', 'Error 2', 'Error 3']);
+    });
+
+    it('converts to string', function () {
+        $errors = ErrorCollection::fromArray(['Error 1', 'Error 2', 'Error 3']);
+
+        expect($errors->toString())->toBe('Error 1, Error 2, Error 3');
+        expect($errors->toString(' | '))->toBe('Error 1 | Error 2 | Error 3');
+    });
+
+    it('returns first error', function () {
+        $errors = ErrorCollection::fromArray(['First', 'Second']);
+
+        expect($errors->first())->toBe('First');
+    });
+
+    it('returns null for empty collection first', function () {
+        $errors = ErrorCollection::empty();
+
+        expect($errors->first())->toBeNull();
+    });
+});

tests/Framework/MagicLinks/ValueObjects/ExecutionContextTest.php

@@ -0,0 +1,51 @@
+<?php
+
+use App\Framework\MagicLinks\ValueObjects\ExecutionContext;
+
+describe('ExecutionContext', function () {
+    it('creates empty context', function () {
+        $context = ExecutionContext::empty();
+
+        expect($context->isEmpty())->toBeTrue();
+        expect($context->toArray())->toBe([]);
+    });
+
+    it('creates context from array', function () {
+        $context = ExecutionContext::fromArray(['ip' => '127.0.0.1', 'user_agent' => 'Test']);
+
+        expect($context->isEmpty())->toBeFalse();
+        expect($context->toArray())->toBe(['ip' => '127.0.0.1', 'user_agent' => 'Test']);
+    });
+
+    it('adds values immutably', function () {
+        $context = ExecutionContext::empty();
+        $updated = $context->with('ip', '127.0.0.1');
+
+        expect($context->has('ip'))->toBeFalse();
+        expect($updated->has('ip'))->toBeTrue();
+        expect($updated->get('ip'))->toBe('127.0.0.1');
+    });
+
+    it('retrieves values with defaults', function () {
+        $context = ExecutionContext::fromArray(['ip' => '127.0.0.1']);
+
+        expect($context->get('ip'))->toBe('127.0.0.1');
+        expect($context->get('missing', 'default'))->toBe('default');
+    });
+
+    it('merges contexts', function () {
+        $context1 = ExecutionContext::fromArray(['ip' => '127.0.0.1']);
+        $context2 = ExecutionContext::fromArray(['user_agent' => 'Test']);
+        $merged = $context1->merge($context2);
+
+        expect($merged->toArray())->toBe(['ip' => '127.0.0.1', 'user_agent' => 'Test']);
+    });
+
+    it('merges with override', function () {
+        $context1 = ExecutionContext::fromArray(['ip' => '127.0.0.1']);
+        $context2 = ExecutionContext::fromArray(['ip' => '192.168.1.1']);
+        $merged = $context1->merge($context2);
+
+        expect($merged->get('ip'))->toBe('192.168.1.1');
+    });
+});

tests/Framework/MagicLinks/ValueObjects/MagicLinkPayloadTest.php

@@ -0,0 +1,61 @@
+<?php
+
+use App\Framework\MagicLinks\ValueObjects\MagicLinkPayload;
+
+describe('MagicLinkPayload', function () {
+    it('creates payload from array', function () {
+        $payload = MagicLinkPayload::fromArray(['email' => 'test@example.com', 'user_id' => 123]);
+
+        expect($payload->toArray())->toBe(['email' => 'test@example.com', 'user_id' => 123]);
+    });
+
+    it('throws exception for empty payload', function () {
+        expect(fn() => MagicLinkPayload::fromArray([]))
+            ->toThrow(InvalidArgumentException::class, 'Payload cannot be empty');
+    });
+
+    it('retrieves value with get method', function () {
+        $payload = MagicLinkPayload::fromArray(['email' => 'test@example.com']);
+
+        expect($payload->get('email'))->toBe('test@example.com');
+        expect($payload->get('missing', 'default'))->toBe('default');
+    });
+
+    it('checks if key exists', function () {
+        $payload = MagicLinkPayload::fromArray(['email' => 'test@example.com']);
+
+        expect($payload->has('email'))->toBeTrue();
+        expect($payload->has('missing'))->toBeFalse();
+    });
+
+    it('creates new instance with added value', function () {
+        $payload = MagicLinkPayload::fromArray(['email' => 'test@example.com']);
+        $updated = $payload->with('user_id', 123);
+
+        expect($payload->has('user_id'))->toBeFalse();
+        expect($updated->has('user_id'))->toBeTrue();
+        expect($updated->get('user_id'))->toBe(123);
+    });
+
+    it('creates new instance without key', function () {
+        $payload = MagicLinkPayload::fromArray(['email' => 'test@example.com', 'user_id' => 123]);
+        $updated = $payload->without('user_id');
+
+        expect($payload->has('user_id'))->toBeTrue();
+        expect($updated->has('user_id'))->toBeFalse();
+    });
+
+    it('throws exception when removing last key', function () {
+        $payload = MagicLinkPayload::fromArray(['email' => 'test@example.com']);
+
+        expect(fn() => $payload->without('email'))
+            ->toThrow(InvalidArgumentException::class, 'Payload cannot be empty after removal');
+    });
+
+    it('returns keys and values', function () {
+        $payload = MagicLinkPayload::fromArray(['email' => 'test@example.com', 'user_id' => 123]);
+
+        expect($payload->keys())->toBe(['email', 'user_id']);
+        expect($payload->values())->toBe(['test@example.com', 123]);
+    });
+});

tests/Framework/MagicLinks/ValueObjects/MetadataTest.php

@@ -0,0 +1,51 @@
+<?php
+
+use App\Framework\MagicLinks\ValueObjects\Metadata;
+
+describe('Metadata', function () {
+    it('creates empty metadata', function () {
+        $metadata = Metadata::empty();
+
+        expect($metadata->isEmpty())->toBeTrue();
+        expect($metadata->toArray())->toBe([]);
+    });
+
+    it('creates from array', function () {
+        $metadata = Metadata::fromArray(['source' => 'email', 'campaign' => 'welcome']);
+
+        expect($metadata->isEmpty())->toBeFalse();
+        expect($metadata->toArray())->toBe(['source' => 'email', 'campaign' => 'welcome']);
+    });
+
+    it('adds values immutably', function () {
+        $metadata = Metadata::empty();
+        $updated = $metadata->with('source', 'email');
+
+        expect($metadata->has('source'))->toBeFalse();
+        expect($updated->has('source'))->toBeTrue();
+        expect($updated->get('source'))->toBe('email');
+    });
+
+    it('removes values immutably', function () {
+        $metadata = Metadata::fromArray(['source' => 'email', 'campaign' => 'welcome']);
+        $updated = $metadata->without('campaign');
+
+        expect($metadata->has('campaign'))->toBeTrue();
+        expect($updated->has('campaign'))->toBeFalse();
+        expect($updated->has('source'))->toBeTrue();
+    });
+
+    it('merges metadata', function () {
+        $meta1 = Metadata::fromArray(['source' => 'email']);
+        $meta2 = Metadata::fromArray(['campaign' => 'welcome']);
+        $merged = $meta1->merge($meta2);
+
+        expect($merged->toArray())->toBe(['source' => 'email', 'campaign' => 'welcome']);
+    });
+
+    it('returns keys', function () {
+        $metadata = Metadata::fromArray(['source' => 'email', 'campaign' => 'welcome']);
+
+        expect($metadata->keys())->toBe(['source', 'campaign']);
+    });
+});

tests/Framework/Mail/Commands/SendEmailBatchCommandHandlerTest.php

@@ -3,6 +3,10 @@
 declare(strict_types=1);
 
 use App\Domain\Common\ValueObject\Email;
+use App\Framework\Logging\ChannelLogger;
+use App\Framework\Logging\LogChannel;
+use App\Framework\Logging\LogLevel;
+use App\Framework\Logging\ValueObjects\LogContext;
 use App\Framework\Mail\Commands\SendEmailBatchCommand;
 use App\Framework\Mail\Commands\SendEmailBatchCommandHandler;
 use App\Framework\Mail\EmailList;
@@ -164,46 +168,51 @@ class BatchTestLogger implements \App\Framework\Logging\Logger
 {
     private array $logs = [];
 
-    public function emergency(string $message, array $context = []): void
+    public function emergency(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'emergency', 'message' => $message, 'context' => $context];
     }
 
-    public function alert(string $message, array $context = []): void
+    public function alert(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'alert', 'message' => $message, 'context' => $context];
     }
 
-    public function critical(string $message, array $context = []): void
+    public function critical(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'critical', 'message' => $message, 'context' => $context];
     }
 
-    public function error(string $message, array $context = []): void
+    public function error(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'error', 'message' => $message, 'context' => $context];
     }
 
-    public function warning(string $message, array $context = []): void
+    public function warning(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'warning', 'message' => $message, 'context' => $context];
     }
 
-    public function notice(string $message, array $context = []): void
+    public function notice(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'notice', 'message' => $message, 'context' => $context];
     }
 
-    public function info(string $message, array $context = []): void
+    public function info(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'info', 'message' => $message, 'context' => $context];
     }
 
-    public function debug(string $message, array $context = []): void
+    public function debug(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'debug', 'message' => $message, 'context' => $context];
     }
 
+    public function log(LogLevel $level, string $message, ?LogContext $context = null): void
+    {
+        $this->logs[] = ['level' => $level->value, 'message' => $message, 'context' => $context];
+    }
+
     public function getLogs(): array
     {
         return $this->logs;
@@ -239,6 +248,80 @@ class BatchTestLogger implements \App\Framework\Logging\Logger
 
         return false;
     }
+
+    public function logToChannel(LogChannel $channel, LogLevel $level, string $message, ?LogContext $context = null): void
+    {
+        $this->logs[] = ['level' => $level->value, 'channel' => $channel->value, 'message' => $message, 'context' => $context];
+    }
+
+    private ?ChannelLogger $mockChannelLogger = null;
+
+    public ChannelLogger $security {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    public ChannelLogger $cache {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    public ChannelLogger $database {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    public ChannelLogger $framework {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    public ChannelLogger $error {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    private function createMockChannelLogger(): ChannelLogger
+    {
+        return new class () implements ChannelLogger {
+            public function emergency(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function alert(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function critical(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function error(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function warning(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function notice(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function info(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function debug(string $message, ?LogContext $context = null): void
+            {
+            }
+        };
+    }
 }
 
 // Test transport classes for batch handler

tests/Framework/Mail/Commands/SendEmailCommandHandlerTest.php

@@ -3,7 +3,11 @@
 declare(strict_types=1);
 
 use App\Domain\Common\ValueObject\Email;
+use App\Framework\Logging\ChannelLogger;
+use App\Framework\Logging\LogChannel;
 use App\Framework\Logging\Logger;
+use App\Framework\Logging\LogLevel;
+use App\Framework\Logging\ValueObjects\LogContext;
 use App\Framework\Mail\Commands\SendEmailCommand;
 use App\Framework\Mail\Commands\SendEmailCommandHandler;
 use App\Framework\Mail\EmailList;
@@ -112,46 +116,51 @@ class MailTestLogger implements Logger
 {
     private array $logs = [];
 
-    public function emergency(string $message, array $context = []): void
+    public function emergency(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'emergency', 'message' => $message, 'context' => $context];
     }
 
-    public function alert(string $message, array $context = []): void
+    public function alert(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'alert', 'message' => $message, 'context' => $context];
     }
 
-    public function critical(string $message, array $context = []): void
+    public function critical(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'critical', 'message' => $message, 'context' => $context];
     }
 
-    public function error(string $message, array $context = []): void
+    public function error(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'error', 'message' => $message, 'context' => $context];
     }
 
-    public function warning(string $message, array $context = []): void
+    public function warning(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'warning', 'message' => $message, 'context' => $context];
     }
 
-    public function notice(string $message, array $context = []): void
+    public function notice(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'notice', 'message' => $message, 'context' => $context];
     }
 
-    public function info(string $message, array $context = []): void
+    public function info(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'info', 'message' => $message, 'context' => $context];
     }
 
-    public function debug(string $message, array $context = []): void
+    public function debug(string $message, ?LogContext $context = null): void
     {
         $this->logs[] = ['level' => 'debug', 'message' => $message, 'context' => $context];
     }
 
+    public function log(LogLevel $level, string $message, ?LogContext $context = null): void
+    {
+        $this->logs[] = ['level' => $level->value, 'message' => $message, 'context' => $context];
+    }
+
     public function getLogs(): array
     {
         return $this->logs;
@@ -187,6 +196,80 @@ class MailTestLogger implements Logger
 
         return false;
     }
+
+    public function logToChannel(LogChannel $channel, LogLevel $level, string $message, ?LogContext $context = null): void
+    {
+        $this->logs[] = ['level' => $level->value, 'channel' => $channel->value, 'message' => $message, 'context' => $context];
+    }
+
+    private ?ChannelLogger $mockChannelLogger = null;
+
+    public ChannelLogger $security {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    public ChannelLogger $cache {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    public ChannelLogger $database {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    public ChannelLogger $framework {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    public ChannelLogger $error {
+        get {
+            return $this->mockChannelLogger ??= $this->createMockChannelLogger();
+        }
+    }
+
+    private function createMockChannelLogger(): ChannelLogger
+    {
+        return new class () implements ChannelLogger {
+            public function emergency(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function alert(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function critical(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function error(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function warning(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function notice(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function info(string $message, ?LogContext $context = null): void
+            {
+            }
+
+            public function debug(string $message, ?LogContext $context = null): void
+            {
+            }
+        };
+    }
 }
 
 // Test transport classes

tests/Framework/Mail/MailerTest.php

@@ -12,6 +12,7 @@ use App\Framework\Mail\Message;
 use App\Framework\Mail\Testing\MockTransport;
 use App\Framework\Mail\TransportResult;
 use App\Framework\Queue\Queue;
+use App\Framework\Queue\ValueObjects\JobPayload;
 
 describe('Mailer', function () {
     beforeEach(function () {
@@ -241,17 +242,39 @@ class MailTestQueue implements Queue
 
     private array $jobs = [];
 
-    public function push(object $job): void
+    public function push(JobPayload $payload): void
     {
         $this->used = true;
-        $this->jobs[] = $job;
+        $this->jobs[] = $payload;
     }
 
-    public function pop(): ?object
+    public function pop(): ?JobPayload
     {
         return array_shift($this->jobs);
     }
 
+    public function peek(): ?JobPayload
+    {
+        return $this->jobs[0] ?? null;
+    }
+
+    public function size(): int
+    {
+        return count($this->jobs);
+    }
+
+    public function clear(): int
+    {
+        $count = count($this->jobs);
+        $this->jobs = [];
+        return $count;
+    }
+
+    public function getStats(): array
+    {
+        return ['size' => count($this->jobs)];
+    }
+
     public function wasUsed(): bool
     {
         return $this->used;

tests/Framework/Mcp/Tools/FrameworkToolsTest.php

@@ -0,0 +1,193 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Mcp\Tools;
+
+use App\Framework\DI\Container;
+use App\Framework\DI\DefaultContainer;
+use App\Framework\Discovery\UnifiedDiscoveryService;
+use App\Framework\Mcp\Tools\FrameworkTools;
+use App\Framework\Router\CompiledRoutes;
+use Mockery;
+
+describe('FrameworkTools MCP Integration', function () {
+    beforeEach(function () {
+        $this->container = new DefaultContainer();
+        $this->discoveryService = Mockery::mock(UnifiedDiscoveryService::class);
+        $this->compiledRoutes = Mockery::mock(CompiledRoutes::class);
+
+        $this->frameworkTools = new FrameworkTools(
+            $this->container,
+            $this->discoveryService,
+            $this->compiledRoutes
+        );
+    });
+
+    afterEach(function () {
+        Mockery::close();
+    });
+
+    it('can analyze routes', function () {
+        $this->compiledRoutes
+            ->shouldReceive('getStaticRoutes')
+            ->once()
+            ->andReturn([
+                '/admin' => ['handler' => 'AdminController@dashboard'],
+                '/api/users' => ['handler' => 'UserController@index'],
+            ]);
+
+        $this->compiledRoutes
+            ->shouldReceive('getNamedRoutes')
+            ->once()
+            ->andReturn([
+                'admin.dashboard' => '/admin',
+                'api.users.index' => '/api/users',
+            ]);
+
+        $result = $this->frameworkTools->analyzeRoutes();
+
+        expect($result)->toBeArray();
+        expect($result)->toHaveKey('named_routes');
+        expect($result)->toHaveKey('total_routes');
+        expect($result['total_routes'])->toBe(2);
+    });
+
+    it('can analyze container bindings', function () {
+        // Register some services in the container
+        $this->container->singleton('TestService', function () {
+            return new \stdClass();
+        });
+
+        $result = $this->frameworkTools->analyzeContainerBindings();
+
+        expect($result)->toBeArray();
+        expect($result)->toHaveKey('total_bindings');
+        expect($result)->toHaveKey('bindings');
+        expect($result['total_bindings'])->toBeGreaterThan(0);
+    });
+
+    it('can discover attributes', function () {
+        $mockRegistry = Mockery::mock(\App\Framework\Discovery\Results\DiscoveryRegistry::class);
+        $mockAttributeRegistry = Mockery::mock(\App\Framework\Discovery\Results\AttributeRegistry::class);
+
+        $mockRegistry->attributes = $mockAttributeRegistry;
+
+        $mockAttributeRegistry
+            ->shouldReceive('get')
+            ->with('App\\Framework\\Mcp\\McpTool')
+            ->once()
+            ->andReturn([
+                ['className' => 'TestClass', 'methodName' => 'testMethod'],
+                ['className' => 'AnotherClass', 'methodName' => 'anotherMethod'],
+            ]);
+
+        $this->discoveryService
+            ->shouldReceive('discover')
+            ->once()
+            ->andReturn($mockRegistry);
+
+        $result = $this->frameworkTools->discoverAttributes('App\\Framework\\Mcp\\McpTool');
+
+        expect($result)->toBeArray();
+        expect($result)->toHaveKey('attribute_class');
+        expect($result)->toHaveKey('count');
+        expect($result)->toHaveKey('discoveries');
+        expect($result['attribute_class'])->toBe('App\\Framework\\Mcp\\McpTool');
+        expect($result['count'])->toBe(2);
+        expect($result['discoveries'])->toHaveCount(2);
+    });
+
+    it('handles discovery errors gracefully', function () {
+        $this->discoveryService
+            ->shouldReceive('discover')
+            ->once()
+            ->andThrow(new \Exception('Discovery failed'));
+
+        $result = $this->frameworkTools->discoverAttributes('NonExistentAttribute');
+
+        expect($result)->toBeArray();
+        expect($result)->toHaveKey('error');
+        expect($result)->toHaveKey('attribute_class');
+        expect($result['error'])->toBe('Discovery failed');
+        expect($result['attribute_class'])->toBe('NonExistentAttribute');
+    });
+
+    it('performs framework health check', function () {
+        $result = $this->frameworkTools->frameworkHealthCheck();
+
+        expect($result)->toBeArray();
+        expect($result)->toHaveKey('status');
+        expect($result)->toHaveKey('components');
+        expect($result)->toHaveKey('timestamp');
+        expect($result['status'])->toBe('completed');
+        expect($result['components'])->toHaveKey('container');
+        expect($result['components'])->toHaveKey('discovery_service');
+    });
+
+    it('lists framework modules', function () {
+        $result = $this->frameworkTools->listFrameworkModules();
+
+        expect($result)->toBeArray();
+        expect($result)->toHaveKey('core_modules');
+        expect($result)->toHaveKey('total_modules');
+        expect($result['core_modules'])->toBeArray();
+        expect($result['total_modules'])->toBeGreaterThan(0);
+    });
+
+    it('validates container health in health check', function () {
+        $result = $this->frameworkTools->frameworkHealthCheck();
+
+        expect($result['components']['container'])->toBe('healthy');
+    });
+
+    it('validates discovery service health in health check', function () {
+        $result = $this->frameworkTools->frameworkHealthCheck();
+
+        expect($result['components']['discovery_service'])->toBe('healthy');
+    });
+
+    it('handles container errors in health check', function () {
+        // Create a broken container scenario by triggering an error
+        $brokenContainer = Mockery::mock(Container::class);
+        $brokenContainer
+            ->shouldReceive('get')
+            ->andThrow(new \Exception('Container error'));
+
+        $frameworkTools = new FrameworkTools(
+            $brokenContainer,
+            $this->discoveryService,
+            $this->compiledRoutes
+        );
+
+        $result = $frameworkTools->frameworkHealthCheck();
+
+        expect($result['components']['container'])->toContain('error');
+    });
+
+    it('limits discovery results to prevent overwhelming output', function () {
+        $mockRegistry = Mockery::mock(\App\Framework\Discovery\Results\DiscoveryRegistry::class);
+        $mockAttributeRegistry = Mockery::mock(\App\Framework\Discovery\Results\AttributeRegistry::class);
+
+        $mockRegistry->attributes = $mockAttributeRegistry;
+
+        // Create 15 mock results
+        $manyResults = array_fill(0, 15, ['className' => 'TestClass', 'methodName' => 'testMethod']);
+
+        $mockAttributeRegistry
+            ->shouldReceive('get')
+            ->once()
+            ->andReturn($manyResults);
+
+        $this->discoveryService
+            ->shouldReceive('discover')
+            ->once()
+            ->andReturn($mockRegistry);
+
+        $result = $this->frameworkTools->discoverAttributes('SomeAttribute');
+
+        expect($result['total_found'])->toBe(15);
+        expect($result['discoveries'])->toHaveCount(10); // Limited to 10
+        expect($result['count'])->toBe(15); // But count shows total
+    });
+});

tests/Framework/Performance/PerformanceMetricsIntegrationTest.php

@@ -0,0 +1,607 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Core\ValueObjects\Byte;
+use App\Framework\Core\ValueObjects\Duration;
+use App\Framework\Database\ConnectionInterface;
+use App\Framework\Database\Migration\Migration;
+use App\Framework\Database\Migration\MigrationCollection;
+use App\Framework\Database\Migration\MigrationRunner;
+use App\Framework\Database\Migration\MigrationVersion;
+use App\Framework\Database\Platform\MySQLPlatform;
+use App\Framework\Database\QueryBuilder\QueryBuilder;
+use App\Framework\Database\QueryBuilder\QueryBuilderFactory;
+use App\Framework\Database\ResultInterface;
+use App\Framework\Database\ValueObjects\SqlQuery;
+use App\Framework\DateTime\SystemClock;
+use App\Framework\Performance\Entity\PerformanceMetric;
+use App\Framework\Performance\MemoryMonitor;
+use App\Framework\Performance\OperationTracker;
+use App\Framework\Performance\PerformanceCategory;
+use App\Framework\Performance\Repository\PerformanceMetricsRepository;
+
+describe('Performance Metrics Integration', function () {
+    beforeEach(function () {
+        $this->connection = new PerformanceMetricsMockConnection();
+        $this->platform = new MySQLPlatform();
+        $this->clock = new SystemClock();
+        $this->memoryMonitor = new MemoryMonitor();
+        $this->operationTracker = new OperationTracker($this->clock, $this->memoryMonitor);
+        $this->queryBuilderFactory = new PerformanceMetricsMockQueryBuilderFactory();
+        $this->performanceMetricsRepository = new PerformanceMetricsRepository(
+            $this->connection,
+            $this->queryBuilderFactory
+        );
+
+        $this->migrationRunner = new MigrationRunner(
+            $this->connection,
+            $this->platform,
+            $this->clock,
+            null, // tableConfig
+            null, // logger
+            $this->operationTracker,
+            $this->memoryMonitor,
+            null, // performanceReporter
+            null, // memoryThresholds
+            $this->performanceMetricsRepository
+        );
+    });
+
+    test('migration runner persists performance metrics for successful migrations', function () {
+        $migration = new PerformanceTestMigration();
+        $migrations = new MigrationCollection($migration);
+
+        // Set no applied migrations initially
+        $this->connection->setAppliedMigrations([]);
+
+        $result = $this->migrationRunner->migrate($migrations);
+
+        expect($result)->toContain('2024_01_01_000000');
+        expect($migration->wasExecuted())->toBeTrue();
+
+        // Verify performance metrics were persisted
+        $savedMetrics = $this->queryBuilderFactory->getInsertedData('performance_metrics');
+        expect($savedMetrics)->toHaveCount(1);
+
+        $metric = $savedMetrics[0];
+        expect($metric['operation_type'])->toBe('migration_execution');
+        expect($metric['category'])->toBe('DATABASE');
+        expect($metric['migration_version'])->toBe('2024_01_01_000000');
+        expect($metric['success'])->toBe(true);
+        expect($metric['error_message'])->toBeNull();
+        expect($metric['metadata'])->toContain('migration_description');
+    });
+
+    test('migration runner persists performance metrics for failed migrations', function () {
+        $migration = new PerformanceMetricsFailingTestMigration();
+        $migrations = new MigrationCollection($migration);
+
+        // Set no applied migrations initially
+        $this->connection->setAppliedMigrations([]);
+
+        expect(function () {
+            $this->migrationRunner->migrate($migrations);
+        })->toThrow(Exception::class);
+
+        // Verify failed migration performance metrics were persisted
+        $savedMetrics = $this->queryBuilderFactory->getInsertedData('performance_metrics');
+        expect($savedMetrics)->toHaveCount(1);
+
+        $metric = $savedMetrics[0];
+        expect($metric['operation_type'])->toBe('migration_execution');
+        expect($metric['category'])->toBe('DATABASE');
+        expect($metric['migration_version'])->toBe('2024_01_01_000001');
+        expect($metric['success'])->toBe(false);
+        expect($metric['error_message'])->toContain('Test migration failure');
+        expect($metric['metadata'])->toContain('error_type');
+    });
+
+    test('migration runner persists performance metrics for rollbacks', function () {
+        $migration = new PerformanceTestMigration();
+        $migrations = new MigrationCollection($migration);
+
+        // Set migration as already applied
+        $this->connection->setAppliedMigrations([
+            ['version' => '2024_01_01_000000', 'description' => 'Performance Test Migration'],
+        ]);
+
+        $result = $this->migrationRunner->rollback($migrations, 1);
+
+        expect($result)->toContain($migration);
+
+        // Verify rollback performance metrics were persisted
+        $savedMetrics = $this->queryBuilderFactory->getInsertedData('performance_metrics');
+        expect($savedMetrics)->toHaveCount(1);
+
+        $metric = $savedMetrics[0];
+        expect($metric['operation_type'])->toBe('rollback_execution');
+        expect($metric['category'])->toBe('DATABASE');
+        expect($metric['migration_version'])->toBe('2024_01_01_000000');
+        expect($metric['success'])->toBe(true);
+        expect($metric['metadata'])->toContain('rollback_steps');
+    });
+
+    test('performance metrics repository can query metrics by migration version', function () {
+        // Create test metrics
+        $version = MigrationVersion::fromTimestamp('2024_01_01_000000');
+        $metrics = [
+            PerformanceMetric::fromPerformanceSnapshot(
+                'migration_test_1',
+                'migration_execution',
+                PerformanceCategory::DATABASE,
+                Duration::fromMilliseconds(1500),
+                Byte::fromBytes(50 * 1024 * 1024),
+                Byte::fromBytes(55 * 1024 * 1024),
+                Byte::fromBytes(60 * 1024 * 1024),
+                Byte::fromBytes(5 * 1024 * 1024),
+                true,
+                null,
+                $version,
+                ['test' => 'data']
+            ),
+            PerformanceMetric::fromPerformanceSnapshot(
+                'rollback_test_1',
+                'rollback_execution',
+                PerformanceCategory::DATABASE,
+                Duration::fromMilliseconds(800),
+                Byte::fromBytes(55 * 1024 * 1024),
+                Byte::fromBytes(50 * 1024 * 1024),
+                Byte::fromBytes(55 * 1024 * 1024),
+                Byte::fromBytes(-5 * 1024 * 1024),
+                true,
+                null,
+                $version,
+                ['rollback' => 'data']
+            ),
+        ];
+
+        // Save metrics
+        $this->performanceMetricsRepository->saveBatch($metrics);
+
+        // Query by migration version
+        $foundMetrics = $this->performanceMetricsRepository->findByMigrationVersion($version);
+
+        expect($foundMetrics)->toHaveCount(2);
+        expect($foundMetrics[0]->operationType)->toBeIn(['migration_execution', 'rollback_execution']);
+        expect($foundMetrics[1]->operationType)->toBeIn(['migration_execution', 'rollback_execution']);
+    });
+
+    test('performance metrics repository can get performance statistics', function () {
+        $since = new DateTimeImmutable('-1 hour');
+
+        // Create test metrics with different categories
+        $metrics = [
+            PerformanceMetric::fromPerformanceSnapshot(
+                'migration_1',
+                'migration_execution',
+                PerformanceCategory::DATABASE,
+                Duration::fromMilliseconds(1000),
+                Byte::fromBytes(50 * 1024 * 1024),
+                Byte::fromBytes(55 * 1024 * 1024),
+                Byte::fromBytes(60 * 1024 * 1024),
+                Byte::fromBytes(5 * 1024 * 1024),
+                true
+            ),
+            PerformanceMetric::fromPerformanceSnapshot(
+                'migration_2',
+                'migration_execution',
+                PerformanceCategory::DATABASE,
+                Duration::fromMilliseconds(2000),
+                Byte::fromBytes(60 * 1024 * 1024),
+                Byte::fromBytes(65 * 1024 * 1024),
+                Byte::fromBytes(70 * 1024 * 1024),
+                Byte::fromBytes(5 * 1024 * 1024),
+                false,
+                'Test failure'
+            ),
+        ];
+
+        $this->performanceMetricsRepository->saveBatch($metrics);
+
+        $statistics = $this->performanceMetricsRepository->getPerformanceStatistics($since);
+
+        expect($statistics)->toHaveCount(1); // Only DATABASE category
+        expect($statistics[0]['category'])->toBe(PerformanceCategory::DATABASE);
+        expect($statistics[0]['total_operations'])->toBe(2);
+        expect($statistics[0]['successful_operations'])->toBe(1);
+        expect($statistics[0]['success_rate'])->toBe(0.5);
+        expect($statistics[0]['avg_execution_time'])->toBeInstanceOf(Duration::class);
+    });
+
+    test('performance metrics repository can find slow operations', function () {
+        $slowThreshold = Duration::fromMilliseconds(1500);
+
+        $metrics = [
+            PerformanceMetric::fromPerformanceSnapshot(
+                'fast_migration',
+                'migration_execution',
+                PerformanceCategory::DATABASE,
+                Duration::fromMilliseconds(500), // Fast
+                Byte::fromBytes(50 * 1024 * 1024),
+                Byte::fromBytes(55 * 1024 * 1024),
+                Byte::fromBytes(60 * 1024 * 1024),
+                Byte::fromBytes(5 * 1024 * 1024),
+                true
+            ),
+            PerformanceMetric::fromPerformanceSnapshot(
+                'slow_migration',
+                'migration_execution',
+                PerformanceCategory::DATABASE,
+                Duration::fromMilliseconds(3000), // Slow
+                Byte::fromBytes(60 * 1024 * 1024),
+                Byte::fromBytes(70 * 1024 * 1024),
+                Byte::fromBytes(75 * 1024 * 1024),
+                Byte::fromBytes(10 * 1024 * 1024),
+                true
+            ),
+        ];
+
+        $this->performanceMetricsRepository->saveBatch($metrics);
+
+        $slowOperations = $this->performanceMetricsRepository->findSlowOperations($slowThreshold);
+
+        expect($slowOperations)->toHaveCount(1);
+        expect($slowOperations[0]->operationId)->toBe('slow_migration');
+        expect($slowOperations[0]->executionTime->toMilliseconds())->toBe(3000);
+    });
+});
+
+// Test fixtures
+class PerformanceTestMigration implements Migration
+{
+    private bool $executed = false;
+
+    public function up(ConnectionInterface $connection): void
+    {
+        $this->executed = true;
+        // Simulate migration execution
+        $connection->execute(SqlQuery::create('CREATE TABLE performance_test (id INT)'));
+    }
+
+    public function down(ConnectionInterface $connection): void
+    {
+        $connection->execute(SqlQuery::create('DROP TABLE performance_test'));
+    }
+
+    public function getDescription(): string
+    {
+        return 'Performance Test Migration';
+    }
+
+    public function getVersion(): MigrationVersion
+    {
+        return MigrationVersion::fromTimestamp('2024_01_01_000000');
+    }
+
+    public function wasExecuted(): bool
+    {
+        return $this->executed;
+    }
+}
+
+class PerformanceMetricsFailingTestMigration implements Migration
+{
+    public function up(ConnectionInterface $connection): void
+    {
+        throw new \Exception('Test migration failure');
+    }
+
+    public function down(ConnectionInterface $connection): void
+    {
+        // Empty
+    }
+
+    public function getDescription(): string
+    {
+        return 'Failing Test Migration';
+    }
+
+    public function getVersion(): MigrationVersion
+    {
+        return MigrationVersion::fromTimestamp('2024_01_01_000001');
+    }
+}
+
+class PerformanceMetricsMockConnection implements ConnectionInterface
+{
+    private array $queries = [];
+
+    private array $appliedMigrations = [];
+
+    private bool $inTransaction = false;
+
+    public function setAppliedMigrations(array $migrations): void
+    {
+        $this->appliedMigrations = $migrations;
+    }
+
+    public function execute(SqlQuery $query): int
+    {
+        $this->queries[] = ['type' => 'execute', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
+
+        return 1;
+    }
+
+    public function query(SqlQuery $query): ResultInterface
+    {
+        $this->queries[] = ['type' => 'query', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
+
+        return new PerformanceMetricsMockResult($this->appliedMigrations);
+    }
+
+    public function queryOne(SqlQuery $query): ?array
+    {
+        return null;
+    }
+
+    public function queryColumn(SqlQuery $query): array
+    {
+        $this->queries[] = ['type' => 'queryColumn', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
+
+        return array_column($this->appliedMigrations, 'version');
+    }
+
+    public function queryScalar(SqlQuery $query): mixed
+    {
+        $this->queries[] = ['type' => 'queryScalar', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
+
+        // Return '1' for connectivity test (SELECT 1)
+        if (str_contains($query->sql, 'SELECT 1')) {
+            return '1';
+        }
+
+        return null;
+    }
+
+    public function beginTransaction(): void
+    {
+        $this->inTransaction = true;
+    }
+
+    public function commit(): void
+    {
+        $this->inTransaction = false;
+    }
+
+    public function rollback(): void
+    {
+        $this->inTransaction = false;
+    }
+
+    public function inTransaction(): bool
+    {
+        return $this->inTransaction;
+    }
+
+    public function lastInsertId(): string
+    {
+        return '1';
+    }
+
+    public function getPdo(): \PDO
+    {
+        return new class () extends \PDO {
+            public function __construct()
+            {
+                // Skip parent constructor to avoid actual DB connection
+            }
+
+            public function getAttribute(int $attribute): mixed
+            {
+                return match($attribute) {
+                    \PDO::ATTR_DRIVER_NAME => 'mysql',
+                    default => null
+                };
+            }
+        };
+    }
+
+    public function getQueries(): array
+    {
+        return $this->queries;
+    }
+}
+
+class PerformanceMetricsMockResult implements ResultInterface
+{
+    private array $data;
+
+    public function __construct(array $data)
+    {
+        $this->data = $data;
+    }
+
+    public function fetch(): ?array
+    {
+        return $this->data[0] ?? null;
+    }
+
+    public function fetchAll(): array
+    {
+        return $this->data;
+    }
+
+    public function fetchOne(): ?array
+    {
+        return $this->data[0] ?? null;
+    }
+
+    public function fetchColumn(int $column = 0): array
+    {
+        return array_column($this->data, $column);
+    }
+
+    public function fetchScalar(): mixed
+    {
+        $row = $this->fetchOne();
+
+        return $row ? array_values($row)[0] : null;
+    }
+
+    public function rowCount(): int
+    {
+        return count($this->data);
+    }
+
+    public function getIterator(): \Traversable
+    {
+        return new \ArrayIterator($this->data);
+    }
+
+    public function count(): int
+    {
+        return count($this->data);
+    }
+}
+
+class PerformanceMetricsMockQueryBuilderFactory
+{
+    private array $insertedData = [];
+
+    public function create(ConnectionInterface $connection): QueryBuilder
+    {
+        return new PerformanceMetricsMockQueryBuilder($this);
+    }
+
+    public function recordInsert(string $table, array $data): void
+    {
+        if (! isset($this->insertedData[$table])) {
+            $this->insertedData[$table] = [];
+        }
+        $this->insertedData[$table][] = $data;
+    }
+
+    public function getInsertedData(string $table): array
+    {
+        return $this->insertedData[$table] ?? [];
+    }
+}
+
+class PerformanceMetricsMockQueryBuilder implements QueryBuilder
+{
+    private string $tableName = '';
+
+    private array $wheres = [];
+
+    private string $orderBy = '';
+
+    private ?int $limitValue = null;
+
+    public function __construct(private PerformanceMetricsMockQueryBuilderFactory $factory)
+    {
+    }
+
+    public function table(string $table): self
+    {
+        $this->tableName = $table;
+
+        return $this;
+    }
+
+    public function select(array $columns): self
+    {
+        return $this;
+    }
+
+    public function where(string $column, string $operator, mixed $value): self
+    {
+        $this->wheres[] = [$column, $operator, $value];
+
+        return $this;
+    }
+
+    public function orderBy(string $column, string $direction = 'ASC'): self
+    {
+        $this->orderBy = "$column $direction";
+
+        return $this;
+    }
+
+    public function limit(int $limit): self
+    {
+        $this->limitValue = $limit;
+
+        return $this;
+    }
+
+    public function groupBy(string $column): self
+    {
+        return $this;
+    }
+
+    public function get(): array
+    {
+        // Mock return based on table and conditions
+        if ($this->tableName === 'performance_metrics') {
+            return $this->factory->getInsertedData('performance_metrics');
+        }
+
+        return [];
+    }
+
+    public function first(): ?array
+    {
+        $results = $this->get();
+
+        return $results[0] ?? null;
+    }
+
+    public function count(): int
+    {
+        return count($this->get());
+    }
+
+    public function average(string $column): ?float
+    {
+        $results = $this->get();
+        if (empty($results)) {
+            return null;
+        }
+
+        $values = array_column($results, $column);
+
+        return array_sum($values) / count($values);
+    }
+
+    public function insert(array $data): int
+    {
+        $this->factory->recordInsert($this->tableName, $data);
+
+        return 1; // Mock insert ID
+    }
+
+    public function insertBatch(array $data): int
+    {
+        foreach ($data as $row) {
+            $this->factory->recordInsert($this->tableName, $row);
+        }
+
+        return count($data);
+    }
+
+    public function update(array $data): int
+    {
+        return 1;
+    }
+
+    public function delete(): int
+    {
+        return 1;
+    }
+
+    public function toSql(): string
+    {
+        return "SELECT * FROM {$this->tableName}";
+    }
+
+    public function getParameters(): array
+    {
+        return [];
+    }
+
+    public function execute(): mixed
+    {
+        return $this->get();
+    }
+}

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
+        });
+    });
+});

tests/Framework/Router/RouteEnumTest.php

@@ -0,0 +1,132 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Router\WebRoutes;
+use App\Framework\Router\ApiRoutes;
+use App\Framework\Router\AdminRoutes;
+use App\Framework\Router\HealthRoutes;
+use App\Framework\Router\MediaRoutes;
+use App\Framework\Router\RouteCategory;
+
+describe('Route Enums', function () {
+
+    describe('WebRoutes', function () {
+        it('implements RouteNameInterface correctly', function () {
+            expect(WebRoutes::HOME)->toBeInstanceOf(\App\Framework\Router\RouteNameInterface::class);
+        });
+
+        it('returns correct values', function () {
+            expect(WebRoutes::HOME->value)->toBe('home');
+            expect(WebRoutes::CONTACT->value)->toBe('contact');
+        });
+
+        it('returns correct category', function () {
+            expect(WebRoutes::HOME->getCategory())->toBe(RouteCategory::WEB);
+        });
+
+        it('returns correct route type checks', function () {
+            expect(WebRoutes::HOME->isWebRoute())->toBeTrue();
+            expect(WebRoutes::HOME->isApiRoute())->toBeFalse();
+            expect(WebRoutes::HOME->isAdminRoute())->toBeFalse();
+            expect(WebRoutes::HOME->isAuthRoute())->toBeFalse();
+        });
+    });
+
+    describe('ApiRoutes', function () {
+        it('implements RouteNameInterface correctly', function () {
+            expect(ApiRoutes::USERS_LIST)->toBeInstanceOf(\App\Framework\Router\RouteNameInterface::class);
+        });
+
+        it('returns correct values', function () {
+            expect(ApiRoutes::USERS_LIST->value)->toBe('api_users_list');
+            expect(ApiRoutes::HEALTH->value)->toBe('api_health');
+        });
+
+        it('returns correct category', function () {
+            expect(ApiRoutes::USERS_LIST->getCategory())->toBe(RouteCategory::API);
+        });
+
+        it('returns correct route type checks', function () {
+            expect(ApiRoutes::USERS_LIST->isApiRoute())->toBeTrue();
+            expect(ApiRoutes::USERS_LIST->isWebRoute())->toBeFalse();
+            expect(ApiRoutes::USERS_LIST->isAdminRoute())->toBeFalse();
+            expect(ApiRoutes::USERS_LIST->isAuthRoute())->toBeFalse();
+        });
+    });
+
+    describe('AdminRoutes', function () {
+        it('implements RouteNameInterface correctly', function () {
+            expect(AdminRoutes::DASHBOARD)->toBeInstanceOf(\App\Framework\Router\RouteNameInterface::class);
+        });
+
+        it('returns correct values', function () {
+            expect(AdminRoutes::DASHBOARD->value)->toBe('admin.dashboard');
+            expect(AdminRoutes::MIGRATIONS->value)->toBe('admin.migrations');
+        });
+
+        it('returns correct category', function () {
+            expect(AdminRoutes::DASHBOARD->getCategory())->toBe(RouteCategory::ADMIN);
+        });
+
+        it('returns correct route type checks', function () {
+            expect(AdminRoutes::DASHBOARD->isAdminRoute())->toBeTrue();
+            expect(AdminRoutes::DASHBOARD->isApiRoute())->toBeFalse();
+            expect(AdminRoutes::DASHBOARD->isWebRoute())->toBeFalse();
+            expect(AdminRoutes::DASHBOARD->isAuthRoute())->toBeFalse();
+        });
+    });
+
+    describe('HealthRoutes', function () {
+        it('implements RouteNameInterface correctly', function () {
+            expect(HealthRoutes::HEALTH_CHECK)->toBeInstanceOf(\App\Framework\Router\RouteNameInterface::class);
+        });
+
+        it('returns correct values', function () {
+            expect(HealthRoutes::HEALTH_CHECK->value)->toBe('health_check');
+            expect(HealthRoutes::HEALTH_LIVENESS->value)->toBe('health_liveness');
+        });
+
+        it('returns correct category', function () {
+            expect(HealthRoutes::HEALTH_CHECK->getCategory())->toBe(RouteCategory::WEB);
+        });
+
+        it('returns correct route type checks', function () {
+            expect(HealthRoutes::HEALTH_CHECK->isWebRoute())->toBeTrue();
+            expect(HealthRoutes::HEALTH_CHECK->isApiRoute())->toBeFalse();
+            expect(HealthRoutes::HEALTH_CHECK->isAdminRoute())->toBeFalse();
+            expect(HealthRoutes::HEALTH_CHECK->isAuthRoute())->toBeFalse();
+        });
+    });
+
+    describe('MediaRoutes', function () {
+        it('implements RouteNameInterface correctly', function () {
+            expect(MediaRoutes::SHOW_IMAGE)->toBeInstanceOf(\App\Framework\Router\RouteNameInterface::class);
+        });
+
+        it('returns correct values', function () {
+            expect(MediaRoutes::SHOW_IMAGE->value)->toBe('show_image');
+        });
+
+        it('returns correct category', function () {
+            expect(MediaRoutes::SHOW_IMAGE->getCategory())->toBe(RouteCategory::MEDIA);
+        });
+
+        it('returns correct route type checks', function () {
+            expect(MediaRoutes::SHOW_IMAGE->isWebRoute())->toBeFalse();
+            expect(MediaRoutes::SHOW_IMAGE->isApiRoute())->toBeFalse();
+            expect(MediaRoutes::SHOW_IMAGE->isAdminRoute())->toBeFalse();
+            expect(MediaRoutes::SHOW_IMAGE->isAuthRoute())->toBeFalse();
+        });
+    });
+});
+
+describe('RouteCategory', function () {
+    it('has correct values', function () {
+        expect(RouteCategory::WEB->value)->toBe('web');
+        expect(RouteCategory::API->value)->toBe('api');
+        expect(RouteCategory::ADMIN->value)->toBe('admin');
+        expect(RouteCategory::AUTH->value)->toBe('auth');
+        expect(RouteCategory::MEDIA->value)->toBe('media');
+    });
+});

tests/Framework/Router/RouteHelperTest.php

@@ -0,0 +1,190 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Router\RouteHelper;
+use App\Framework\Router\UrlGenerator;
+use App\Framework\Router\WebRoutes;
+use App\Framework\Router\ApiRoutes;
+use App\Framework\Router\AdminRoutes;
+use App\Framework\Router\HealthRoutes;
+use App\Framework\Router\MediaRoutes;
+
+describe('RouteHelper', function () {
+    beforeEach(function () {
+        $this->mockUrlGenerator = mock(UrlGenerator::class);
+        $this->routeHelper = new RouteHelper($this->mockUrlGenerator);
+    });
+
+    describe('web routes', function () {
+        it('generates web route URLs correctly', function () {
+            $this->mockUrlGenerator->shouldReceive('route')
+                ->once()
+                ->with(WebRoutes::HOME, [], false)
+                ->andReturn('/');
+
+            $result = $this->routeHelper->web(WebRoutes::HOME);
+
+            expect($result)->toBe('/');
+        });
+
+        it('generates absolute web route URLs', function () {
+            $this->mockUrlGenerator->shouldReceive('route')
+                ->once()
+                ->with(WebRoutes::HOME, [], true)
+                ->andReturn('https://example.com/');
+
+            $result = $this->routeHelper->absoluteWeb(WebRoutes::HOME);
+
+            expect($result)->toBe('https://example.com/');
+        });
+
+        it('passes parameters correctly', function () {
+            $params = ['id' => 123];
+
+            $this->mockUrlGenerator->shouldReceive('route')
+                ->once()
+                ->with(WebRoutes::CONTACT, $params, false)
+                ->andReturn('/contact?id=123');
+
+            $result = $this->routeHelper->web(WebRoutes::CONTACT, $params);
+
+            expect($result)->toBe('/contact?id=123');
+        });
+    });
+
+    describe('API routes', function () {
+        it('generates API route URLs correctly', function () {
+            $this->mockUrlGenerator->shouldReceive('route')
+                ->once()
+                ->with(ApiRoutes::USERS_LIST, [], false)
+                ->andReturn('/api/users');
+
+            $result = $this->routeHelper->api(ApiRoutes::USERS_LIST);
+
+            expect($result)->toBe('/api/users');
+        });
+
+        it('generates absolute API route URLs', function () {
+            $this->mockUrlGenerator->shouldReceive('route')
+                ->once()
+                ->with(ApiRoutes::USERS_LIST, [], true)
+                ->andReturn('https://api.example.com/api/users');
+
+            $result = $this->routeHelper->absoluteApi(ApiRoutes::USERS_LIST);
+
+            expect($result)->toBe('https://api.example.com/api/users');
+        });
+    });
+
+    describe('admin routes', function () {
+        it('generates admin route URLs correctly', function () {
+            $this->mockUrlGenerator->shouldReceive('route')
+                ->once()
+                ->with(AdminRoutes::DASHBOARD, [], false)
+                ->andReturn('/admin');
+
+            $result = $this->routeHelper->admin(AdminRoutes::DASHBOARD);
+
+            expect($result)->toBe('/admin');
+        });
+
+        it('generates absolute admin route URLs', function () {
+            $this->mockUrlGenerator->shouldReceive('route')
+                ->once()
+                ->with(AdminRoutes::DASHBOARD, [], true)
+                ->andReturn('https://admin.example.com/admin');
+
+            $result = $this->routeHelper->absoluteAdmin(AdminRoutes::DASHBOARD);
+
+            expect($result)->toBe('https://admin.example.com/admin');
+        });
+    });
+
+    describe('health routes', function () {
+        it('generates health route URLs correctly', function () {
+            $this->mockUrlGenerator->shouldReceive('route')
+                ->once()
+                ->with(HealthRoutes::HEALTH_CHECK, [], false)
+                ->andReturn('/health');
+
+            $result = $this->routeHelper->health(HealthRoutes::HEALTH_CHECK);
+
+            expect($result)->toBe('/health');
+        });
+    });
+
+    describe('media routes', function () {
+        it('generates media route URLs correctly', function () {
+            $params = ['filename' => 'test.jpg'];
+
+            $this->mockUrlGenerator->shouldReceive('route')
+                ->once()
+                ->with(MediaRoutes::SHOW_IMAGE, $params, false)
+                ->andReturn('/images/test.jpg');
+
+            $result = $this->routeHelper->media(MediaRoutes::SHOW_IMAGE, $params);
+
+            expect($result)->toBe('/images/test.jpg');
+        });
+    });
+
+    describe('generic route handling', function () {
+        it('generates URLs for any RouteNameInterface', function () {
+            $this->mockUrlGenerator->shouldReceive('route')
+                ->once()
+                ->with(WebRoutes::HOME, [], false)
+                ->andReturn('/');
+
+            $result = $this->routeHelper->any(WebRoutes::HOME);
+
+            expect($result)->toBe('/');
+        });
+    });
+
+    describe('current route checking', function () {
+        it('checks if current route matches web route', function () {
+            $this->mockUrlGenerator->shouldReceive('isCurrentRoute')
+                ->once()
+                ->with(WebRoutes::HOME)
+                ->andReturn(true);
+
+            $result = $this->routeHelper->isCurrentWeb(WebRoutes::HOME);
+
+            expect($result)->toBeTrue();
+        });
+
+        it('checks if current route matches API route', function () {
+            $this->mockUrlGenerator->shouldReceive('isCurrentRoute')
+                ->once()
+                ->with(ApiRoutes::USERS_LIST)
+                ->andReturn(false);
+
+            $result = $this->routeHelper->isCurrentApi(ApiRoutes::USERS_LIST);
+
+            expect($result)->toBeFalse();
+        });
+
+        it('checks if current route matches admin route', function () {
+            $this->mockUrlGenerator->shouldReceive('isCurrentRoute')
+                ->once()
+                ->with(AdminRoutes::DASHBOARD)
+                ->andReturn(true);
+
+            $result = $this->routeHelper->isCurrentAdmin(AdminRoutes::DASHBOARD);
+
+            expect($result)->toBeTrue();
+        });
+
+        it('checks if current route matches any route', function () {
+            $this->mockUrlGenerator->shouldReceive('isCurrentRoute')
+                ->once()
+                ->with(HealthRoutes::HEALTH_CHECK)
+                ->andReturn(false);
+
+            $result = $this->routeHelper->isCurrent(HealthRoutes::HEALTH_CHECK);
+
+            expect($result)->toBeFalse();
+        });
+    });
+});

tests/Framework/Router/UrlGeneratorRouteEnumTest.php

@@ -0,0 +1,138 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Router\UrlGenerator;
+use App\Framework\Router\CompiledRoutes;
+use App\Framework\Router\WebRoutes;
+use App\Framework\Router\ApiRoutes;
+use App\Framework\Router\AdminRoutes;
+use App\Framework\Http\Request;
+
+describe('UrlGenerator with Route Enums', function () {
+    beforeEach(function () {
+        $this->mockRequest = mock(Request::class);
+        $this->mockCompiledRoutes = mock(CompiledRoutes::class);
+        $this->urlGenerator = new UrlGenerator($this->mockRequest, $this->mockCompiledRoutes);
+    });
+
+    describe('route generation with enums', function () {
+        it('generates URLs using WebRoutes enum', function () {
+            $mockRoute = (object) ['path' => '/'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('home')
+                ->andReturn($mockRoute);
+
+            $result = $this->urlGenerator->route(WebRoutes::HOME);
+
+            expect($result)->toBe('/');
+        });
+
+        it('generates URLs using ApiRoutes enum', function () {
+            $mockRoute = (object) ['path' => '/api/users'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('api_users_list')
+                ->andReturn($mockRoute);
+
+            $result = $this->urlGenerator->route(ApiRoutes::USERS_LIST);
+
+            expect($result)->toBe('/api/users');
+        });
+
+        it('generates URLs using AdminRoutes enum', function () {
+            $mockRoute = (object) ['path' => '/admin'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('admin.dashboard')
+                ->andReturn($mockRoute);
+
+            $result = $this->urlGenerator->route(AdminRoutes::DASHBOARD);
+
+            expect($result)->toBe('/admin');
+        });
+
+        it('generates URLs with parameters using enum', function () {
+            $mockRoute = (object) ['path' => '/api/users/{id}'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('api_users_show')
+                ->andReturn($mockRoute);
+
+            $result = $this->urlGenerator->route(ApiRoutes::USERS_SHOW, ['id' => 123]);
+
+            expect($result)->toBe('/api/users/123');
+        });
+    });
+
+    describe('backward compatibility', function () {
+        it('still works with string route names', function () {
+            $mockRoute = (object) ['path' => '/legacy'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('legacy_route')
+                ->andReturn($mockRoute);
+
+            $result = $this->urlGenerator->route('legacy_route');
+
+            expect($result)->toBe('/legacy');
+        });
+    });
+
+    describe('absolute URL generation', function () {
+        it('generates absolute URLs using enums', function () {
+            $mockRoute = (object) ['path' => '/'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('home')
+                ->andReturn($mockRoute);
+
+            $this->mockRequest->server = mock();
+            $this->mockRequest->server->shouldReceive('isHttps')->andReturn(true);
+            $this->mockRequest->server->shouldReceive('getHttpHost')->andReturn('example.com');
+
+            $result = $this->urlGenerator->absoluteRoute(WebRoutes::HOME);
+
+            expect($result)->toBe('https://example.com/');
+        });
+    });
+
+    describe('current route checking', function () {
+        it('checks current route using enum', function () {
+            $mockRoute = (object) ['path' => '/'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('home')
+                ->andReturn($mockRoute);
+
+            $this->mockRequest->path = '/';
+
+            $result = $this->urlGenerator->isCurrentRoute(WebRoutes::HOME);
+
+            expect($result)->toBeTrue();
+        });
+
+        it('returns false for non-matching enum route', function () {
+            $mockRoute = (object) ['path' => '/admin'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('admin.dashboard')
+                ->andReturn($mockRoute);
+
+            $this->mockRequest->path = '/';
+
+            $result = $this->urlGenerator->isCurrentRoute(AdminRoutes::DASHBOARD);
+
+            expect($result)->toBeFalse();
+        });
+    });
+});

tests/Framework/Router/ValueObjects/PlaceholderTest.php

@@ -0,0 +1,104 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Router\ValueObjects\Placeholder;
+
+describe('Placeholder', function () {
+    describe('creation', function () {
+        it('can be created from string', function () {
+            $placeholder = Placeholder::fromString('id');
+
+            expect($placeholder->getName())->toBe('id');
+            expect($placeholder->toString())->toBe('{id}');
+            expect($placeholder->isWildcard())->toBeFalse();
+        });
+
+        it('can be created with type', function () {
+            $placeholder = Placeholder::typed('id', 'int');
+
+            expect($placeholder->getName())->toBe('id');
+            expect($placeholder->getType())->toBe('int');
+            expect($placeholder->getPattern())->toBe('(\d+)');
+        });
+
+        it('can be created as wildcard', function () {
+            $placeholder = Placeholder::wildcard('path');
+
+            expect($placeholder->getName())->toBe('path');
+            expect($placeholder->toString())->toBe('{path*}');
+            expect($placeholder->isWildcard())->toBeTrue();
+            expect($placeholder->getPattern())->toBe('(.+?)');
+        });
+
+        it('validates placeholder names', function () {
+            expect(fn() => Placeholder::fromString(''))
+                ->toThrow(InvalidArgumentException::class);
+
+            expect(fn() => Placeholder::fromString('123invalid'))
+                ->toThrow(InvalidArgumentException::class);
+
+            expect(fn() => Placeholder::fromString('invalid-name'))
+                ->toThrow(InvalidArgumentException::class);
+        });
+
+        it('accepts valid placeholder names', function () {
+            $validNames = ['id', 'userId', 'user_id', '_private', 'snake_case'];
+
+            foreach ($validNames as $name) {
+                $placeholder = Placeholder::fromString($name);
+                expect($placeholder->getName())->toBe($name);
+            }
+        });
+    });
+
+    describe('type patterns', function () {
+        it('provides correct patterns for common types', function () {
+            $patterns = [
+                'int' => '(\d+)',
+                'uuid' => '([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})',
+                'slug' => '([a-z0-9\-]+)',
+                'alpha' => '([a-zA-Z]+)',
+                'alphanumeric' => '([a-zA-Z0-9]+)',
+                'filename' => '([a-zA-Z0-9._\-]+)',
+            ];
+
+            foreach ($patterns as $type => $expectedPattern) {
+                $placeholder = Placeholder::typed('test', $type);
+                expect($placeholder->getPattern())->toBe($expectedPattern);
+            }
+        });
+
+        it('falls back to default pattern for unknown types', function () {
+            $placeholder = Placeholder::typed('test', 'unknown');
+            expect($placeholder->getPattern())->toBe('([^/]+)');
+        });
+
+        it('allows custom patterns', function () {
+            $placeholder = Placeholder::typed('test', 'custom', '([a-z]{3})');
+            expect($placeholder->getPattern())->toBe('([a-z]{3})');
+        });
+    });
+
+    describe('string representation', function () {
+        it('converts to proper placeholder syntax', function () {
+            $regular = Placeholder::fromString('id');
+            $wildcard = Placeholder::wildcard('path');
+
+            expect($regular->toString())->toBe('{id}');
+            expect($wildcard->toString())->toBe('{path*}');
+        });
+    });
+
+    describe('pattern generation', function () {
+        it('returns correct regex patterns', function () {
+            $regular = Placeholder::fromString('id');
+            $wildcard = Placeholder::wildcard('path');
+            $typed = Placeholder::typed('id', 'int');
+
+            expect($regular->getPattern())->toBe('([^/]+)');
+            expect($wildcard->getPattern())->toBe('(.+?)');
+            expect($typed->getPattern())->toBe('(\d+)');
+        });
+    });
+});

tests/Framework/Router/ValueObjects/RoutePathTest.php

@@ -0,0 +1,158 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Router\ValueObjects\Placeholder;
+use App\Framework\Router\ValueObjects\RoutePath;
+
+describe('RoutePath', function () {
+    describe('creation', function () {
+        it('can be created from elements', function () {
+            $path = RoutePath::fromElements('api', 'users', Placeholder::fromString('id'));
+
+            expect($path->toString())->toBe('/api/users/{id}');
+            expect($path->isDynamic())->toBeTrue();
+            expect($path->getParameterNames())->toBe(['id']);
+        });
+
+        it('can be created from string', function () {
+            $path = RoutePath::fromString('/api/users/{id}');
+
+            expect($path->toString())->toBe('/api/users/{id}');
+            expect($path->isDynamic())->toBeTrue();
+            expect($path->getParameterNames())->toBe(['id']);
+        });
+
+        it('handles static routes', function () {
+            $path = RoutePath::fromElements('api', 'health');
+
+            expect($path->toString())->toBe('/api/health');
+            expect($path->isStatic())->toBeTrue();
+            expect($path->getParameterNames())->toBe([]);
+        });
+
+        it('handles wildcard parameters', function () {
+            $path = RoutePath::fromString('/files/{path*}');
+
+            expect($path->toString())->toBe('/files/{path*}');
+
+            $placeholders = $path->getPlaceholders();
+            expect($placeholders)->toHaveCount(1);
+            expect($placeholders[0]->isWildcard())->toBeTrue();
+        });
+
+        it('throws on empty path', function () {
+            expect(fn() => RoutePath::fromElements())
+                ->toThrow(InvalidArgumentException::class);
+        });
+    });
+
+    describe('fluent builder', function () {
+        it('can build paths fluently', function () {
+            $path = RoutePath::create()
+                ->segment('api')
+                ->segment('users')
+                ->parameter('id')
+                ->build();
+
+            expect($path->toString())->toBe('/api/users/{id}');
+        });
+
+        it('supports typed parameters', function () {
+            $path = RoutePath::create()
+                ->segment('api')
+                ->segment('users')
+                ->typedParameter('id', 'uuid')
+                ->build();
+
+            $placeholders = $path->getPlaceholders();
+            expect($placeholders[0]->getType())->toBe('uuid');
+        });
+
+        it('supports quick patterns', function () {
+            $path = RoutePath::create()
+                ->segment('api')
+                ->segment('users')
+                ->uuid();
+
+            expect($path->toString())->toBe('/api/users/{id}');
+        });
+    });
+
+    describe('regex compilation', function () {
+        it('compiles static routes to regex', function () {
+            $path = RoutePath::fromString('/api/health');
+
+            expect($path->toRegex())->toBe('~^/api/health$~');
+        });
+
+        it('compiles dynamic routes to regex', function () {
+            $path = RoutePath::fromString('/api/users/{id}');
+
+            expect($path->toRegex())->toBe('~^/api/users/([^/]+)$~');
+        });
+
+        it('compiles typed parameters correctly', function () {
+            $path = RoutePath::fromElements(
+                'api',
+                'users',
+                Placeholder::typed('id', 'int')
+            );
+
+            expect($path->toRegex())->toBe('~^/api/users/(\d+)$~');
+        });
+
+        it('compiles wildcard parameters', function () {
+            $path = RoutePath::fromElements(
+                'files',
+                Placeholder::wildcard('path')
+            );
+
+            expect($path->toRegex())->toBe('~^/files/(.+?)$~');
+        });
+    });
+
+    describe('manipulation', function () {
+        it('can append elements', function () {
+            $base = RoutePath::fromElements('api', 'users');
+            $extended = $base->append(Placeholder::fromString('id'));
+
+            expect($extended->toString())->toBe('/api/users/{id}');
+        });
+
+        it('can prepend elements', function () {
+            $base = RoutePath::fromElements('users', Placeholder::fromString('id'));
+            $extended = $base->prepend('api');
+
+            expect($extended->toString())->toBe('/api/users/{id}');
+        });
+    });
+
+    describe('analysis', function () {
+        it('counts segments correctly', function () {
+            $path = RoutePath::fromString('/api/users/{id}');
+
+            expect($path->getSegmentCount())->toBe(3);
+        });
+
+        it('identifies placeholders', function () {
+            $path = RoutePath::fromString('/api/users/{id}/posts/{postId}');
+
+            $placeholders = $path->getPlaceholders();
+            expect($placeholders)->toHaveCount(2);
+            expect($path->getParameterNames())->toBe(['id', 'postId']);
+        });
+    });
+
+    describe('validation', function () {
+        it('validates segment content', function () {
+            expect(fn() => RoutePath::fromElements('api', ''))
+                ->toThrow(InvalidArgumentException::class);
+        });
+
+        it('rejects invalid characters in segments', function () {
+            expect(fn() => RoutePath::fromElements('api', 'users{id}'))
+                ->toThrow(InvalidArgumentException::class);
+        });
+    });
+});

tests/Framework/Search/SearchDocumentTest.php

@@ -0,0 +1,151 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Search;
+
+use App\Framework\Search\SearchDocument;
+use App\Framework\Search\ValueObjects\DocumentData;
+use App\Framework\Search\ValueObjects\DocumentMetadata;
+use App\Framework\Search\ValueObjects\EntityId;
+use App\Framework\Search\ValueObjects\EntityType;
+
+describe('SearchDocument Value Object', function () {
+    it('can be created with Value Objects', function () {
+        $document = new SearchDocument(
+            EntityId::fromString('user_123'),
+            EntityType::user(),
+            DocumentData::fromArray(['name' => 'John', 'email' => 'john@test.com']),
+            DocumentMetadata::withTimestamps()
+        );
+
+        expect($document->id->toString())->toBe('user_123');
+        expect($document->entityType->toString())->toBe('user');
+        expect($document->data->get('name'))->toBe('John');
+        expect($document->hasMetadata())->toBeTrue();
+    });
+
+    it('can be created with minimal data', function () {
+        $document = new SearchDocument(
+            EntityId::fromString('product_456'),
+            EntityType::product(),
+            DocumentData::fromArray(['title' => 'Test Product'])
+        );
+
+        expect($document->id->toString())->toBe('product_456');
+        expect($document->hasMetadata())->toBeFalse();
+    });
+
+    it('supports immutable metadata updates', function () {
+        $document = new SearchDocument(
+            EntityId::fromString('test_1'),
+            EntityType::fromString('test'),
+            DocumentData::empty()
+        );
+
+        $updated = $document->withMetadata('version', '1.0');
+
+        expect($document->hasMetadata())->toBeFalse(); // Original unchanged
+        expect($updated->hasMetadata())->toBeTrue();
+        expect($updated->metadata->get('version'))->toBe('1.0');
+    });
+
+    it('supports immutable data updates', function () {
+        $document = new SearchDocument(
+            EntityId::fromString('test_1'),
+            EntityType::fromString('test'),
+            DocumentData::fromArray(['title' => 'Original'])
+        );
+
+        $updated = $document->withDocumentData(
+            DocumentData::fromArray(['title' => 'Updated', 'content' => 'New content'])
+        );
+
+        expect($document->data->get('title'))->toBe('Original'); // Original unchanged
+        expect($updated->data->get('title'))->toBe('Updated');
+        expect($updated->data->get('content'))->toBe('New content');
+    });
+
+    it('supports field-level updates', function () {
+        $document = new SearchDocument(
+            EntityId::fromString('test_1'),
+            EntityType::fromString('test'),
+            DocumentData::fromArray(['title' => 'Original', 'status' => 'draft'])
+        );
+
+        $updated = $document->withField('status', 'published');
+
+        expect($document->data->get('status'))->toBe('draft'); // Original unchanged
+        expect($updated->data->get('status'))->toBe('published');
+        expect($updated->data->get('title'))->toBe('Original'); // Other fields preserved
+    });
+
+    it('supports field removal', function () {
+        $document = new SearchDocument(
+            EntityId::fromString('test_1'),
+            EntityType::fromString('test'),
+            DocumentData::fromArray(['title' => 'Test', 'temp' => 'remove me'])
+        );
+
+        $updated = $document->withoutField('temp');
+
+        expect($document->data->has('temp'))->toBeTrue(); // Original unchanged
+        expect($updated->data->has('temp'))->toBeFalse();
+        expect($updated->data->has('title'))->toBeTrue(); // Other fields preserved
+    });
+
+    it('converts to array correctly', function () {
+        $document = new SearchDocument(
+            EntityId::fromString('user_123'),
+            EntityType::user(),
+            DocumentData::fromArray(['name' => 'John']),
+            DocumentMetadata::fromArray(['version' => '1.0'])
+        );
+
+        $array = $document->toArray();
+
+        expect($array)->toBe([
+            'id' => 'user_123',
+            'entity_type' => 'user',
+            'data' => ['name' => 'John'],
+            'metadata' => ['version' => '1.0'],
+        ]);
+    });
+
+    it('converts to index array with special fields', function () {
+        $document = new SearchDocument(
+            EntityId::fromString('product_456'),
+            EntityType::product(),
+            DocumentData::fromArray(['title' => 'Test Product', 'price' => 99.99]),
+            DocumentMetadata::fromArray(['version' => '2.0', 'language' => 'en'])
+        );
+
+        $indexArray = $document->toIndexArray();
+
+        expect($indexArray)->toBe([
+            'title' => 'Test Product',
+            'price' => 99.99,
+            '_id' => 'product_456',
+            '_type' => 'product',
+            '_meta_version' => '2.0',
+            '_meta_language' => 'en',
+        ]);
+    });
+
+    it('handles empty metadata correctly', function () {
+        $document = new SearchDocument(
+            EntityId::fromString('test_1'),
+            EntityType::fromString('test'),
+            DocumentData::fromArray(['title' => 'Test'])
+        );
+
+        expect($document->hasMetadata())->toBeFalse();
+
+        $indexArray = $document->toIndexArray();
+        expect($indexArray)->toBe([
+            'title' => 'Test',
+            '_id' => 'test_1',
+            '_type' => 'test',
+        ]);
+    });
+});

tests/Framework/Search/ValueObjects/DocumentDataTest.php

@@ -0,0 +1,130 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Search\ValueObjects;
+
+use App\Framework\Search\ValueObjects\DocumentData;
+use InvalidArgumentException;
+
+describe('DocumentData Value Object', function () {
+    it('can be created empty', function () {
+        $data = DocumentData::empty();
+        expect($data->isEmpty())->toBeTrue();
+        expect($data->toArray())->toBe([]);
+    });
+
+    it('can be created from array', function () {
+        $fields = ['title' => 'Test', 'content' => 'Content'];
+        $data = DocumentData::fromArray($fields);
+
+        expect($data->toArray())->toBe($fields);
+        expect($data->isEmpty())->toBeFalse();
+    });
+
+    it('can add fields immutably', function () {
+        $data = DocumentData::empty();
+        $newData = $data->with('title', 'Test Title');
+
+        expect($data->isEmpty())->toBeTrue(); // Original unchanged
+        expect($newData->get('title'))->toBe('Test Title');
+        expect($newData->has('title'))->toBeTrue();
+    });
+
+    it('can remove fields immutably', function () {
+        $data = DocumentData::fromArray(['title' => 'Test', 'content' => 'Content']);
+        $newData = $data->without('title');
+
+        expect($data->has('title'))->toBeTrue(); // Original unchanged
+        expect($newData->has('title'))->toBeFalse();
+        expect($newData->has('content'))->toBeTrue();
+    });
+
+    it('gets field values with defaults', function () {
+        $data = DocumentData::fromArray(['title' => 'Test']);
+
+        expect($data->get('title'))->toBe('Test');
+        expect($data->get('missing'))->toBeNull();
+        expect($data->get('missing', 'default'))->toBe('default');
+    });
+
+    it('extracts text fields only', function () {
+        $data = DocumentData::fromArray([
+            'title' => 'Text Title',
+            'content' => 'Text Content',
+            'price' => 123.45,
+            'active' => true,
+            'empty_text' => '',
+            'whitespace' => '   ',
+        ]);
+
+        $textFields = $data->getTextFields();
+        expect($textFields)->toBe([
+            'title' => 'Text Title',
+            'content' => 'Text Content',
+        ]);
+    });
+
+    it('extracts facet fields only', function () {
+        $data = DocumentData::fromArray([
+            'title' => 'Text Title',
+            'price' => 123.45,
+            'active' => true,
+            'count' => 42,
+            'nested' => ['key' => 'value'],
+        ]);
+
+        $facetFields = $data->getFacetFields();
+        expect($facetFields)->toBe([
+            'title' => 'Text Title',
+            'price' => 123.45,
+            'active' => true,
+            'count' => 42,
+        ]);
+    });
+
+    it('validates field keys', function () {
+        expect(fn () => DocumentData::fromArray(['' => 'value']))->toThrow(InvalidArgumentException::class);
+        expect(fn () => DocumentData::fromArray(['   ' => 'value']))->toThrow(InvalidArgumentException::class);
+        expect(fn () => DocumentData::fromArray([123 => 'value']))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('validates field key length', function () {
+        $longKey = str_repeat('a', 256);
+        expect(fn () => DocumentData::fromArray([$longKey => 'value']))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('validates field key format', function () {
+        expect(fn () => DocumentData::fromArray(['1invalid' => 'value']))->toThrow(InvalidArgumentException::class);
+        expect(fn () => DocumentData::fromArray(['invalid-key' => 'value']))->toThrow(InvalidArgumentException::class);
+        expect(fn () => DocumentData::fromArray(['invalid key' => 'value']))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('allows valid field keys', function () {
+        expect(fn () => DocumentData::fromArray(['valid' => 'value']))->not->toThrow(InvalidArgumentException::class);
+        expect(fn () => DocumentData::fromArray(['valid_key' => 'value']))->not->toThrow(InvalidArgumentException::class);
+        expect(fn () => DocumentData::fromArray(['valid123' => 'value']))->not->toThrow(InvalidArgumentException::class);
+        expect(fn () => DocumentData::fromArray(['a' => 'value']))->not->toThrow(InvalidArgumentException::class);
+    });
+
+    it('validates field values for serializability', function () {
+        $resource = fopen('php://memory', 'r');
+
+        expect(fn () => DocumentData::fromArray(['resource' => $resource]))->toThrow(InvalidArgumentException::class);
+
+        fclose($resource);
+    });
+
+    it('allows serializable values', function () {
+        $data = DocumentData::fromArray([
+            'string' => 'text',
+            'int' => 123,
+            'float' => 12.34,
+            'bool' => true,
+            'null' => null,
+            'array' => [1, 2, 3],
+        ]);
+
+        expect($data->toArray())->toHaveCount(6);
+    });
+});

tests/Framework/Search/ValueObjects/EntityIdTest.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Search\ValueObjects;
+
+use App\Framework\Search\ValueObjects\EntityId;
+use InvalidArgumentException;
+
+describe('EntityId Value Object', function () {
+    it('can be created with valid ID', function () {
+        $id = new EntityId('user_123');
+        expect($id->value)->toBe('user_123');
+    });
+
+    it('can be created from string', function () {
+        $id = EntityId::fromString('product_456');
+        expect($id->toString())->toBe('product_456');
+    });
+
+    it('can generate unique ID', function () {
+        $id1 = EntityId::generate();
+        $id2 = EntityId::generate();
+
+        expect($id1->toString())->not->toBe($id2->toString());
+        expect($id1->toString())->toStartWith('entity_');
+    });
+
+    it('converts to string', function () {
+        $id = new EntityId('test_789');
+        expect($id->__toString())->toBe('test_789');
+    });
+
+    it('compares equality correctly', function () {
+        $id1 = new EntityId('same_id');
+        $id2 = new EntityId('same_id');
+        $id3 = new EntityId('different_id');
+
+        expect($id1->equals($id2))->toBeTrue();
+        expect($id1->equals($id3))->toBeFalse();
+    });
+
+    it('throws exception for empty ID', function () {
+        expect(fn () => new EntityId(''))->toThrow(InvalidArgumentException::class);
+        expect(fn () => new EntityId('   '))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for too long ID', function () {
+        $longId = str_repeat('a', 256);
+        expect(fn () => new EntityId($longId))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for invalid characters', function () {
+        expect(fn () => new EntityId('invalid@id'))->toThrow(InvalidArgumentException::class);
+        expect(fn () => new EntityId('invalid id'))->toThrow(InvalidArgumentException::class);
+        expect(fn () => new EntityId('invalid/id'))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('allows valid characters', function () {
+        expect(fn () => new EntityId('valid_id.123-test'))->not->toThrow(InvalidArgumentException::class);
+        expect(fn () => new EntityId('123'))->not->toThrow(InvalidArgumentException::class);
+        expect(fn () => new EntityId('a'))->not->toThrow(InvalidArgumentException::class);
+    });
+});

tests/Framework/Search/ValueObjects/EntityTypeTest.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Framework\Search\ValueObjects;
+
+use App\Framework\Search\ValueObjects\EntityType;
+use InvalidArgumentException;
+
+describe('EntityType Value Object', function () {
+    it('can be created with valid type', function () {
+        $type = new EntityType('user');
+        expect($type->value)->toBe('user');
+    });
+
+    it('provides common entity types', function () {
+        expect(EntityType::user()->toString())->toBe('user');
+        expect(EntityType::product()->toString())->toBe('product');
+        expect(EntityType::article()->toString())->toBe('article');
+        expect(EntityType::category()->toString())->toBe('category');
+        expect(EntityType::order()->toString())->toBe('order');
+    });
+
+    it('can be created from string', function () {
+        $type = EntityType::fromString('custom_type');
+        expect($type->toString())->toBe('custom_type');
+    });
+
+    it('converts to string', function () {
+        $type = new EntityType('product');
+        expect($type->__toString())->toBe('product');
+    });
+
+    it('generates index name', function () {
+        $type = new EntityType('user');
+        expect($type->getIndexName())->toBe('search_user');
+    });
+
+    it('compares equality correctly', function () {
+        $type1 = new EntityType('user');
+        $type2 = new EntityType('user');
+        $type3 = new EntityType('product');
+
+        expect($type1->equals($type2))->toBeTrue();
+        expect($type1->equals($type3))->toBeFalse();
+    });
+
+    it('throws exception for empty type', function () {
+        expect(fn () => new EntityType(''))->toThrow(InvalidArgumentException::class);
+        expect(fn () => new EntityType('   '))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for too long type', function () {
+        $longType = str_repeat('a', 101);
+        expect(fn () => new EntityType($longType))->toThrow(InvalidArgumentException::class);
+    });
+
+    it('throws exception for invalid format', function () {
+        expect(fn () => new EntityType('User'))->toThrow(InvalidArgumentException::class); // uppercase
+        expect(fn () => new EntityType('user-type'))->toThrow(InvalidArgumentException::class); // hyphen
+        expect(fn () => new EntityType('user type'))->toThrow(InvalidArgumentException::class); // space
+        expect(fn () => new EntityType('1user'))->toThrow(InvalidArgumentException::class); // starts with number
+    });
+
+    it('allows valid format', function () {
+        expect(fn () => new EntityType('user'))->not->toThrow(InvalidArgumentException::class);
+        expect(fn () => new EntityType('user_type'))->not->toThrow(InvalidArgumentException::class);
+        expect(fn () => new EntityType('user123'))->not->toThrow(InvalidArgumentException::class);
+        expect(fn () => new EntityType('a'))->not->toThrow(InvalidArgumentException::class);
+    });
+});

tests/Framework/Vault/VaultTest.php

@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Database\ConnectionInterface;
+use App\Framework\Vault\DatabaseVault;
+use App\Framework\Vault\Exceptions\VaultKeyNotFoundException;
+use App\Framework\Vault\VaultAuditLogger;
+use App\Framework\Vault\ValueObjects\SecretKey;
+use App\Framework\Vault\ValueObjects\SecretValue;
+
+beforeEach(function () {
+    // Mock Connection für Tests
+    $this->connection = Mockery::mock(ConnectionInterface::class);
+    $this->auditLogger = Mockery::mock(VaultAuditLogger::class);
+
+    // Generate test encryption key
+    $this->encryptionKey = DatabaseVault::generateEncryptionKey();
+
+    $this->vault = new DatabaseVault(
+        connection: $this->connection,
+        encryptionKey: $this->encryptionKey,
+        auditLogger: $this->auditLogger
+    );
+});
+
+afterEach(function () {
+    Mockery::close();
+});
+
+describe('SecretKey Value Object', function () {
+    it('creates valid secret key', function () {
+        $key = SecretKey::from('database.password');
+
+        expect($key->value)->toBe('database.password');
+    });
+
+    it('rejects empty key', function () {
+        expect(fn () => SecretKey::from(''))
+            ->toThrow(InvalidArgumentException::class, 'Secret key cannot be empty');
+    });
+
+    it('rejects invalid characters', function () {
+        expect(fn () => SecretKey::from('invalid key!'))
+            ->toThrow(InvalidArgumentException::class);
+    });
+
+    it('accepts valid characters', function () {
+        $key = SecretKey::from('api.stripe.secret-key_2024');
+
+        expect($key->value)->toBe('api.stripe.secret-key_2024');
+    });
+});
+
+describe('SecretValue Value Object', function () {
+    it('stores secret value', function () {
+        $value = new SecretValue('my-secret-password');
+
+        expect($value->reveal())->toBe('my-secret-password');
+    });
+
+    it('masks value in __toString', function () {
+        $value = new SecretValue('my-secret-password');
+
+        expect((string) $value)->toBe('[SECRET]');
+    });
+
+    it('redacts value in var_dump', function () {
+        $value = new SecretValue('my-secret-password');
+        $debugInfo = $value->__debugInfo();
+
+        expect($debugInfo['value'])->toBe('[REDACTED]');
+        expect($debugInfo['length'])->toBe(18);
+    });
+
+    it('checks if value is empty', function () {
+        $empty = new SecretValue('');
+        $notEmpty = new SecretValue('value');
+
+        expect($empty->isEmpty())->toBeTrue();
+        expect($notEmpty->isEmpty())->toBeFalse();
+    });
+});
+
+describe('DatabaseVault Key Generation', function () {
+    it('generates valid encryption key', function () {
+        $key = DatabaseVault::generateEncryptionKey();
+
+        expect(strlen($key))->toBe(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);
+    });
+
+    it('encodes and decodes key correctly', function () {
+        $originalKey = DatabaseVault::generateEncryptionKey();
+        $encoded = DatabaseVault::encodeKey($originalKey);
+        $decoded = DatabaseVault::decodeKey($encoded);
+
+        expect($decoded)->toBe($originalKey);
+    });
+});
+
+describe('DatabaseVault Basic Operations', function () {
+    it('requires correct key length', function () {
+        $connection = Mockery::mock(ConnectionInterface::class);
+        $auditLogger = Mockery::mock(VaultAuditLogger::class);
+
+        expect(function () use ($connection, $auditLogger) {
+            new DatabaseVault(
+                connection: $connection,
+                encryptionKey: 'too-short',
+                auditLogger: $auditLogger
+            );
+        })->toThrow(InvalidArgumentException::class);
+    });
+
+    it('checks if libsodium is available', function () {
+        if (!extension_loaded('sodium')) {
+            $this->markTestSkipped('Sodium extension not available');
+        }
+
+        expect(extension_loaded('sodium'))->toBeTrue();
+    });
+});

tests/Framework/View/ComponentProcessorTest.php

@@ -0,0 +1,174 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\DI\DefaultContainer;
+use App\Framework\Template\Parser\DomTemplateParser;
+use App\Framework\View\ComponentRenderer;
+use App\Framework\View\DomComponentService;
+use App\Framework\View\Processors\ComponentProcessor;
+use App\Framework\View\Processors\PlaceholderReplacer;
+use App\Framework\View\RenderContext;
+
+beforeEach(function () {
+    $this->container = new DefaultContainer();
+
+    // Setup dependencies
+    $this->container->singleton(
+        PlaceholderReplacer::class,
+        new PlaceholderReplacer($this->container)
+    );
+
+    $this->componentService = new DomComponentService();
+    $this->componentRenderer = new ComponentRenderer(
+        __DIR__ . '/../../../src/Framework/View/templates/components'
+    );
+
+    $this->processor = new ComponentProcessor(
+        $this->componentService,
+        $this->componentRenderer,
+        $this->container
+    );
+
+    $this->parser = new DomTemplateParser();
+});
+
+describe('ComponentProcessor', function () {
+    it('processes simple component without attributes', function () {
+        $html = <<<HTML
+<div>
+    <component name="alert" />
+</div>
+HTML;
+
+        $dom = $this->parser->parseToWrapper($html);
+        $context = new RenderContext(
+            template: 'test',
+            data: [
+                'type' => 'info',
+                'message' => 'Test message',
+            ]
+        );
+
+        $result = $this->processor->process($dom, $context);
+        $output = $result->document->saveHTML();
+
+        expect($output)->toContain('alert alert-info');
+        expect($output)->toContain('Test message');
+    });
+
+    it('processes component with attributes', function () {
+        $html = <<<HTML
+<div>
+    <component name="alert" type="warning" message="Custom message" />
+</div>
+HTML;
+
+        $dom = $this->parser->parseToWrapper($html);
+        $context = new RenderContext(template: 'test', data: []);
+
+        $result = $this->processor->process($dom, $context);
+        $output = $result->document->saveHTML();
+
+        expect($output)->toContain('alert alert-warning');
+        expect($output)->toContain('Custom message');
+    });
+
+    it('processes nested components', function () {
+        $html = <<<HTML
+<div>
+    <component name="card" title="Test Card" message="Card content" />
+</div>
+HTML;
+
+        $dom = $this->parser->parseToWrapper($html);
+        $context = new RenderContext(template: 'test', data: []);
+
+        $result = $this->processor->process($dom, $context);
+        $output = $result->document->saveHTML();
+
+        expect($output)->toContain('card');
+        expect($output)->toContain('Test Card');
+        expect($output)->toContain('Card content');
+    });
+
+    it('handles components with placeholder variables', function () {
+        $html = <<<HTML
+<div>
+    <component name="alert" type="{{ alertType }}" message="{{ alertMessage }}" />
+</div>
+HTML;
+
+        $dom = $this->parser->parseToWrapper($html);
+        $context = new RenderContext(
+            template: 'test',
+            data: [
+                'alertType' => 'success',
+                'alertMessage' => 'Operation successful',
+            ]
+        );
+
+        $result = $this->processor->process($dom, $context);
+        $output = $result->document->saveHTML();
+
+        expect($output)->toContain('alert alert-success');
+        expect($output)->toContain('Operation successful');
+    });
+
+    it('gracefully handles missing component files', function () {
+        $html = <<<HTML
+<div>
+    <component name="non-existent-component" />
+</div>
+HTML;
+
+        $dom = $this->parser->parseToWrapper($html);
+        $context = new RenderContext(template: 'test', data: []);
+
+        // Should not throw exception
+        $result = $this->processor->process($dom, $context);
+
+        expect($result)->toBeInstanceOf(App\Framework\View\DomWrapper::class);
+    });
+
+    it('processes multiple components in sequence', function () {
+        $html = <<<HTML
+<div>
+    <component name="alert" type="info" message="First alert" />
+    <component name="alert" type="warning" message="Second alert" />
+    <component name="alert" type="danger" message="Third alert" />
+</div>
+HTML;
+
+        $dom = $this->parser->parseToWrapper($html);
+        $context = new RenderContext(template: 'test', data: []);
+
+        $result = $this->processor->process($dom, $context);
+        $output = $result->document->saveHTML();
+
+        expect($output)->toContain('First alert');
+        expect($output)->toContain('Second alert');
+        expect($output)->toContain('Third alert');
+        expect($output)->toContain('alert-info');
+        expect($output)->toContain('alert-warning');
+        expect($output)->toContain('alert-danger');
+    });
+
+    it('skips components without name attribute', function () {
+        $html = <<<HTML
+<div>
+    <component />
+    <component name="alert" type="info" message="Valid component" />
+</div>
+HTML;
+
+        $dom = $this->parser->parseToWrapper($html);
+        $context = new RenderContext(template: 'test', data: []);
+
+        $result = $this->processor->process($dom, $context);
+        $output = $result->document->saveHTML();
+
+        // Should only process the valid component
+        expect($output)->toContain('Valid component');
+    });
+});

tests/Framework/View/ForProcessorTest.php

@@ -0,0 +1,176 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\DI\DefaultContainer;
+use App\Framework\Meta\MetaData;
+use App\Framework\View\DomWrapper;
+use App\Framework\View\Processors\ForProcessor;
+use App\Framework\View\Processors\PlaceholderReplacer;
+use App\Framework\View\RenderContext;
+
+beforeEach(function () {
+    $this->container = new DefaultContainer();
+    $this->container->singleton(
+        PlaceholderReplacer::class,
+        new PlaceholderReplacer($this->container)
+    );
+    $this->processor = new ForProcessor($this->container);
+});
+
+describe('ForProcessor', function () {
+    it('processes simple for loops with array data', function () {
+        $html = <<<HTML
+<ul>
+    <for var="item" in="items">
+        <li>{{ item.name }}</li>
+    </for>
+</ul>
+HTML;
+
+        $context = new RenderContext(
+            template: 'test',
+            metaData: new MetaData('Test', 'Test'),
+            data: [
+                'items' => [
+                    ['name' => 'Item 1'],
+                    ['name' => 'Item 2'],
+                    ['name' => 'Item 3']
+                ]
+            ],
+            controllerClass: null
+        );
+
+        $dom = DomWrapper::fromString($html);
+        $result = $this->processor->process($dom, $context);
+        $output = $result->toHtml(true);
+
+        expect($output)->toContain('Item 1');
+        expect($output)->toContain('Item 2');
+        expect($output)->toContain('Item 3');
+        expect(str_contains($output, '<for'))->toBeFalse();
+    });
+
+    it('processes table rows in for loops', function () {
+        $html = <<<HTML
+<table>
+    <tbody>
+        <for var="check" in="health_checks">
+            <tr>
+                <td>{{ check.componentName }}</td>
+                <td>{{ check.status }}</td>
+            </tr>
+        </for>
+    </tbody>
+</table>
+HTML;
+
+        $context = new RenderContext(
+            template: 'health',
+            metaData: new MetaData('Health', 'Health'),
+            data: [
+                'health_checks' => [
+                    ['componentName' => 'Database', 'status' => 'healthy'],
+                    ['componentName' => 'Cache', 'status' => 'healthy'],
+                    ['componentName' => 'Queue', 'status' => 'degraded']
+                ]
+            ],
+            controllerClass: null
+        );
+
+        $dom = DomWrapper::fromString($html);
+        $result = $this->processor->process($dom, $context);
+        $output = $result->toHtml(true);
+
+        expect($output)->toContain('Database');
+        expect($output)->toContain('Cache');
+        expect($output)->toContain('Queue');
+        expect($output)->toContain('healthy');
+        expect($output)->toContain('degraded');
+        expect(str_contains($output, '<for'))->toBeFalse();
+    });
+
+    it('handles empty arrays gracefully', function () {
+        $html = <<<HTML
+<ul>
+    <for var="item" in="items">
+        <li>{{ item.name }}</li>
+    </for>
+</ul>
+HTML;
+
+        $context = new RenderContext(
+            template: 'test',
+            metaData: new MetaData('Test', 'Test'),
+            data: ['items' => []],
+            controllerClass: null
+        );
+
+        $dom = DomWrapper::fromString($html);
+        $result = $this->processor->process($dom, $context);
+        $output = $result->toHtml(true);
+
+        expect(str_contains($output, '<for'))->toBeFalse();
+        expect(str_contains($output, '{{ item.name }}'))->toBeFalse();
+    });
+
+    it('processes nested property paths', function () {
+        $html = <<<HTML
+<div>
+    <for var="user" in="data.users">
+        <p>{{ user.profile.displayName }}</p>
+    </for>
+</div>
+HTML;
+
+        $context = new RenderContext(
+            template: 'test',
+            metaData: new MetaData('Test', 'Test'),
+            data: [
+                'data' => [
+                    'users' => [
+                        ['profile' => ['displayName' => 'John Doe']],
+                        ['profile' => ['displayName' => 'Jane Smith']]
+                    ]
+                ]
+            ],
+            controllerClass: null
+        );
+
+        $dom = DomWrapper::fromString($html);
+        $result = $this->processor->process($dom, $context);
+        $output = $result->toHtml(true);
+
+        expect($output)->toContain('John Doe');
+        expect($output)->toContain('Jane Smith');
+    });
+
+    it('handles boolean values correctly', function () {
+        $html = <<<HTML
+<div>
+    <for var="item" in="items">
+        <span>{{ item.active }}</span>
+    </for>
+</div>
+HTML;
+
+        $context = new RenderContext(
+            template: 'test',
+            metaData: new MetaData('Test', 'Test'),
+            data: [
+                'items' => [
+                    ['active' => true],
+                    ['active' => false]
+                ]
+            ],
+            controllerClass: null
+        );
+
+        $dom = DomWrapper::fromString($html);
+        $result = $this->processor->process($dom, $context);
+        $output = $result->toHtml(true);
+
+        expect($output)->toContain('true');
+        expect($output)->toContain('false');
+    });
+});