feat(Production): Complete production deployment infrastructure

- Add comprehensive health check system with multiple endpoints
- Add Prometheus metrics endpoint
- Add production logging configurations (5 strategies)
- Add complete deployment documentation suite:
  * QUICKSTART.md - 30-minute deployment guide
  * DEPLOYMENT_CHECKLIST.md - Printable verification checklist
  * DEPLOYMENT_WORKFLOW.md - Complete deployment lifecycle
  * PRODUCTION_DEPLOYMENT.md - Comprehensive technical reference
  * production-logging.md - Logging configuration guide
  * ANSIBLE_DEPLOYMENT.md - Infrastructure as Code automation
  * README.md - Navigation hub
  * DEPLOYMENT_SUMMARY.md - Executive summary
- Add deployment scripts and automation
- Add DEPLOYMENT_PLAN.md - Concrete plan for immediate deployment
- Update README with production-ready features

All production infrastructure is now complete and ready for deployment.

tests/Unit/Framework/Filesystem/CachedFileStorageTest.php

@@ -0,0 +1,400 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Filesystem\CachedFileStorage;
+use App\Framework\Filesystem\FileStorage;
+use App\Framework\Filesystem\Exceptions\FileNotFoundException;
+use App\Framework\Filesystem\Exceptions\DirectoryCreateException;
+
+// Helper function for recursive directory deletion
+function deleteDirectoryRecursive(string $dir): void
+{
+    if (!is_dir($dir)) {
+        return;
+    }
+
+    $files = array_diff(scandir($dir), ['.', '..']);
+
+    foreach ($files as $file) {
+        $path = $dir . '/' . $file;
+        if (is_dir($path)) {
+            deleteDirectoryRecursive($path);
+        } else {
+            unlink($path);
+        }
+    }
+
+    rmdir($dir);
+}
+
+describe('CachedFileStorage', function () {
+    beforeEach(function () {
+        // Create temporary test directory
+        $this->testDir = sys_get_temp_dir() . '/cached_storage_test_' . uniqid();
+        mkdir($this->testDir, 0777, true);
+
+        // Create wrapped storage
+        $this->storage = new FileStorage(basePath: $this->testDir);
+        $this->cachedStorage = new CachedFileStorage($this->storage, basePath: $this->testDir);
+    });
+
+    afterEach(function () {
+        // Cleanup test directory
+        if (is_dir($this->testDir)) {
+            deleteDirectoryRecursive($this->testDir);
+        }
+    });
+
+
+    describe('Directory Caching', function () {
+        it('caches directory on first put', function () {
+            $path = 'subdir/file.txt';
+            $content = 'test content';
+
+            // First put - directory will be created and cached
+            $this->cachedStorage->put($path, $content);
+
+            $stats = $this->cachedStorage->getCacheStats();
+            expect($stats['cached_directories'])->toBeGreaterThan(0);
+
+            // Verify directory exists
+            $dir = $this->testDir . '/subdir';
+            expect(is_dir($dir))->toBeTrue();
+        });
+
+        it('reuses cached directory on subsequent puts', function () {
+            $dir = 'nested/deep/directory';
+
+            // First put - creates and caches directory
+            $this->cachedStorage->put($dir . '/file1.txt', 'content1');
+
+            $statsBefore = $this->cachedStorage->getCacheStats();
+            $cacheSizeBefore = $statsBefore['cached_directories'];
+
+            // Second put - reuses cached directory (no new is_dir call)
+            $this->cachedStorage->put($dir . '/file2.txt', 'content2');
+
+            $statsAfter = $this->cachedStorage->getCacheStats();
+            $cacheSizeAfter = $statsAfter['cached_directories'];
+
+            // Cache size should be same (directory already cached)
+            expect($cacheSizeAfter)->toBe($cacheSizeBefore);
+
+            // Both files should exist
+            expect(file_exists($this->testDir . '/' . $dir . '/file1.txt'))->toBeTrue();
+            expect(file_exists($this->testDir . '/' . $dir . '/file2.txt'))->toBeTrue();
+        });
+
+        it('caches parent directories recursively', function () {
+            $path = 'level1/level2/level3/file.txt';
+
+            $this->cachedStorage->put($path, 'test');
+
+            $stats = $this->cachedStorage->getCacheStats();
+
+            // Should cache level1, level1/level2, and level1/level2/level3
+            expect($stats['cached_directories'])->toBeGreaterThanOrEqual(3);
+        });
+
+        it('handles absolute paths correctly', function () {
+            $absolutePath = $this->testDir . '/absolute/file.txt';
+
+            $this->cachedStorage->put($absolutePath, 'test');
+
+            $stats = $this->cachedStorage->getCacheStats();
+            expect($stats['cached_directories'])->toBeGreaterThan(0);
+
+            expect(file_exists($absolutePath))->toBeTrue();
+        });
+    });
+
+    describe('Read Operations', function () {
+        it('delegates get to wrapped storage', function () {
+            $path = 'test.txt';
+            $content = 'test content';
+
+            // Write file directly via wrapped storage
+            $this->storage->put($path, $content);
+
+            // Read via cached storage
+            $result = $this->cachedStorage->get($path);
+
+            expect($result)->toBe($content);
+        });
+
+        it('throws FileNotFoundException for non-existent files', function () {
+            expect(fn() => $this->cachedStorage->get('nonexistent.txt'))
+                ->toThrow(FileNotFoundException::class);
+        });
+
+        it('checks file existence correctly', function () {
+            $path = 'exists.txt';
+
+            expect($this->cachedStorage->exists($path))->toBeFalse();
+
+            $this->cachedStorage->put($path, 'content');
+
+            expect($this->cachedStorage->exists($path))->toBeTrue();
+        });
+    });
+
+    describe('Write Operations', function () {
+        it('creates nested directories automatically', function () {
+            $path = 'deep/nested/structure/file.txt';
+            $content = 'nested content';
+
+            $this->cachedStorage->put($path, $content);
+
+            expect(file_exists($this->testDir . '/' . $path))->toBeTrue();
+            expect(file_get_contents($this->testDir . '/' . $path))->toBe($content);
+        });
+
+        it('overwrites existing files', function () {
+            $path = 'overwrite.txt';
+
+            $this->cachedStorage->put($path, 'original');
+            expect($this->cachedStorage->get($path))->toBe('original');
+
+            $this->cachedStorage->put($path, 'updated');
+            expect($this->cachedStorage->get($path))->toBe('updated');
+        });
+
+        it('handles empty content', function () {
+            $path = 'empty.txt';
+
+            $this->cachedStorage->put($path, '');
+
+            expect($this->cachedStorage->exists($path))->toBeTrue();
+            expect($this->cachedStorage->get($path))->toBe('');
+        });
+    });
+
+    describe('Copy Operations', function () {
+        it('copies files with directory cache optimization', function () {
+            $source = 'source.txt';
+            $destination = 'subdir/destination.txt';
+
+            // Create source file
+            $this->cachedStorage->put($source, 'copy this');
+
+            // Copy to nested directory (should cache destination directory)
+            $this->cachedStorage->copy($source, $destination);
+
+            expect($this->cachedStorage->exists($destination))->toBeTrue();
+            expect($this->cachedStorage->get($destination))->toBe('copy this');
+
+            $stats = $this->cachedStorage->getCacheStats();
+            expect($stats['cached_directories'])->toBeGreaterThan(0);
+        });
+
+        it('throws exception when copying non-existent file', function () {
+            expect(fn() => $this->cachedStorage->copy('nonexistent.txt', 'destination.txt'))
+                ->toThrow(FileNotFoundException::class);
+        });
+    });
+
+
+    describe('Delete Operations', function () {
+        it('deletes files', function () {
+            $path = 'delete-me.txt';
+
+            $this->cachedStorage->put($path, 'content');
+            expect($this->cachedStorage->exists($path))->toBeTrue();
+
+            $this->cachedStorage->delete($path);
+            expect($this->cachedStorage->exists($path))->toBeFalse();
+        });
+
+        it('throws exception when deleting non-existent file', function () {
+            expect(fn() => $this->cachedStorage->delete('nonexistent.txt'))
+                ->toThrow(FileNotFoundException::class);
+        });
+
+        it('keeps directory in cache after file deletion', function () {
+            $path = 'subdir/file.txt';
+
+            $this->cachedStorage->put($path, 'content');
+
+            $statsBefore = $this->cachedStorage->getCacheStats();
+            $cacheSizeBefore = $statsBefore['cached_directories'];
+
+            $this->cachedStorage->delete($path);
+
+            $statsAfter = $this->cachedStorage->getCacheStats();
+            $cacheSizeAfter = $statsAfter['cached_directories'];
+
+            // Directory should still be cached (still exists, just empty)
+            expect($cacheSizeAfter)->toBe($cacheSizeBefore);
+        });
+    });
+
+    describe('Metadata Operations', function () {
+        it('gets file size', function () {
+            $path = 'sized.txt';
+            $content = 'test content with size';
+
+            $this->cachedStorage->put($path, $content);
+
+            $size = $this->cachedStorage->size($path);
+
+            expect($size)->toBe(strlen($content));
+        });
+
+        it('gets last modified timestamp', function () {
+            $path = 'timestamped.txt';
+
+            $this->cachedStorage->put($path, 'content');
+
+            $lastModified = $this->cachedStorage->lastModified($path);
+
+            expect($lastModified)->toBeInt();
+            expect($lastModified)->toBeLessThanOrEqual(time());
+        });
+
+        it('gets MIME type', function () {
+            $path = 'file.txt';
+
+            $this->cachedStorage->put($path, 'text content');
+
+            $mimeType = $this->cachedStorage->getMimeType($path);
+
+            expect($mimeType)->toContain('text');
+        });
+
+    });
+
+    describe('Batch Operations', function () {
+        it('puts multiple files with directory cache optimization', function () {
+            $files = [
+                'batch1/file1.txt' => 'content1',
+                'batch1/file2.txt' => 'content2',
+                'batch2/file3.txt' => 'content3',
+            ];
+
+            $this->cachedStorage->putMultiple($files);
+
+            foreach ($files as $path => $content) {
+                expect($this->cachedStorage->exists($path))->toBeTrue();
+                expect($this->cachedStorage->get($path))->toBe($content);
+            }
+
+            $stats = $this->cachedStorage->getCacheStats();
+            expect($stats['cached_directories'])->toBeGreaterThan(0);
+        });
+
+        it('gets multiple files', function () {
+            $files = [
+                'multi1.txt' => 'content1',
+                'multi2.txt' => 'content2',
+                'multi3.txt' => 'content3',
+            ];
+
+            // Write files
+            $this->cachedStorage->putMultiple($files);
+
+            // Read in batch
+            $results = $this->cachedStorage->getMultiple(array_keys($files));
+
+            expect($results)->toBe($files);
+        });
+
+        it('gets metadata for multiple files', function () {
+            $files = [
+                'meta1.txt' => 'content1',
+                'meta2.txt' => 'content2',
+            ];
+
+            $this->cachedStorage->putMultiple($files);
+
+            $metadata = $this->cachedStorage->getMetadataMultiple(array_keys($files));
+
+            expect($metadata)->toHaveCount(2);
+            expect($metadata['meta1.txt']->size)->toBe(strlen('content1'));
+            expect($metadata['meta2.txt']->size)->toBe(strlen('content2'));
+        });
+    });
+
+    describe('Directory Listing', function () {
+        it('lists directory contents', function () {
+            $dir = 'listable';
+
+            $this->cachedStorage->put($dir . '/file1.txt', 'content1');
+            $this->cachedStorage->put($dir . '/file2.txt', 'content2');
+            $this->cachedStorage->put($dir . '/file3.txt', 'content3');
+
+            $contents = $this->cachedStorage->listDirectory($dir);
+
+            // listDirectory returns array with numeric keys and relative path values (including directory prefix)
+            expect($contents)->toHaveCount(3);
+
+            // Convert to simple array values for comparison
+            $files = array_values($contents);
+            expect($files)->toContain('listable/file1.txt');
+            expect($files)->toContain('listable/file2.txt');
+            expect($files)->toContain('listable/file3.txt');
+        });
+    });
+
+    describe('Cache Management', function () {
+        it('can clear directory cache', function () {
+            $this->cachedStorage->put('cached/file.txt', 'content');
+
+            $statsBefore = $this->cachedStorage->getCacheStats();
+            expect($statsBefore['cached_directories'])->toBeGreaterThan(0);
+
+            $this->cachedStorage->clearDirectoryCache();
+
+            $statsAfter = $this->cachedStorage->getCacheStats();
+            expect($statsAfter['cached_directories'])->toBe(0);
+        });
+
+        it('provides accurate cache statistics', function () {
+            $this->cachedStorage->put('level1/level2/file.txt', 'content');
+
+            $stats = $this->cachedStorage->getCacheStats();
+
+            expect($stats)->toHaveKeys(['cached_directories', 'cache_entries']);
+            expect($stats['cached_directories'])->toBeGreaterThan(0);
+            expect($stats['cache_entries'])->toBeArray();
+        });
+
+        it('checks if directory is cached', function () {
+            // Use relative path that will be resolved
+            $relativePath = 'cached_check/file.txt';
+
+            // Get the directory that will actually be cached
+            $cachedDir = $this->testDir . '/cached_check';
+
+            expect($this->cachedStorage->isDirectoryCached($cachedDir))->toBeFalse();
+
+            $this->cachedStorage->put($relativePath, 'content');
+
+            // After put, the directory should be cached
+            expect($this->cachedStorage->isDirectoryCached($cachedDir))->toBeTrue();
+        });
+    });
+
+    describe('Performance Characteristics', function () {
+        it('reduces directory checks for repeated writes', function () {
+            $dir = 'performance/test';
+
+            // First write creates and caches directory
+            $this->cachedStorage->put($dir . '/file1.txt', 'content1');
+
+            $statsBefore = $this->cachedStorage->getCacheStats();
+
+            // Subsequent writes reuse cached directory
+            for ($i = 2; $i <= 10; $i++) {
+                $this->cachedStorage->put($dir . "/file{$i}.txt", "content{$i}");
+            }
+
+            $statsAfter = $this->cachedStorage->getCacheStats();
+
+            // Cache size should not grow significantly (same directory)
+            expect($statsAfter['cached_directories'])->toBeLessThanOrEqual(
+                $statsBefore['cached_directories'] + 1
+            );
+        });
+    });
+});

tests/Unit/Framework/Filesystem/CachedFileValidatorTest.php

@@ -0,0 +1,358 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Filesystem\CachedFileValidator;
+use App\Framework\Filesystem\FileValidator;
+use App\Framework\Filesystem\Exceptions\FileValidationException;
+use App\Framework\Core\ValueObjects\FileSize;
+
+describe('CachedFileValidator', function () {
+    beforeEach(function () {
+        $this->validator = FileValidator::createDefault();
+        $this->cachedValidator = new CachedFileValidator(
+            validator: $this->validator,
+            cacheTtl: 60,
+            maxCacheSize: 10
+        );
+    });
+
+    describe('Path Validation Caching', function () {
+        it('caches successful path validation', function () {
+            $path = '/valid/path/file.txt';
+
+            // First call - cache miss
+            $this->cachedValidator->validatePath($path);
+
+            // Second call - cache hit (should not throw)
+            $this->cachedValidator->validatePath($path);
+
+            $stats = $this->cachedValidator->getCacheStats();
+            expect($stats['path_cache_size'])->toBe(1);
+        });
+
+        it('caches failed path validation', function () {
+            $invalidPath = '/path/with/../traversal';
+
+            // First call - cache miss, throws exception
+            try {
+                $this->cachedValidator->validatePath($invalidPath);
+                $this->fail('Expected FileValidationException');
+            } catch (FileValidationException $e) {
+                expect($e->getMessage())->toContain('Path traversal');
+            }
+
+            // Second call - cache hit, throws same exception
+            try {
+                $this->cachedValidator->validatePath($invalidPath);
+                $this->fail('Expected FileValidationException from cache');
+            } catch (FileValidationException $e) {
+                expect($e->getMessage())->toContain('Path traversal');
+            }
+
+            $stats = $this->cachedValidator->getCacheStats();
+            expect($stats['path_cache_size'])->toBe(1);
+        });
+
+        it('detects path traversal on first call and caches result', function () {
+            $traversalPath = '/etc/../passwd';
+
+            // Should throw on first call
+            expect(fn() => $this->cachedValidator->validatePath($traversalPath))
+                ->toThrow(FileValidationException::class);
+
+            // Should throw on second call (from cache)
+            expect(fn() => $this->cachedValidator->validatePath($traversalPath))
+                ->toThrow(FileValidationException::class);
+        });
+
+        it('detects null bytes and caches result', function () {
+            $nullBytePath = "/path/with\0nullbyte";
+
+            // Should throw on first call
+            expect(fn() => $this->cachedValidator->validatePath($nullBytePath))
+                ->toThrow(FileValidationException::class);
+
+            // Should throw on second call (from cache)
+            expect(fn() => $this->cachedValidator->validatePath($nullBytePath))
+                ->toThrow(FileValidationException::class);
+        });
+    });
+
+    describe('Extension Validation Caching', function () {
+        it('caches successful extension validation', function () {
+            $path = '/valid/path/file.txt';
+
+            // First call - cache miss
+            $this->cachedValidator->validateExtension($path);
+
+            // Second call - cache hit
+            $this->cachedValidator->validateExtension($path);
+
+            $stats = $this->cachedValidator->getCacheStats();
+            expect($stats['extension_cache_size'])->toBe(1);
+        });
+
+        it('caches failed extension validation', function () {
+            $strictValidator = FileValidator::createStrict(['json', 'txt']);
+            $cached = new CachedFileValidator($strictValidator);
+
+            $phpPath = '/path/file.php';
+
+            // First call - cache miss, throws exception
+            expect(fn() => $cached->validateExtension($phpPath))
+                ->toThrow(FileValidationException::class);
+
+            // Second call - cache hit, throws same exception
+            expect(fn() => $cached->validateExtension($phpPath))
+                ->toThrow(FileValidationException::class);
+
+            $stats = $cached->getCacheStats();
+            expect($stats['extension_cache_size'])->toBe(1);
+        });
+
+        it('validates different extensions separately', function () {
+            $this->cachedValidator->validateExtension('/file1.txt');
+            $this->cachedValidator->validateExtension('/file2.json');
+            $this->cachedValidator->validateExtension('/file3.csv');
+
+            $stats = $this->cachedValidator->getCacheStats();
+            expect($stats['extension_cache_size'])->toBe(3);
+        });
+    });
+
+    describe('LRU Cache Eviction', function () {
+        it('evicts oldest entry when cache is full', function () {
+            $cached = new CachedFileValidator(
+                validator: $this->validator,
+                maxCacheSize: 3
+            );
+
+            // Fill cache with 3 entries
+            $cached->validatePath('/path1');
+            $cached->validatePath('/path2');
+            $cached->validatePath('/path3');
+
+            $stats = $cached->getCacheStats();
+            expect($stats['path_cache_size'])->toBe(3);
+
+            // Add 4th entry - should evict oldest (/path1)
+            $cached->validatePath('/path4');
+
+            $stats = $cached->getCacheStats();
+            expect($stats['path_cache_size'])->toBe(3); // Still 3 (max size)
+        });
+
+        it('maintains LRU order on cache hit', function () {
+            $cached = new CachedFileValidator(
+                validator: $this->validator,
+                maxCacheSize: 3
+            );
+
+            // Fill cache
+            $cached->validatePath('/path1');
+            $cached->validatePath('/path2');
+            $cached->validatePath('/path3');
+
+            // Access /path1 again (should move to end)
+            $cached->validatePath('/path1');
+
+            // Add new entry - should evict /path2 (oldest)
+            $cached->validatePath('/path4');
+
+            $stats = $cached->getCacheStats();
+            expect($stats['path_cache_size'])->toBe(3);
+        });
+    });
+
+    describe('Cache TTL Expiration', function () {
+        it('expires cache entries after TTL', function () {
+            $cached = new CachedFileValidator(
+                validator: $this->validator,
+                cacheTtl: 1 // 1 second TTL
+            );
+
+            $path = '/valid/path.txt';
+
+            // Cache the validation
+            $cached->validatePath($path);
+
+            // Wait for TTL to expire
+            sleep(2);
+
+            // This should be a cache miss (expired)
+            $cached->validatePath($path);
+
+            // Cache should still have 1 entry (re-cached)
+            $stats = $cached->getCacheStats();
+            expect($stats['path_cache_size'])->toBe(1);
+        });
+    });
+
+    describe('Non-Cached Validations', function () {
+        it('does not cache file size validation', function () {
+            $fileSize = FileSize::fromBytes(1024);
+
+            // Multiple calls should not affect cache
+            $this->cachedValidator->validateFileSize($fileSize);
+            $this->cachedValidator->validateFileSize($fileSize);
+
+            $stats = $this->cachedValidator->getCacheStats();
+            expect($stats['path_cache_size'])->toBe(0);
+            expect($stats['extension_cache_size'])->toBe(0);
+        });
+
+        it('does not cache existence checks', function () {
+            // Create a temporary test file
+            $testFile = sys_get_temp_dir() . '/test_cached_validator_' . uniqid() . '.txt';
+            file_put_contents($testFile, 'test');
+
+            try {
+                $this->cachedValidator->validateExists($testFile);
+                $this->cachedValidator->validateExists($testFile);
+
+                $stats = $this->cachedValidator->getCacheStats();
+                expect($stats['path_cache_size'])->toBe(0);
+            } finally {
+                if (file_exists($testFile)) {
+                    unlink($testFile);
+                }
+            }
+        });
+
+        it('does not cache permission checks', function () {
+            // Use temp directory for permission test
+            $testDir = sys_get_temp_dir();
+
+            $this->cachedValidator->validateWritable($testDir);
+            $this->cachedValidator->validateWritable($testDir);
+
+            $stats = $this->cachedValidator->getCacheStats();
+            expect($stats['path_cache_size'])->toBe(0);
+        });
+    });
+
+    describe('Composite Validations', function () {
+        it('caches path and extension in validateUpload', function () {
+            $path = '/upload/file.jpg';
+            $fileSize = FileSize::fromBytes(1024);
+
+            $this->cachedValidator->validateUpload($path, $fileSize);
+
+            $stats = $this->cachedValidator->getCacheStats();
+            expect($stats['path_cache_size'])->toBe(1);
+            expect($stats['extension_cache_size'])->toBe(1);
+        });
+
+        it('caches path in validateRead', function () {
+            $testFile = sys_get_temp_dir() . '/test_read_' . uniqid() . '.txt';
+            file_put_contents($testFile, 'test');
+
+            try {
+                $this->cachedValidator->validateRead($testFile);
+
+                $stats = $this->cachedValidator->getCacheStats();
+                expect($stats['path_cache_size'])->toBe(1);
+            } finally {
+                if (file_exists($testFile)) {
+                    unlink($testFile);
+                }
+            }
+        });
+
+        it('caches path and extension in validateWrite', function () {
+            $testDir = sys_get_temp_dir() . '/test_write_dir_' . uniqid();
+            mkdir($testDir);
+
+            try {
+                $path = $testDir . '/file.txt';
+
+                $this->cachedValidator->validateWrite($path);
+
+                $stats = $this->cachedValidator->getCacheStats();
+                expect($stats['path_cache_size'])->toBe(1);
+                expect($stats['extension_cache_size'])->toBe(1);
+            } finally {
+                if (is_dir($testDir)) {
+                    rmdir($testDir);
+                }
+            }
+        });
+    });
+
+    describe('Cache Management', function () {
+        it('can clear all caches', function () {
+            $this->cachedValidator->validatePath('/path1');
+            $this->cachedValidator->validatePath('/path2');
+            $this->cachedValidator->validateExtension('/file.txt');
+
+            $statsBefore = $this->cachedValidator->getCacheStats();
+            expect($statsBefore['path_cache_size'])->toBe(2);
+            expect($statsBefore['extension_cache_size'])->toBe(1);
+
+            $this->cachedValidator->clearCache();
+
+            $statsAfter = $this->cachedValidator->getCacheStats();
+            expect($statsAfter['path_cache_size'])->toBe(0);
+            expect($statsAfter['extension_cache_size'])->toBe(0);
+        });
+
+        it('provides accurate cache statistics', function () {
+            $stats = $this->cachedValidator->getCacheStats();
+
+            expect($stats)->toHaveKeys([
+                'path_cache_size',
+                'extension_cache_size',
+                'max_cache_size',
+                'cache_ttl_seconds'
+            ]);
+
+            expect($stats['max_cache_size'])->toBe(10);
+            expect($stats['cache_ttl_seconds'])->toBe(60);
+        });
+    });
+
+    describe('Delegation Methods', function () {
+        it('delegates isExtensionAllowed to wrapped validator', function () {
+            expect($this->cachedValidator->isExtensionAllowed('txt'))->toBeTrue();
+            expect($this->cachedValidator->isExtensionAllowed('exe'))->toBeFalse();
+        });
+
+        it('delegates getAllowedExtensions to wrapped validator', function () {
+            $result = $this->cachedValidator->getAllowedExtensions();
+            expect($result)->toBeNull(); // Default validator has no whitelist
+        });
+
+        it('delegates getBlockedExtensions to wrapped validator', function () {
+            $result = $this->cachedValidator->getBlockedExtensions();
+            expect($result)->toBeArray();
+            expect($result)->toContain('exe');
+        });
+
+        it('delegates getMaxFileSize to wrapped validator', function () {
+            $result = $this->cachedValidator->getMaxFileSize();
+            expect($result)->toBeInstanceOf(FileSize::class);
+        });
+    });
+
+    describe('Performance Characteristics', function () {
+        it('maintains cache hits for repeated validations', function () {
+            $path = '/repeated/path/file.txt';
+
+            // First call - cache miss
+            $this->cachedValidator->validatePath($path);
+
+            $statsBefore = $this->cachedValidator->getCacheStats();
+            expect($statsBefore['path_cache_size'])->toBe(1);
+
+            // Repeated calls - cache hits
+            for ($i = 0; $i < 100; $i++) {
+                $this->cachedValidator->validatePath($path);
+            }
+
+            // Cache size should remain 1 (same path cached)
+            $statsAfter = $this->cachedValidator->getCacheStats();
+            expect($statsAfter['path_cache_size'])->toBe(1);
+        });
+    });
+});

tests/Unit/Framework/Filesystem/FileOperationContextLoggingTest.php

@@ -0,0 +1,340 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Core\ValueObjects\FileSize;
+use App\Framework\Filesystem\ValueObjects\FileOperationContext;
+use App\Framework\Filesystem\ValueObjects\FileOperation;
+
+describe('FileOperationContext Logging', function () {
+    // Severity Detection Tests
+    describe('Severity Detection', function () {
+        it('identifies high severity operations', function () {
+            $deleteContext = FileOperationContext::forOperation(
+                FileOperation::DELETE,
+                '/path/to/file.txt'
+            );
+
+            expect($deleteContext->isHighSeverity())->toBeTrue();
+            expect($deleteContext->toArray()['severity'])->toBe('high');
+
+            $moveContext = FileOperationContext::forOperationWithDestination(
+                FileOperation::MOVE,
+                '/source/file.txt',
+                '/dest/file.txt'
+            );
+
+            expect($moveContext->isHighSeverity())->toBeTrue();
+
+            $deleteDirContext = FileOperationContext::forOperation(
+                FileOperation::DELETE_DIRECTORY,
+                '/path/to/dir'
+            );
+
+            expect($deleteDirContext->isHighSeverity())->toBeTrue();
+        });
+
+        it('identifies medium severity operations', function () {
+            $writeContext = FileOperationContext::forWrite(
+                '/path/to/file.txt',
+                FileSize::fromBytes(1024)
+            );
+
+            expect($writeContext->isHighSeverity())->toBeFalse();
+            expect($writeContext->toArray()['severity'])->toBe('medium');
+
+            $copyContext = FileOperationContext::forOperationWithDestination(
+                FileOperation::COPY,
+                '/source/file.txt',
+                '/dest/file.txt'
+            );
+
+            expect($copyContext->toArray()['severity'])->toBe('medium');
+
+            $createDirContext = FileOperationContext::forOperation(
+                FileOperation::CREATE_DIRECTORY,
+                '/path/to/newdir'
+            );
+
+            expect($createDirContext->toArray()['severity'])->toBe('medium');
+        });
+
+        it('identifies low severity operations', function () {
+            $readContext = FileOperationContext::forRead(
+                '/path/to/file.txt',
+                FileSize::fromBytes(1024)
+            );
+
+            expect($readContext->isHighSeverity())->toBeFalse();
+            expect($readContext->toArray()['severity'])->toBe('low');
+
+            $listContext = FileOperationContext::forOperation(
+                FileOperation::LIST_DIRECTORY,
+                '/path/to/dir'
+            );
+
+            expect($listContext->toArray()['severity'])->toBe('low');
+
+            $metadataContext = FileOperationContext::forOperation(
+                FileOperation::GET_METADATA,
+                '/path/to/file.txt'
+            );
+
+            expect($metadataContext->toArray()['severity'])->toBe('low');
+        });
+    });
+
+    // Large Operation Detection Tests
+    describe('Large Operation Detection', function () {
+        it('identifies large operations (>10MB)', function () {
+            // 15MB operation - should be large
+            $largeWrite = FileOperationContext::forWrite(
+                '/path/to/large.txt',
+                FileSize::fromMegabytes(15)
+            );
+
+            expect($largeWrite->isLargeOperation())->toBeTrue();
+
+            // 50MB read - should be large
+            $largeRead = FileOperationContext::forRead(
+                '/path/to/huge.txt',
+                FileSize::fromMegabytes(50)
+            );
+
+            expect($largeRead->isLargeOperation())->toBeTrue();
+        });
+
+        it('does not identify small operations as large', function () {
+            // 1MB operation - should NOT be large
+            $smallWrite = FileOperationContext::forWrite(
+                '/path/to/small.txt',
+                FileSize::fromMegabytes(1)
+            );
+
+            expect($smallWrite->isLargeOperation())->toBeFalse();
+
+            // 5KB read - should NOT be large
+            $tinyRead = FileOperationContext::forRead(
+                '/path/to/tiny.txt',
+                FileSize::fromKilobytes(5)
+            );
+
+            expect($tinyRead->isLargeOperation())->toBeFalse();
+        });
+
+        it('returns false for operations without byte information', function () {
+            $deleteContext = FileOperationContext::forOperation(
+                FileOperation::DELETE,
+                '/path/to/file.txt'
+            );
+
+            expect($deleteContext->isLargeOperation())->toBeFalse();
+        });
+    });
+
+    // Context Data Completeness Tests
+    describe('Context Data Completeness', function () {
+        it('includes all relevant data in toArray()', function () {
+            $context = FileOperationContext::forWrite(
+                '/path/to/file.txt',
+                FileSize::fromKilobytes(150),
+                'user123'
+            );
+
+            $context = $context->withMetadata([
+                'source' => 'upload',
+                'mime_type' => 'text/plain'
+            ]);
+
+            $array = $context->toArray();
+
+            expect($array)->toHaveKey('operation');
+            expect($array)->toHaveKey('operation_name');
+            expect($array)->toHaveKey('path');
+            expect($array)->toHaveKey('timestamp');
+            expect($array)->toHaveKey('severity');
+            expect($array)->toHaveKey('bytes_affected');
+            expect($array)->toHaveKey('bytes_affected_human');
+            expect($array)->toHaveKey('user_id');
+            expect($array)->toHaveKey('metadata');
+
+            expect($array['operation'])->toBe('write');
+            expect($array['operation_name'])->toBe('file.write');
+            expect($array['path'])->toBe('/path/to/file.txt');
+            expect($array['severity'])->toBe('medium');
+            expect($array['bytes_affected'])->toBe(153600); // 150 * 1024
+            expect($array['bytes_affected_human'])->toBe('150 KB');  // toHumanReadable() returns without decimals
+            expect($array['user_id'])->toBe('user123');
+            expect($array['metadata'])->toBe([
+                'source' => 'upload',
+                'mime_type' => 'text/plain'
+            ]);
+        });
+
+        it('handles operation with destination', function () {
+            $context = FileOperationContext::forOperationWithDestination(
+                FileOperation::COPY,
+                '/source/file.txt',
+                '/dest/file.txt'
+            );
+
+            $array = $context->toArray();
+
+            expect($array)->toHaveKey('destination_path');
+            expect($array['destination_path'])->toBe('/dest/file.txt');
+            expect($array['path'])->toBe('/source/file.txt');
+        });
+
+        it('generates readable string representation', function () {
+            $context = FileOperationContext::forWrite(
+                '/var/www/uploads/document.pdf',
+                FileSize::fromKilobytes(250),
+                'admin'
+            );
+
+            $string = $context->toString();
+
+            expect($string)->toContain('Write file contents');
+            expect($string)->toContain('path: /var/www/uploads/document.pdf');
+            expect($string)->toContain('bytes: 250');  // Flexible - may be "250 KB" or "250.00 KB"
+            expect($string)->toContain('user: admin');
+        });
+    });
+
+    // Write Operation Detection Tests
+    describe('Write Operation Detection', function () {
+        it('correctly identifies write operations', function () {
+            $writeContext = FileOperationContext::forOperation(
+                FileOperation::WRITE,
+                '/path/to/file.txt'
+            );
+            expect($writeContext->isWriteOperation())->toBeTrue();
+
+            $deleteContext = FileOperationContext::forOperation(
+                FileOperation::DELETE,
+                '/path/to/file.txt'
+            );
+            expect($deleteContext->isWriteOperation())->toBeTrue();
+
+            $moveContext = FileOperationContext::forOperationWithDestination(
+                FileOperation::MOVE,
+                '/source.txt',
+                '/dest.txt'
+            );
+            expect($moveContext->isWriteOperation())->toBeTrue();
+        });
+
+        it('correctly identifies non-write operations', function () {
+            $readContext = FileOperationContext::forRead(
+                '/path/to/file.txt',
+                FileSize::fromBytes(100)
+            );
+            expect($readContext->isWriteOperation())->toBeFalse();
+
+            $copyContext = FileOperationContext::forOperationWithDestination(
+                FileOperation::COPY,
+                '/source.txt',
+                '/dest.txt'
+            );
+            expect($copyContext->isWriteOperation())->toBeFalse();
+        });
+    });
+
+    // Immutability Tests
+    describe('Immutability', function () {
+        it('withMetadata creates new instance', function () {
+            $original = FileOperationContext::forOperation(
+                FileOperation::WRITE,
+                '/path/to/file.txt'
+            );
+
+            $modified = $original->withMetadata(['key' => 'value']);
+
+            expect($original->metadata)->toBeNull();
+            expect($modified->metadata)->toBe(['key' => 'value']);
+            expect($original)->not->toBe($modified);
+        });
+
+        it('withUserId creates new instance', function () {
+            $original = FileOperationContext::forOperation(
+                FileOperation::DELETE,
+                '/path/to/file.txt'
+            );
+
+            $modified = $original->withUserId('user456');
+
+            expect($original->userId)->toBeNull();
+            expect($modified->userId)->toBe('user456');
+            expect($original)->not->toBe($modified);
+        });
+
+        it('withMetadata merges with existing metadata', function () {
+            $context = FileOperationContext::forOperation(
+                FileOperation::WRITE,
+                '/file.txt'
+            );
+
+            $context = $context->withMetadata(['a' => 1]);
+            $context = $context->withMetadata(['b' => 2]);
+
+            expect($context->metadata)->toBe(['a' => 1, 'b' => 2]);
+        });
+    });
+
+    // Factory Method Tests
+    describe('Factory Methods', function () {
+        it('creates context for simple operations', function () {
+            $context = FileOperationContext::forOperation(
+                FileOperation::DELETE,
+                '/path/to/file.txt'
+            );
+
+            expect($context->operation)->toBe(FileOperation::DELETE);
+            expect($context->path)->toBe('/path/to/file.txt');
+            expect($context->timestamp)->not->toBeNull();
+            expect($context->destinationPath)->toBeNull();
+            expect($context->bytesAffected)->toBeNull();
+        });
+
+        it('creates context for operations with destination', function () {
+            $context = FileOperationContext::forOperationWithDestination(
+                FileOperation::MOVE,
+                '/source/file.txt',
+                '/dest/file.txt'
+            );
+
+            expect($context->operation)->toBe(FileOperation::MOVE);
+            expect($context->path)->toBe('/source/file.txt');
+            expect($context->destinationPath)->toBe('/dest/file.txt');
+            expect($context->timestamp)->not->toBeNull();
+        });
+
+        it('creates context for write operations', function () {
+            $context = FileOperationContext::forWrite(
+                '/path/to/file.txt',
+                FileSize::fromKilobytes(100),
+                'user789'
+            );
+
+            expect($context->operation)->toBe(FileOperation::WRITE);
+            expect($context->path)->toBe('/path/to/file.txt');
+            expect($context->bytesAffected)->toBeInstanceOf(FileSize::class);
+            expect($context->bytesAffected->toBytes())->toBe(102400);
+            expect($context->userId)->toBe('user789');
+            expect($context->timestamp)->not->toBeNull();
+        });
+
+        it('creates context for read operations', function () {
+            $context = FileOperationContext::forRead(
+                '/path/to/file.txt',
+                FileSize::fromMegabytes(5)
+            );
+
+            expect($context->operation)->toBe(FileOperation::READ);
+            expect($context->path)->toBe('/path/to/file.txt');
+            expect($context->bytesAffected)->toBeInstanceOf(FileSize::class);
+            expect($context->bytesAffected->toMegabytes())->toBe(5.0);
+            expect($context->timestamp)->not->toBeNull();
+        });
+    });
+});

tests/Unit/Framework/Filesystem/FileStorageIntegrationTest.php

@@ -0,0 +1,283 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Core\ValueObjects\FileSize;
+use App\Framework\Filesystem\FileStorage;
+use App\Framework\Filesystem\FileValidator;
+use App\Framework\Filesystem\Exceptions\FileValidationException;
+use App\Framework\Filesystem\Exceptions\FileNotFoundException;
+
+describe('FileStorage Integration', function () {
+    beforeEach(function () {
+        // Create temp directory for tests
+        $this->testDir = sys_get_temp_dir() . '/filesystem_test_' . uniqid();
+        mkdir($this->testDir, 0777, true);
+    });
+
+    afterEach(function () {
+        // Clean up temp directory
+        if (is_dir($this->testDir)) {
+            $files = glob($this->testDir . '/*');
+            foreach ($files as $file) {
+                if (is_file($file)) {
+                    unlink($file);
+                }
+            }
+            rmdir($this->testDir);
+        }
+    });
+
+    // Storage without Validator or Logger
+    it('works without validator or logger', function () {
+        $storage = new FileStorage($this->testDir);
+
+        $storage->put('test.txt', 'Hello World');
+        $content = $storage->get('test.txt');
+
+        expect($content)->toBe('Hello World');
+        expect($storage->exists('test.txt'))->toBeTrue();
+    });
+
+    // Storage with FileValidator integration
+    it('validates path traversal attempts with validator', function () {
+        $validator = FileValidator::createDefault();
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        try {
+            $storage->get('../../../etc/passwd');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('Path traversal');
+        }
+    });
+
+    it('validates file extensions with validator on write', function () {
+        $validator = FileValidator::createStrict(['txt', 'json']);
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        // Allowed extension should work
+        $storage->put('allowed.txt', 'content');
+        expect($storage->exists('allowed.txt'))->toBeTrue();
+
+        // Disallowed extension should fail
+        try {
+            $storage->put('blocked.exe', 'malicious');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('not allowed');
+        }
+    });
+
+    it('validates file size with validator on write', function () {
+        $validator = FileValidator::forUploads(FileSize::fromKilobytes(1)); // 1KB limit
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        // Small file should work
+        $storage->put('small.txt', 'Small content');
+        expect($storage->exists('small.txt'))->toBeTrue();
+
+        // Large file should fail
+        $largeContent = str_repeat('X', 2048); // 2KB
+        try {
+            $storage->put('large.txt', $largeContent);
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('exceeds maximum');
+        }
+    });
+
+    // Note: validateRead() does not validate extensions by design
+    // Extensions are validated on write operations only
+    // This is the correct behavior - when reading files, extension doesn't matter
+
+    // Edge cases
+    it('handles nonexistent files with validator', function () {
+        $validator = FileValidator::createDefault();
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        try {
+            $storage->get('nonexistent.txt');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileNotFoundException $e) {
+            expect($e)->toBeInstanceOf(FileNotFoundException::class);
+        }
+    });
+
+    it('validates before attempting file operations', function () {
+        $validator = FileValidator::forUploads();
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        // Path traversal should fail validation before attempting filesystem operation
+        try {
+            $storage->put('../../../tmp/malicious.txt', 'content');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('Path traversal');
+        }
+
+        // Verify file was NOT created (path traversal prevented)
+        expect(file_exists($this->testDir . '/../../../tmp/malicious.txt'))->toBeFalse();
+    });
+
+    // Performance: Large file handling
+    it('handles large files efficiently', function () {
+        $validator = FileValidator::forUploads(FileSize::fromMegabytes(10));
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        // Create 1MB file
+        $largeContent = str_repeat('X', 1024 * 1024);
+        $storage->put('large.txt', $largeContent);
+
+        $content = $storage->get('large.txt');
+        expect(strlen($content))->toBe(1024 * 1024);
+    });
+
+    // Multiple operations workflow
+    it('handles complete file lifecycle with validation', function () {
+        $validator = FileValidator::createStrict(['txt', 'json']);
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        // Create
+        $storage->put('lifecycle.txt', 'initial content');
+        expect($storage->exists('lifecycle.txt'))->toBeTrue();
+
+        // Read
+        $content = $storage->get('lifecycle.txt');
+        expect($content)->toBe('initial content');
+
+        // Update
+        $storage->put('lifecycle.txt', 'updated content');
+        $updatedContent = $storage->get('lifecycle.txt');
+        expect($updatedContent)->toBe('updated content');
+
+        // Copy
+        $storage->copy('lifecycle.txt', 'lifecycle-copy.txt');
+        expect($storage->exists('lifecycle-copy.txt'))->toBeTrue();
+
+        // Delete
+        $storage->delete('lifecycle.txt');
+        expect($storage->exists('lifecycle.txt'))->toBeFalse();
+
+        // Copy still exists
+        expect($storage->exists('lifecycle-copy.txt'))->toBeTrue();
+    });
+
+    // Validator prevents invalid operations
+    it('prevents path traversal on read operations', function () {
+        $validator = FileValidator::createDefault();
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        try {
+            $storage->get('../../sensitive/file.txt');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('Path traversal');
+        }
+    });
+
+    it('prevents path traversal on copy operations', function () {
+        $validator = FileValidator::createDefault();
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        $storage->put('source.txt', 'content');
+
+        try {
+            $storage->copy('source.txt', '../../../etc/target.txt');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('Path traversal');
+        }
+    });
+
+    it('prevents path traversal on delete operations', function () {
+        $validator = FileValidator::createDefault();
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        try {
+            $storage->delete('../../../important/file.txt');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('Path traversal');
+        }
+    });
+
+    // URL-encoded path traversal prevention
+    it('prevents URL-encoded path traversal attacks', function () {
+        $validator = FileValidator::createDefault();
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        try {
+            $storage->put('%2e%2e/%2e%2e/malicious.txt', 'content');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('Path traversal');
+        }
+    });
+
+    // Multiple validator configurations
+    it('enforces strict whitelist validation', function () {
+        $validator = FileValidator::createStrict(['txt']);
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        // Only .txt should work
+        $storage->put('allowed.txt', 'content');
+        expect($storage->exists('allowed.txt'))->toBeTrue();
+
+        // Everything else should fail
+        $blocked = ['file.json', 'file.pdf', 'file.exe', 'file.jpg'];
+
+        foreach ($blocked as $filename) {
+            try {
+                $storage->put($filename, 'content');
+                expect(true)->toBeFalse("Should have blocked {$filename}");
+            } catch (FileValidationException $e) {
+                expect($e->getMessage())->toContain('not allowed');
+            }
+        }
+    });
+
+    // Image validator integration
+    it('works with image validator', function () {
+        $validator = FileValidator::forImages();
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        // Image extensions should work
+        $allowedImages = ['photo.jpg', 'image.png', 'graphic.gif', 'icon.webp'];
+
+        foreach ($allowedImages as $filename) {
+            $storage->put($filename, 'fake image data');
+            expect($storage->exists($filename))->toBeTrue();
+        }
+
+        // Non-image should fail
+        try {
+            $storage->put('document.pdf', 'content');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('not allowed');
+        }
+    });
+
+    // Upload validator integration
+    it('works with upload validator', function () {
+        $validator = FileValidator::forUploads();
+        $storage = new FileStorage($this->testDir, validator: $validator);
+
+        // Common upload types should work
+        $allowedFiles = ['data.json', 'report.pdf', 'document.txt', 'data.csv'];
+
+        foreach ($allowedFiles as $filename) {
+            $storage->put($filename, 'content');
+            expect($storage->exists($filename))->toBeTrue();
+        }
+
+        // Executable should fail
+        try {
+            $storage->put('malware.exe', 'malicious');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('not allowed');
+        }
+    });
+});

tests/Unit/Framework/Filesystem/FileValidatorTest.php

@@ -0,0 +1,293 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Core\ValueObjects\FileSize;
+use App\Framework\Filesystem\FileValidator;
+use App\Framework\Filesystem\Exceptions\FileValidationException;
+
+describe('FileValidator', function () {
+    // Factory Methods Tests
+    it('creates default validator with safe defaults', function () {
+        $validator = FileValidator::createDefault();
+
+        expect($validator->getAllowedExtensions())->toBeNull();
+        expect($validator->getBlockedExtensions())->toBe(['exe', 'bat', 'sh', 'cmd', 'com']);
+        expect($validator->getMaxFileSize())->toBeInstanceOf(FileSize::class);
+        expect($validator->getMaxFileSize()->toBytes())->toBe(100 * 1024 * 1024); // 100MB
+    });
+
+    it('creates strict validator with allowed extensions only', function () {
+        $validator = FileValidator::createStrict(['txt', 'pdf']);
+
+        expect($validator->getAllowedExtensions())->toBe(['txt', 'pdf']);
+        expect($validator->getBlockedExtensions())->toBeNull();
+        expect($validator->getMaxFileSize()->toBytes())->toBe(50 * 1024 * 1024); // 50MB
+    });
+
+    it('creates upload validator with secure defaults', function () {
+        $validator = FileValidator::forUploads();
+
+        expect($validator->getAllowedExtensions())->toBe(['jpg', 'jpeg', 'png', 'gif', 'pdf', 'txt', 'csv', 'json']);
+        expect($validator->getBlockedExtensions())->toBe(['exe', 'bat', 'sh', 'cmd', 'com', 'php', 'phtml']);
+        expect($validator->getMaxFileSize()->toBytes())->toBe(10 * 1024 * 1024); // 10MB
+    });
+
+    it('creates image validator with image extensions only', function () {
+        $validator = FileValidator::forImages();
+
+        expect($validator->getAllowedExtensions())->toBe(['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg']);
+        expect($validator->getBlockedExtensions())->toBeNull();
+        expect($validator->getMaxFileSize()->toBytes())->toBe(5 * 1024 * 1024); // 5MB
+    });
+
+    it('allows custom max size for uploads', function () {
+        $customSize = FileSize::fromMegabytes(20);
+        $validator = FileValidator::forUploads($customSize);
+
+        expect($validator->getMaxFileSize()->toBytes())->toBe(20 * 1024 * 1024);
+    });
+
+    // Path Validation Tests
+    it('validates normal file paths', function () {
+        $validator = FileValidator::createDefault();
+
+        $validator->validatePath('/var/www/html/test.txt');
+        $validator->validatePath('relative/path/file.json');
+
+        expect(true)->toBeTrue(); // No exception thrown
+    });
+
+    it('throws exception for empty path', function () {
+        $validator = FileValidator::createDefault();
+
+        try {
+            $validator->validatePath('');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('File path cannot be empty');
+        }
+    });
+
+    it('throws exception for path with null bytes', function () {
+        $validator = FileValidator::createDefault();
+
+        try {
+            $validator->validatePath("/path/to/file\0.txt");
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('null bytes');
+        }
+    });
+
+    it('detects path traversal with ../', function () {
+        $validator = FileValidator::createDefault();
+
+        try {
+            $validator->validatePath('../../../etc/passwd');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('Path traversal attempt');
+        }
+    });
+
+    it('detects path traversal with backslash notation', function () {
+        $validator = FileValidator::createDefault();
+
+        try {
+            $validator->validatePath('..\\..\\windows\\system32');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('Path traversal attempt');
+        }
+    });
+
+    it('detects URL-encoded path traversal', function () {
+        $validator = FileValidator::createDefault();
+
+        try {
+            $validator->validatePath('/path/%2e%2e/etc/passwd');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('Path traversal attempt');
+        }
+    });
+
+    // Extension Validation Tests
+    it('validates allowed extensions', function () {
+        $validator = FileValidator::createStrict(['txt', 'pdf']);
+
+        $validator->validateExtension('/path/to/file.txt');
+        $validator->validateExtension('/path/to/document.pdf');
+
+        expect(true)->toBeTrue(); // No exception thrown
+    });
+
+    it('throws exception for disallowed extension', function () {
+        $validator = FileValidator::createStrict(['txt', 'pdf']);
+
+        try {
+            $validator->validateExtension('/path/to/file.exe');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('not allowed');
+        }
+    });
+
+    it('throws exception for blocked extension', function () {
+        $validator = FileValidator::createDefault();
+
+        try {
+            $validator->validateExtension('/path/to/malware.exe');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('is blocked');
+        }
+    });
+
+    it('allows files without extension when no whitelist defined', function () {
+        $validator = FileValidator::createDefault();
+
+        $validator->validateExtension('/path/to/Makefile');
+
+        expect(true)->toBeTrue(); // No exception thrown
+    });
+
+    it('throws exception for files without extension when whitelist defined', function () {
+        $validator = FileValidator::createStrict(['txt', 'pdf']);
+
+        try {
+            $validator->validateExtension('/path/to/Makefile');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('no extension');
+        }
+    });
+
+    it('handles case-insensitive extension validation', function () {
+        $validator = FileValidator::createStrict(['txt', 'pdf']);
+
+        $validator->validateExtension('/path/to/file.TXT');
+        $validator->validateExtension('/path/to/document.PDF');
+
+        expect(true)->toBeTrue(); // No exception thrown
+    });
+
+    // FileSize Validation Tests
+    it('validates file size within limit', function () {
+        $validator = FileValidator::forUploads(FileSize::fromMegabytes(10));
+
+        $validator->validateFileSize(FileSize::fromMegabytes(5));
+        $validator->validateFileSize(FileSize::fromMegabytes(9));
+
+        expect(true)->toBeTrue(); // No exception thrown
+    });
+
+    it('throws exception when file size exceeds limit', function () {
+        $validator = FileValidator::forUploads(FileSize::fromMegabytes(10));
+
+        try {
+            $validator->validateFileSize(FileSize::fromMegabytes(15));
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('exceeds maximum allowed size');
+        }
+    });
+
+    it('allows any file size when no limit defined', function () {
+        $validator = new FileValidator(
+            allowedExtensions: null,
+            blockedExtensions: null,
+            maxFileSize: null,
+            baseDirectory: null
+        );
+
+        $validator->validateFileSize(FileSize::fromGigabytes(10));
+
+        expect(true)->toBeTrue(); // No exception thrown
+    });
+
+    // Extension Check Helper Tests
+    it('checks if extension is allowed', function () {
+        $validator = FileValidator::createStrict(['txt', 'pdf']);
+
+        expect($validator->isExtensionAllowed('txt'))->toBeTrue();
+        expect($validator->isExtensionAllowed('.pdf'))->toBeTrue(); // With dot
+        expect($validator->isExtensionAllowed('TXT'))->toBeTrue(); // Case insensitive
+        expect($validator->isExtensionAllowed('exe'))->toBeFalse();
+    });
+
+    it('checks blocked extensions correctly', function () {
+        $validator = FileValidator::createDefault();
+
+        expect($validator->isExtensionAllowed('exe'))->toBeFalse();
+        expect($validator->isExtensionAllowed('txt'))->toBeTrue();
+        expect($validator->isExtensionAllowed('pdf'))->toBeTrue();
+    });
+
+    it('allows all extensions when no restrictions', function () {
+        $validator = new FileValidator();
+
+        expect($validator->isExtensionAllowed('exe'))->toBeTrue();
+        expect($validator->isExtensionAllowed('anything'))->toBeTrue();
+    });
+
+    // Composite Validation Tests
+    it('validates upload with all checks', function () {
+        $validator = FileValidator::forUploads();
+
+        $validator->validateUpload('/path/to/image.jpg', FileSize::fromMegabytes(2));
+
+        expect(true)->toBeTrue(); // No exception thrown
+    });
+
+    it('composite upload validation catches path traversal', function () {
+        $validator = FileValidator::forUploads();
+
+        try {
+            $validator->validateUpload('../../../etc/passwd.jpg', FileSize::fromMegabytes(1));
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('Path traversal');
+        }
+    });
+
+    it('composite upload validation catches disallowed extension', function () {
+        $validator = FileValidator::forUploads();
+
+        try {
+            $validator->validateUpload('/path/to/script.php', FileSize::fromMegabytes(1));
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('is not allowed');
+        }
+    });
+
+    it('composite upload validation catches oversized file', function () {
+        $validator = FileValidator::forUploads();
+
+        try {
+            $validator->validateUpload('/path/to/image.jpg', FileSize::fromMegabytes(50));
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (FileValidationException $e) {
+            expect($e->getMessage())->toContain('exceeds maximum');
+        }
+    });
+
+    // Getter Tests
+    it('provides access to configuration', function () {
+        $allowedExtensions = ['txt', 'pdf'];
+        $blockedExtensions = ['exe', 'bat'];
+        $maxSize = FileSize::fromMegabytes(20);
+
+        $validator = new FileValidator(
+            allowedExtensions: $allowedExtensions,
+            blockedExtensions: $blockedExtensions,
+            maxFileSize: $maxSize
+        );
+
+        expect($validator->getAllowedExtensions())->toBe($allowedExtensions);
+        expect($validator->getBlockedExtensions())->toBe($blockedExtensions);
+        expect($validator->getMaxFileSize())->toBe($maxSize);
+    });
+});

tests/Unit/Framework/Filesystem/SerializerRegistryTest.php

@@ -0,0 +1,217 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Filesystem\SerializerRegistry;
+use App\Framework\Filesystem\Serializers\JsonSerializer;
+use App\Framework\Filesystem\Serializers\CsvSerializer;
+use App\Framework\Filesystem\Serializers\PhpSerializer;
+use App\Framework\Filesystem\Exceptions\SerializerNotFoundException;
+
+describe('SerializerRegistry', function () {
+    it('can register serializers', function () {
+        $registry = new SerializerRegistry();
+        $jsonSerializer = new JsonSerializer();
+
+        $registry->register('json', $jsonSerializer);
+
+        expect($registry->has('json'))->toBeTrue();
+        expect($registry->get('json'))->toBe($jsonSerializer);
+    });
+
+    it('can set default serializer', function () {
+        $registry = new SerializerRegistry();
+        $jsonSerializer = new JsonSerializer();
+
+        $registry->register('json', $jsonSerializer, setAsDefault: true);
+
+        expect($registry->hasDefault())->toBeTrue();
+        expect($registry->getDefault())->toBe($jsonSerializer);
+    });
+
+    it('can get serializer by extension', function () {
+        $registry = new SerializerRegistry();
+        $jsonSerializer = new JsonSerializer();
+
+        $registry->register('json', $jsonSerializer);
+
+        $serializer = $registry->getByExtension('json');
+        expect($serializer)->toBe($jsonSerializer);
+    });
+
+    it('throws exception when serializer not found by name', function () {
+        $registry = new SerializerRegistry();
+
+        try {
+            $registry->get('nonexistent');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (SerializerNotFoundException $e) {
+            expect($e)->toBeInstanceOf(SerializerNotFoundException::class);
+        }
+    });
+
+    it('throws exception when serializer not found by extension', function () {
+        $registry = new SerializerRegistry();
+
+        try {
+            $registry->getByExtension('xyz');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (SerializerNotFoundException $e) {
+            expect($e)->toBeInstanceOf(SerializerNotFoundException::class);
+        }
+    });
+
+    it('throws exception when no default serializer set', function () {
+        $registry = new SerializerRegistry();
+
+        try {
+            $registry->getDefault();
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (SerializerNotFoundException $e) {
+            expect($e)->toBeInstanceOf(SerializerNotFoundException::class);
+        }
+    });
+
+    it('can detect serializer from file path', function () {
+        $registry = new SerializerRegistry();
+        $jsonSerializer = new JsonSerializer();
+
+        $registry->register('json', $jsonSerializer);
+
+        $detected = $registry->detectFromPath('/path/to/file.json');
+        expect($detected)->toBe($jsonSerializer);
+    });
+
+    it('throws exception when detecting from path without extension', function () {
+        $registry = new SerializerRegistry();
+
+        try {
+            $registry->detectFromPath('/path/to/file');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (SerializerNotFoundException $e) {
+            expect($e)->toBeInstanceOf(SerializerNotFoundException::class);
+        }
+    });
+
+    it('can get serializer by MIME type', function () {
+        $registry = new SerializerRegistry();
+        $jsonSerializer = new JsonSerializer();
+
+        $registry->register('json', $jsonSerializer);
+
+        $serializer = $registry->getByMimeType('application/json');
+        expect($serializer)->toBe($jsonSerializer);
+    });
+
+    it('throws exception when MIME type not found', function () {
+        $registry = new SerializerRegistry();
+
+        try {
+            $registry->getByMimeType('application/unknown');
+            expect(true)->toBeFalse('Should have thrown exception');
+        } catch (SerializerNotFoundException $e) {
+            expect($e)->toBeInstanceOf(SerializerNotFoundException::class);
+        }
+    });
+
+    it('can list all registered serializers', function () {
+        $registry = new SerializerRegistry();
+        $jsonSerializer = new JsonSerializer();
+        $csvSerializer = new CsvSerializer();
+
+        $registry->register('json', $jsonSerializer);
+        $registry->register('csv', $csvSerializer);
+
+        $serializers = $registry->all();
+
+        expect($serializers)->toHaveCount(2);
+        expect($serializers['json'])->toBe($jsonSerializer);
+        expect($serializers['csv'])->toBe($csvSerializer);
+    });
+
+    it('can get registered serializer names', function () {
+        $registry = new SerializerRegistry();
+        $jsonSerializer = new JsonSerializer();
+        $csvSerializer = new CsvSerializer();
+
+        $registry->register('json', $jsonSerializer);
+        $registry->register('csv', $csvSerializer);
+
+        $names = $registry->getSerializerNames();
+
+        expect($names)->toHaveCount(2);
+        expect($names)->toContain('json');
+        expect($names)->toContain('csv');
+    });
+
+    it('can get statistics', function () {
+        $registry = new SerializerRegistry();
+        $jsonSerializer = new JsonSerializer();
+        $csvSerializer = new CsvSerializer();
+
+        $registry->register('json', $jsonSerializer, setAsDefault: true);
+        $registry->register('csv', $csvSerializer);
+
+        $stats = $registry->getStats();
+
+        expect($stats['total_serializers'])->toBe(2);
+        expect($stats['default_serializer'])->toBe('json');
+        expect($stats['supported_extensions'])->toHaveCount(2);
+        expect($stats['supported_extensions'])->toContain('json');
+        expect($stats['supported_extensions'])->toContain('csv');
+    });
+
+    it('creates default registry with common serializers', function () {
+        $registry = SerializerRegistry::createDefault();
+
+        expect($registry->has('json'))->toBeTrue();
+        expect($registry->has('csv'))->toBeTrue();
+        expect($registry->has('php'))->toBeTrue();
+        expect($registry->hasDefault())->toBeTrue();
+        expect($registry->getDefault())->toBeInstanceOf(JsonSerializer::class);
+    });
+
+    it('automatically maps extensions and MIME types on registration', function () {
+        $registry = new SerializerRegistry();
+        $jsonSerializer = new JsonSerializer();
+
+        $registry->register('json', $jsonSerializer);
+
+        // Extension mapping
+        expect($registry->getByExtension('json'))->toBe($jsonSerializer);
+
+        // MIME type mapping
+        expect($registry->getByMimeType('application/json'))->toBe($jsonSerializer);
+    });
+
+    it('overrides default serializer when set multiple times', function () {
+        $registry = new SerializerRegistry();
+        $jsonSerializer = new JsonSerializer();
+        $csvSerializer = new CsvSerializer();
+
+        $registry->register('json', $jsonSerializer, setAsDefault: true);
+        $registry->register('csv', $csvSerializer, setAsDefault: true);
+
+        expect($registry->getDefault())->toBe($csvSerializer);
+    });
+
+    it('detects serializer from path with multiple dots', function () {
+        $registry = new SerializerRegistry();
+        $jsonSerializer = new JsonSerializer();
+
+        $registry->register('json', $jsonSerializer);
+
+        $detected = $registry->detectFromPath('/path/to/file.backup.json');
+        expect($detected)->toBe($jsonSerializer);
+    });
+
+    it('handles case-insensitive extension detection', function () {
+        $registry = new SerializerRegistry();
+        $jsonSerializer = new JsonSerializer();
+
+        $registry->register('json', $jsonSerializer);
+
+        $detected = $registry->detectFromPath('/path/to/file.JSON');
+        expect($detected)->toBe($jsonSerializer);
+    });
+});

tests/Unit/Framework/Filesystem/TemporaryDirectoryTest.php

@@ -0,0 +1,245 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Filesystem\ValueObjects\FilePath;
+use App\Framework\Filesystem\TemporaryDirectory;
+use App\Framework\Exception\FrameworkException;
+
+describe('TemporaryDirectory', function () {
+    it('creates temporary directory with default name', function () {
+        $temp = TemporaryDirectory::make()->create();
+
+        expect($temp->exists())->toBeTrue();
+        expect($temp->getPath()->isDirectory())->toBeTrue();
+
+        // Cleanup
+        $temp->delete();
+    });
+
+    it('creates temporary directory with custom name', function () {
+        $temp = TemporaryDirectory::make()
+            ->name('my-custom-temp')
+            ->create();
+
+        $path = $temp->getPath();
+
+        expect($path->getFilename())->toBe('my-custom-temp');
+        expect($temp->exists())->toBeTrue();
+
+        $temp->delete();
+    });
+
+    it('creates temporary directory in custom location', function () {
+        $customLocation = FilePath::tempDir()->join('custom-temp-location');
+
+        if (!$customLocation->isDirectory()) {
+            mkdir($customLocation->toString(), 0755, true);
+        }
+
+        $temp = TemporaryDirectory::make()
+            ->location($customLocation)
+            ->name('nested-temp')
+            ->create();
+
+        expect($temp->exists())->toBeTrue();
+        expect($temp->getPath()->toString())->toContain('custom-temp-location');
+
+        $temp->delete();
+        rmdir($customLocation->toString());
+    });
+
+    it('sanitizes directory names', function () {
+        $temp = TemporaryDirectory::make()
+            ->name('my/dangerous\\name:with*symbols')
+            ->create();
+
+        $filename = $temp->getPath()->getFilename();
+
+        expect($filename)->not->toContain('/');
+        expect($filename)->not->toContain('\\');
+        expect($filename)->not->toContain(':');
+        expect($filename)->not->toContain('*');
+
+        $temp->delete();
+    });
+
+    it('throws exception when directory exists without force', function () {
+        $temp = TemporaryDirectory::make()
+            ->name('existing-dir')
+            ->create();
+
+        expect(fn () => TemporaryDirectory::make()
+            ->name('existing-dir')
+            ->create()
+        )->toThrow(FrameworkException::class);
+
+        $temp->delete();
+    });
+
+    it('overwrites existing directory with force', function () {
+        $temp1 = TemporaryDirectory::make()
+            ->name('overwrite-test')
+            ->create();
+
+        // Create a file in the first directory
+        $testFile = $temp1->path('test.txt');
+        file_put_contents($testFile->toString(), 'test content');
+
+        $temp2 = TemporaryDirectory::make()
+            ->name('overwrite-test')
+            ->force()
+            ->create();
+
+        // File should be gone
+        expect($testFile->exists())->toBeFalse();
+        expect($temp2->exists())->toBeTrue();
+
+        $temp2->delete();
+    });
+
+    it('returns FilePath for files in directory', function () {
+        $temp = TemporaryDirectory::make()->create();
+
+        $filePath = $temp->path('subdir/file.txt');
+
+        expect($filePath)->toBeInstanceOf(FilePath::class);
+        expect($filePath->toString())->toContain('subdir');
+        expect($filePath->toString())->toContain('file.txt');
+
+        $temp->delete();
+    });
+
+    it('empties directory without deleting it', function () {
+        $temp = TemporaryDirectory::make()->create();
+
+        // Create some files
+        file_put_contents($temp->path('file1.txt')->toString(), 'content1');
+        file_put_contents($temp->path('file2.txt')->toString(), 'content2');
+        mkdir($temp->path('subdir')->toString());
+        file_put_contents($temp->path('subdir/file3.txt')->toString(), 'content3');
+
+        $temp->empty();
+
+        // Directory should still exist
+        expect($temp->exists())->toBeTrue();
+
+        // But should be empty
+        $items = iterator_to_array(new \FilesystemIterator($temp->getPath()->toString()));
+        expect($items)->toHaveCount(0);
+
+        $temp->delete();
+    });
+
+    it('deletes directory and all contents', function () {
+        $temp = TemporaryDirectory::make()->create();
+        $path = $temp->getPath();
+
+        // Create nested structure
+        mkdir($temp->path('dir1')->toString());
+        mkdir($temp->path('dir1/dir2')->toString());
+        file_put_contents($temp->path('dir1/dir2/file.txt')->toString(), 'nested');
+
+        $result = $temp->delete();
+
+        expect($result)->toBeTrue();
+        expect($path->exists())->toBeFalse();
+    });
+
+    it('auto-deletes on destruct by default', function () {
+        $temp = TemporaryDirectory::make()->create();
+        $path = $temp->getPath();
+
+        expect($path->isDirectory())->toBeTrue();
+
+        // Explicitly trigger destruct and cleanup
+        $temp->delete();
+        unset($temp);
+
+        // Directory should be deleted
+        expect($path->exists())->toBeFalse();
+    });
+
+    it('does not auto-delete when disabled', function () {
+        $path = null;
+
+        {
+            $temp = TemporaryDirectory::make()
+                ->doNotDeleteWhenDestruct()
+                ->create();
+
+            $path = $temp->getPath();
+        } // $temp goes out of scope
+
+        // Directory should still exist
+        expect($path->isDirectory())->toBeTrue();
+
+        // Manual cleanup
+        rmdir($path->toString());
+    });
+
+    it('throws exception when accessing path before creation', function () {
+        $temp = TemporaryDirectory::make();
+
+        expect(fn () => $temp->path())->toThrow(FrameworkException::class);
+    });
+
+    it('handles special characters in filenames', function () {
+        $temp = TemporaryDirectory::make()
+            ->name('test with spaces and-dashes_underscores')
+            ->create();
+
+        $filename = $temp->getPath()->getFilename();
+
+        // Underscores are preserved, spaces become dashes
+        expect($filename)->toBe('test-with-spaces-and-dashes_underscores');
+
+        $temp->delete();
+    });
+
+    it('can chain method calls fluently', function () {
+        $temp = TemporaryDirectory::make()
+            ->name('fluent-test')
+            ->location(FilePath::tempDir())
+            ->force()
+            ->doNotDeleteWhenDestruct()
+            ->create();
+
+        expect($temp)->toBeInstanceOf(TemporaryDirectory::class);
+        expect($temp->exists())->toBeTrue();
+
+        $temp->delete();
+    });
+
+    it('deletes deeply nested structures', function () {
+        $temp = TemporaryDirectory::make()->create();
+
+        // Create deep nesting
+        $deepPath = $temp->path('a/b/c/d/e/f/g');
+        mkdir($deepPath->toString(), 0755, true);
+        file_put_contents($deepPath->join('file.txt')->toString(), 'deep content');
+
+        expect($deepPath->exists())->toBeTrue();
+
+        $temp->delete();
+
+        expect($temp->getPath()->exists())->toBeFalse();
+    });
+
+    it('returns false when deleting non-existent directory', function () {
+        $temp = TemporaryDirectory::make()->name('never-created');
+
+        $result = $temp->delete();
+
+        expect($result)->toBeFalse();
+    });
+
+    it('empty() does nothing on non-existent directory', function () {
+        $temp = TemporaryDirectory::make()->name('never-created');
+
+        // Should not throw
+        $result = $temp->empty();
+
+        expect($result)->toBeInstanceOf(TemporaryDirectory::class);
+    });
+});