feat(ai-edits): add output storage backfill flow and coverage

app/Console/Commands/AiEditsBackfillStorageCommand.php

@@ -0,0 +1,144 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Models\AiEditOutput;
+use App\Models\AiEditRequest;
+use App\Services\AiEditing\AiEditOutputStorageService;
+use Illuminate\Console\Command;
+use Illuminate\Database\Eloquent\Builder;
+
+class AiEditsBackfillStorageCommand extends Command
+{
+    protected $signature = 'ai-edits:backfill-storage
+        {--request-id= : Restrict backfill to one AI edit request id}
+        {--limit=200 : Maximum outputs to process}
+        {--pretend : Dry run without writing changes}';
+
+    protected $description = 'Backfill local storage paths for AI outputs that only have provider URLs.';
+
+    public function __construct(private readonly AiEditOutputStorageService $outputStorage)
+    {
+        parent::__construct();
+    }
+
+    public function handle(): int
+    {
+        $limit = max(1, (int) $this->option('limit'));
+        $requestId = $this->normalizeRequestId($this->option('request-id'));
+        $pretend = (bool) $this->option('pretend');
+
+        $query = AiEditOutput::query()
+            ->with('request')
+            ->whereNotNull('provider_url')
+            ->where(function (Builder $builder): void {
+                $builder
+                    ->whereNull('storage_path')
+                    ->orWhere('storage_path', '');
+            })
+            ->orderBy('id');
+
+        if ($requestId !== null) {
+            $query->where('request_id', $requestId);
+        }
+
+        $candidateCount = (clone $query)->count();
+        $outputs = $query->limit($limit)->get();
+
+        if ($outputs->isEmpty()) {
+            $this->info('No AI outputs require storage backfill.');
+
+            return self::SUCCESS;
+        }
+
+        $this->line(sprintf(
+            'AI output backfill candidates: %d (processing up to %d).',
+            $candidateCount,
+            $limit
+        ));
+
+        if ($pretend) {
+            $this->table(
+                ['Output ID', 'Request ID', 'Provider URL'],
+                $outputs->map(static fn (AiEditOutput $output): array => [
+                    (string) $output->id,
+                    (string) $output->request_id,
+                    (string) $output->provider_url,
+                ])->all()
+            );
+
+            $this->info('Pretend mode enabled. No records were changed.');
+
+            return self::SUCCESS;
+        }
+
+        $processed = 0;
+        $stored = 0;
+        $failed = 0;
+
+        foreach ($outputs as $output) {
+            $processed++;
+
+            $request = $output->request;
+            if (! $request instanceof AiEditRequest) {
+                $failed++;
+                $this->warn(sprintf('Output %d skipped: missing request relation.', $output->id));
+
+                continue;
+            }
+
+            $persisted = $this->outputStorage->persist($request, [
+                'provider_url' => $output->provider_url,
+                'provider_asset_id' => $output->provider_asset_id,
+                'storage_disk' => $output->storage_disk,
+                'storage_path' => $output->storage_path,
+                'mime_type' => $output->mime_type,
+                'width' => $output->width,
+                'height' => $output->height,
+                'bytes' => $output->bytes,
+                'checksum' => $output->checksum,
+                'metadata' => $output->metadata,
+            ]);
+
+            $output->forceFill([
+                'provider_url' => $persisted['provider_url'] ?? $output->provider_url,
+                'storage_disk' => $persisted['storage_disk'] ?? $output->storage_disk,
+                'storage_path' => $persisted['storage_path'] ?? $output->storage_path,
+                'mime_type' => $persisted['mime_type'] ?? $output->mime_type,
+                'width' => array_key_exists('width', $persisted) ? $persisted['width'] : $output->width,
+                'height' => array_key_exists('height', $persisted) ? $persisted['height'] : $output->height,
+                'bytes' => array_key_exists('bytes', $persisted) ? $persisted['bytes'] : $output->bytes,
+                'checksum' => $persisted['checksum'] ?? $output->checksum,
+                'metadata' => is_array($persisted['metadata'] ?? null) ? $persisted['metadata'] : $output->metadata,
+            ])->save();
+
+            $storagePath = trim((string) ($output->storage_path ?? ''));
+            if ($storagePath !== '') {
+                $stored++;
+            } else {
+                $failed++;
+                $this->warn(sprintf('Output %d could not be persisted locally.', $output->id));
+            }
+        }
+
+        $this->info(sprintf(
+            'AI output backfill complete: processed=%d stored=%d failed=%d.',
+            $processed,
+            $stored,
+            $failed
+        ));
+
+        return self::SUCCESS;
+    }
+
+    private function normalizeRequestId(mixed $value): ?int
+    {
+        if (! is_numeric($value)) {
+            return null;
+        }
+
+        $requestId = (int) $value;
+
+        return $requestId > 0 ? $requestId : null;
+    }
+}

app/Http/Controllers/Api/EventPublicAiEditController.php

@@ -20,6 +20,8 @@ use App\Support\ApiError;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Routing\Controller as BaseController;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Storage;
 use Illuminate\Support\Str;
 use Symfony\Component\HttpFoundation\Response;
 
@@ -492,6 +494,11 @@ class EventPublicAiEditController extends BaseController
                 'storage_disk' => $output->storage_disk,
                 'storage_path' => $output->storage_path,
                 'provider_url' => $output->provider_url,
+                'url' => $this->resolveOutputUrl(
+                    $output->storage_disk,
+                    $output->storage_path,
+                    $output->provider_url
+                ),
                 'mime_type' => $output->mime_type,
                 'width' => $output->width,
                 'height' => $output->height,
@@ -502,4 +509,41 @@ class EventPublicAiEditController extends BaseController
             ])->values(),
         ];
     }
+
+    private function resolveOutputUrl(?string $storageDisk, ?string $storagePath, ?string $providerUrl): ?string
+    {
+        $resolvedStoragePath = $this->normalizeOptionalString($storagePath);
+        if ($resolvedStoragePath !== null) {
+            if (Str::startsWith($resolvedStoragePath, ['http://', 'https://'])) {
+                return $resolvedStoragePath;
+            }
+
+            $disk = $this->resolveStorageDisk($storageDisk);
+
+            try {
+                return Storage::disk($disk)->url($resolvedStoragePath);
+            } catch (\Throwable $exception) {
+                Log::debug('Falling back to raw AI output storage path', [
+                    'disk' => $disk,
+                    'path' => $resolvedStoragePath,
+                    'error' => $exception->getMessage(),
+                ]);
+
+                return '/'.ltrim($resolvedStoragePath, '/');
+            }
+        }
+
+        return $this->normalizeOptionalString($providerUrl);
+    }
+
+    private function resolveStorageDisk(?string $disk): string
+    {
+        $candidate = trim((string) ($disk ?: config('filesystems.default', 'public')));
+
+        if ($candidate === '' || ! config("filesystems.disks.{$candidate}")) {
+            return (string) config('filesystems.default', 'public');
+        }
+
+        return $candidate;
+    }
 }

app/Http/Controllers/Api/Tenant/AiEditController.php

@@ -24,6 +24,8 @@ use App\Support\TenantMemberPermissions;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Storage;
 use Illuminate\Support\Str;
 use Symfony\Component\HttpFoundation\Response;
 
@@ -561,6 +563,11 @@ class AiEditController extends Controller
                 'storage_disk' => $output->storage_disk,
                 'storage_path' => $output->storage_path,
                 'provider_url' => $output->provider_url,
+                'url' => $this->resolveOutputUrl(
+                    $output->storage_disk,
+                    $output->storage_path,
+                    $output->provider_url
+                ),
                 'mime_type' => $output->mime_type,
                 'width' => $output->width,
                 'height' => $output->height,
@@ -571,4 +578,41 @@ class AiEditController extends Controller
             ])->values(),
         ];
     }
+
+    private function resolveOutputUrl(?string $storageDisk, ?string $storagePath, ?string $providerUrl): ?string
+    {
+        $resolvedStoragePath = $this->normalizeOptionalString($storagePath);
+        if ($resolvedStoragePath !== null) {
+            if (Str::startsWith($resolvedStoragePath, ['http://', 'https://'])) {
+                return $resolvedStoragePath;
+            }
+
+            $disk = $this->resolveStorageDisk($storageDisk);
+
+            try {
+                return Storage::disk($disk)->url($resolvedStoragePath);
+            } catch (\Throwable $exception) {
+                Log::debug('Falling back to raw AI output storage path', [
+                    'disk' => $disk,
+                    'path' => $resolvedStoragePath,
+                    'error' => $exception->getMessage(),
+                ]);
+
+                return '/'.ltrim($resolvedStoragePath, '/');
+            }
+        }
+
+        return $this->normalizeOptionalString($providerUrl);
+    }
+
+    private function resolveStorageDisk(?string $disk): string
+    {
+        $candidate = trim((string) ($disk ?: config('filesystems.default', 'public')));
+
+        if ($candidate === '' || ! config("filesystems.disks.{$candidate}")) {
+            return (string) config('filesystems.default', 'public');
+        }
+
+        return $candidate;
+    }
 }

app/Jobs/PollAiEditRequest.php

@@ -6,6 +6,7 @@ use App\Models\AiEditOutput;
 use App\Models\AiEditRequest;
 use App\Models\AiProviderRun;
 use App\Services\AiEditing\AiEditingRuntimeConfig;
+use App\Services\AiEditing\AiEditOutputStorageService;
 use App\Services\AiEditing\AiImageProviderManager;
 use App\Services\AiEditing\AiObservabilityService;
 use App\Services\AiEditing\AiStatusNotificationService;
@@ -51,6 +52,7 @@ class PollAiEditRequest implements ShouldQueue
         AiAbuseEscalationService $abuseEscalation,
         AiObservabilityService $observability,
         AiStatusNotificationService $statusNotifications,
+        AiEditOutputStorageService $outputStorage,
         AiEditingRuntimeConfig $runtimeConfig,
         AiUsageLedgerService $usageLedger
     ): void {
@@ -119,21 +121,31 @@ class PollAiEditRequest implements ShouldQueue
             }
 
             foreach ($result->outputs as $output) {
+                $persistedOutput = $outputStorage->persist($request, is_array($output) ? $output : []);
                 AiEditOutput::query()->updateOrCreate(
                     [
                         'request_id' => $request->id,
-                        'provider_asset_id' => (string) Arr::get($output, 'provider_asset_id', $this->providerTaskId),
+                        'provider_asset_id' => (string) Arr::get($persistedOutput, 'provider_asset_id', $this->providerTaskId),
                     ],
                     [
-                        'provider_url' => Arr::get($output, 'provider_url'),
-                        'mime_type' => Arr::get($output, 'mime_type'),
-                        'width' => Arr::get($output, 'width'),
-                        'height' => Arr::get($output, 'height'),
+                        'storage_disk' => Arr::get($persistedOutput, 'storage_disk'),
+                        'storage_path' => Arr::get($persistedOutput, 'storage_path'),
+                        'provider_url' => Arr::get($persistedOutput, 'provider_url'),
+                        'mime_type' => Arr::get($persistedOutput, 'mime_type'),
+                        'width' => Arr::get($persistedOutput, 'width'),
+                        'height' => Arr::get($persistedOutput, 'height'),
+                        'bytes' => Arr::get($persistedOutput, 'bytes'),
+                        'checksum' => Arr::get($persistedOutput, 'checksum'),
                         'is_primary' => true,
                         'safety_state' => 'passed',
                         'safety_reasons' => [],
                         'generated_at' => now(),
-                        'metadata' => ['provider' => $request->provider],
+                        'metadata' => array_merge(
+                            ['provider' => $request->provider],
+                            is_array(Arr::get($persistedOutput, 'metadata'))
+                                ? Arr::get($persistedOutput, 'metadata')
+                                : []
+                        ),
                     ]
                 );
             }

app/Jobs/ProcessAiEditRequest.php

@@ -6,6 +6,7 @@ use App\Models\AiEditOutput;
 use App\Models\AiEditRequest;
 use App\Models\AiProviderRun;
 use App\Services\AiEditing\AiEditingRuntimeConfig;
+use App\Services\AiEditing\AiEditOutputStorageService;
 use App\Services\AiEditing\AiImageProviderManager;
 use App\Services\AiEditing\AiObservabilityService;
 use App\Services\AiEditing\AiProviderResult;
@@ -51,6 +52,7 @@ class ProcessAiEditRequest implements ShouldQueue
         AiAbuseEscalationService $abuseEscalation,
         AiObservabilityService $observability,
         AiStatusNotificationService $statusNotifications,
+        AiEditOutputStorageService $outputStorage,
         AiEditingRuntimeConfig $runtimeConfig,
         AiUsageLedgerService $usageLedger
     ): void {
@@ -90,6 +92,7 @@ class ProcessAiEditRequest implements ShouldQueue
             $abuseEscalation,
             $observability,
             $statusNotifications,
+            $outputStorage,
             $runtimeConfig,
             $usageLedger
         );
@@ -160,6 +163,7 @@ class ProcessAiEditRequest implements ShouldQueue
         AiAbuseEscalationService $abuseEscalation,
         AiObservabilityService $observability,
         AiStatusNotificationService $statusNotifications,
+        AiEditOutputStorageService $outputStorage,
         AiEditingRuntimeConfig $runtimeConfig,
         AiUsageLedgerService $usageLedger
     ): void {
@@ -200,23 +204,33 @@ class ProcessAiEditRequest implements ShouldQueue
                 return;
             }
 
-            DB::transaction(function () use ($request, $result): void {
+            DB::transaction(function () use ($request, $result, $outputStorage): void {
                 foreach ($result->outputs as $output) {
+                    $persistedOutput = $outputStorage->persist($request, is_array($output) ? $output : []);
                     AiEditOutput::query()->updateOrCreate(
                         [
                             'request_id' => $request->id,
-                            'provider_asset_id' => (string) Arr::get($output, 'provider_asset_id', ''),
+                            'provider_asset_id' => (string) Arr::get($persistedOutput, 'provider_asset_id', ''),
                         ],
                         [
-                            'provider_url' => Arr::get($output, 'provider_url'),
-                            'mime_type' => Arr::get($output, 'mime_type'),
-                            'width' => Arr::get($output, 'width'),
-                            'height' => Arr::get($output, 'height'),
+                            'storage_disk' => Arr::get($persistedOutput, 'storage_disk'),
+                            'storage_path' => Arr::get($persistedOutput, 'storage_path'),
+                            'provider_url' => Arr::get($persistedOutput, 'provider_url'),
+                            'mime_type' => Arr::get($persistedOutput, 'mime_type'),
+                            'width' => Arr::get($persistedOutput, 'width'),
+                            'height' => Arr::get($persistedOutput, 'height'),
+                            'bytes' => Arr::get($persistedOutput, 'bytes'),
+                            'checksum' => Arr::get($persistedOutput, 'checksum'),
                             'is_primary' => true,
                             'safety_state' => 'passed',
                             'safety_reasons' => [],
                             'generated_at' => now(),
-                            'metadata' => ['provider' => $request->provider],
+                            'metadata' => array_merge(
+                                ['provider' => $request->provider],
+                                is_array(Arr::get($persistedOutput, 'metadata'))
+                                    ? Arr::get($persistedOutput, 'metadata')
+                                    : []
+                            ),
                         ]
                     );
                 }

app/Services/AiEditing/AiEditOutputStorageService.php

@@ -0,0 +1,520 @@
+<?php
+
+namespace App\Services\AiEditing;
+
+use App\Models\AiEditRequest;
+use App\Models\Event;
+use App\Services\Storage\EventStorageManager;
+use App\Support\ImageHelper;
+use App\Support\WatermarkConfigResolver;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Storage;
+use Illuminate\Support\Str;
+use RuntimeException;
+use Throwable;
+
+class AiEditOutputStorageService
+{
+    public function __construct(private readonly EventStorageManager $eventStorageManager) {}
+
+    /**
+     * @param  array<string, mixed>  $output
+     * @return array{
+     *     provider_url: ?string,
+     *     provider_asset_id: ?string,
+     *     storage_disk: ?string,
+     *     storage_path: ?string,
+     *     mime_type: ?string,
+     *     width: ?int,
+     *     height: ?int,
+     *     bytes: ?int,
+     *     checksum: ?string,
+     *     metadata: array<string, mixed>
+     * }
+     */
+    public function persist(AiEditRequest $request, array $output): array
+    {
+        $normalized = $this->normalizeOutput($output);
+
+        if (! $this->outputsEnabled()) {
+            return $normalized;
+        }
+
+        $providerUrl = $normalized['provider_url'];
+        if (! is_string($providerUrl) || trim($providerUrl) === '') {
+            return $normalized;
+        }
+
+        $event = Event::query()
+            ->with([
+                'tenant',
+                'eventPackage.package',
+                'eventPackages.package',
+                'storageAssignments.storageTarget',
+            ])
+            ->find($request->event_id);
+
+        if (! $event) {
+            return $this->withStorageFailure(
+                $normalized,
+                'event_not_found',
+                'Could not resolve event while persisting AI output.'
+            );
+        }
+
+        try {
+            $download = $this->downloadImage($providerUrl);
+            $persisted = $this->storeLocally($request, $event, $download);
+
+            return array_merge($normalized, $persisted);
+        } catch (Throwable $exception) {
+            Log::warning('AI output local persistence failed', [
+                'request_id' => $request->id,
+                'event_id' => $request->event_id,
+                'provider' => $request->provider,
+                'provider_url' => $providerUrl,
+                'error' => $exception->getMessage(),
+            ]);
+
+            return $this->withStorageFailure(
+                $normalized,
+                'output_storage_failed',
+                $exception->getMessage()
+            );
+        }
+    }
+
+    /**
+     * @return array{
+     *     binary: string,
+     *     mime_type: string,
+     *     width: int,
+     *     height: int,
+     *     bytes: int,
+     *     extension: string
+     * }
+     */
+    private function downloadImage(string $url): array
+    {
+        $this->assertSourceUrlAllowed($url);
+
+        $response = Http::accept('*/*')
+            ->connectTimeout(max(1, (int) config('ai-editing.outputs.connect_timeout_seconds', 10)))
+            ->timeout(max(1, (int) config('ai-editing.outputs.timeout_seconds', 60)))
+            ->withHeaders([
+                'User-Agent' => (string) config('ai-editing.outputs.user_agent', 'fotospiel-ai-output-fetcher/1.0'),
+            ])
+            ->get($url);
+
+        if (! $response->successful()) {
+            throw new RuntimeException(sprintf(
+                'Provider output download returned HTTP %d.',
+                $response->status()
+            ));
+        }
+
+        $maxBytes = max(1024, (int) config('ai-editing.outputs.max_download_bytes', 15 * 1024 * 1024));
+        $contentLength = (int) ($response->header('Content-Length') ?: 0);
+        if ($contentLength > $maxBytes) {
+            throw new RuntimeException(sprintf(
+                'Provider output exceeds maximum allowed size (%d bytes).',
+                $maxBytes
+            ));
+        }
+
+        $binary = $response->body();
+        if (! is_string($binary) || $binary === '') {
+            throw new RuntimeException('Provider output is empty.');
+        }
+
+        $bytes = strlen($binary);
+        if ($bytes > $maxBytes) {
+            throw new RuntimeException(sprintf(
+                'Downloaded output exceeds maximum allowed size (%d bytes).',
+                $maxBytes
+            ));
+        }
+
+        $imageInfo = @getimagesizefromstring($binary);
+        if (! is_array($imageInfo)) {
+            throw new RuntimeException('Provider output is not a valid image.');
+        }
+
+        $mimeType = $this->normalizeMimeType(
+            $imageInfo['mime'] ?? $response->header('Content-Type')
+        );
+        if (! str_starts_with($mimeType, 'image/')) {
+            throw new RuntimeException('Provider output did not return an image mime type.');
+        }
+
+        return [
+            'binary' => $binary,
+            'mime_type' => $mimeType,
+            'width' => (int) ($imageInfo[0] ?? 0),
+            'height' => (int) ($imageInfo[1] ?? 0),
+            'bytes' => $bytes,
+            'extension' => $this->extensionForMimeType($mimeType, $url),
+        ];
+    }
+
+    /**
+     * @param  array{
+     *     binary: string,
+     *     mime_type: string,
+     *     width: int,
+     *     height: int,
+     *     bytes: int,
+     *     extension: string
+     * }  $download
+     * @return array{
+     *     storage_disk: ?string,
+     *     storage_path: ?string,
+     *     mime_type: ?string,
+     *     width: ?int,
+     *     height: ?int,
+     *     bytes: ?int,
+     *     checksum: ?string,
+     *     metadata: array<string, mixed>
+     * }
+     */
+    private function storeLocally(AiEditRequest $request, Event $event, array $download): array
+    {
+        $disk = $this->eventStorageManager->getHotDiskForEvent($event);
+        $eventSlug = trim((string) ($event->slug ?? ''));
+        if ($eventSlug === '') {
+            $eventSlug = 'event-'.$event->id;
+        }
+
+        $baseName = Str::uuid()->toString();
+        $baseDirectory = sprintf('events/%s/ai-edits/%d', $eventSlug, $request->id);
+        $originalPath = sprintf('%s/original/%s.%s', $baseDirectory, $baseName, $download['extension']);
+        Storage::disk($disk)->put($originalPath, $download['binary']);
+
+        $thumbnailPath = sprintf('%s/thumbnails/%s_thumb.jpg', $baseDirectory, $baseName);
+        $thumbnailRelative = ImageHelper::makeThumbnailOnDisk($disk, $originalPath, $thumbnailPath, 640, 82);
+
+        $watermarkConfig = WatermarkConfigResolver::resolve($event);
+        $finalPath = $originalPath;
+        $finalThumbnailPath = $thumbnailRelative;
+        $watermarkApplied = false;
+
+        if ($this->shouldApplyWatermark($watermarkConfig)) {
+            $watermarkedPath = sprintf('%s/watermarked/%s.%s', $baseDirectory, $baseName, $download['extension']);
+            $resolvedWatermarkedPath = ImageHelper::copyWithWatermark($disk, $originalPath, $watermarkedPath, $watermarkConfig);
+            if (is_string($resolvedWatermarkedPath) && $resolvedWatermarkedPath !== '') {
+                $finalPath = $resolvedWatermarkedPath;
+                $watermarkApplied = true;
+            }
+
+            if ($thumbnailRelative) {
+                $watermarkedThumbPath = sprintf('%s/watermarked/%s_thumb.jpg', $baseDirectory, $baseName);
+                $resolvedWatermarkedThumbPath = ImageHelper::copyWithWatermark($disk, $thumbnailRelative, $watermarkedThumbPath, $watermarkConfig);
+                if (is_string($resolvedWatermarkedThumbPath) && $resolvedWatermarkedThumbPath !== '') {
+                    $finalThumbnailPath = $resolvedWatermarkedThumbPath;
+                }
+            }
+        }
+
+        $finalBinary = Storage::disk($disk)->get($finalPath);
+        $finalImageInfo = is_string($finalBinary) ? @getimagesizefromstring($finalBinary) : false;
+        $finalMimeType = is_array($finalImageInfo)
+            ? $this->normalizeMimeType($finalImageInfo['mime'] ?? $download['mime_type'])
+            : $download['mime_type'];
+        $finalWidth = is_array($finalImageInfo) ? (int) ($finalImageInfo[0] ?? 0) : $download['width'];
+        $finalHeight = is_array($finalImageInfo) ? (int) ($finalImageInfo[1] ?? 0) : $download['height'];
+        $finalBytes = Storage::disk($disk)->exists($finalPath)
+            ? (int) Storage::disk($disk)->size($finalPath)
+            : $download['bytes'];
+        $checksum = is_string($finalBinary) && $finalBinary !== ''
+            ? hash('sha256', $finalBinary)
+            : null;
+
+        $metadata = [
+            'storage' => [
+                'original_path' => $originalPath,
+                'thumbnail_path' => $thumbnailRelative,
+                'watermarked_path' => $watermarkApplied ? $finalPath : null,
+                'watermarked_thumbnail_path' => $finalThumbnailPath !== $thumbnailRelative ? $finalThumbnailPath : null,
+                'watermark_applied' => $watermarkApplied,
+                'stored_at' => now()->toIso8601String(),
+            ],
+        ];
+
+        $this->recordAssetSafely($event, $disk, $originalPath, [
+            'variant' => 'ai_original',
+            'mime_type' => $download['mime_type'],
+            'size_bytes' => $download['bytes'],
+            'status' => 'hot',
+            'processed_at' => now(),
+            'photo_id' => $request->photo_id,
+            'meta' => ['ai_request_id' => $request->id],
+        ]);
+
+        if ($finalPath !== $originalPath) {
+            $this->recordAssetSafely($event, $disk, $finalPath, [
+                'variant' => 'ai_watermarked',
+                'mime_type' => $finalMimeType,
+                'size_bytes' => $finalBytes,
+                'checksum' => $checksum,
+                'status' => 'hot',
+                'processed_at' => now(),
+                'photo_id' => $request->photo_id,
+                'meta' => ['ai_request_id' => $request->id],
+            ]);
+        }
+
+        if ($thumbnailRelative) {
+            $this->recordAssetSafely($event, $disk, $thumbnailRelative, [
+                'variant' => 'ai_thumbnail',
+                'mime_type' => 'image/jpeg',
+                'size_bytes' => Storage::disk($disk)->exists($thumbnailRelative)
+                    ? (int) Storage::disk($disk)->size($thumbnailRelative)
+                    : null,
+                'status' => 'hot',
+                'processed_at' => now(),
+                'photo_id' => $request->photo_id,
+                'meta' => ['ai_request_id' => $request->id],
+            ]);
+        }
+
+        if ($finalThumbnailPath && $finalThumbnailPath !== $thumbnailRelative) {
+            $this->recordAssetSafely($event, $disk, $finalThumbnailPath, [
+                'variant' => 'ai_watermarked_thumbnail',
+                'mime_type' => 'image/jpeg',
+                'size_bytes' => Storage::disk($disk)->exists($finalThumbnailPath)
+                    ? (int) Storage::disk($disk)->size($finalThumbnailPath)
+                    : null,
+                'status' => 'hot',
+                'processed_at' => now(),
+                'photo_id' => $request->photo_id,
+                'meta' => ['ai_request_id' => $request->id],
+            ]);
+        }
+
+        return [
+            'storage_disk' => $disk,
+            'storage_path' => $finalPath,
+            'mime_type' => $finalMimeType,
+            'width' => $finalWidth > 0 ? $finalWidth : null,
+            'height' => $finalHeight > 0 ? $finalHeight : null,
+            'bytes' => $finalBytes > 0 ? $finalBytes : null,
+            'checksum' => $checksum,
+            'metadata' => $metadata,
+        ];
+    }
+
+    /**
+     * @param  array<string, mixed>  $attributes
+     */
+    private function recordAssetSafely(Event $event, string $disk, string $path, array $attributes): void
+    {
+        try {
+            $this->eventStorageManager->recordAsset($event, $disk, $path, $attributes);
+        } catch (Throwable $exception) {
+            Log::warning('AI output asset metadata recording failed', [
+                'event_id' => $event->id,
+                'disk' => $disk,
+                'path' => $path,
+                'error' => $exception->getMessage(),
+            ]);
+        }
+    }
+
+    private function shouldApplyWatermark(array $watermarkConfig): bool
+    {
+        return ($watermarkConfig['type'] ?? 'none') !== 'none'
+            && trim((string) ($watermarkConfig['asset'] ?? '')) !== ''
+            && ! (bool) ($watermarkConfig['serve_originals'] ?? false);
+    }
+
+    private function outputsEnabled(): bool
+    {
+        return (bool) config('ai-editing.outputs.enabled', true);
+    }
+
+    private function assertSourceUrlAllowed(string $url): void
+    {
+        $parsed = parse_url($url);
+        if (! is_array($parsed)) {
+            throw new RuntimeException('Provider output URL is invalid.');
+        }
+
+        $scheme = strtolower((string) ($parsed['scheme'] ?? ''));
+        if (! in_array($scheme, ['http', 'https'], true)) {
+            throw new RuntimeException('Provider output URL scheme is not allowed.');
+        }
+
+        $host = strtolower((string) ($parsed['host'] ?? ''));
+        if ($host === '') {
+            throw new RuntimeException('Provider output URL host is missing.');
+        }
+
+        if (
+            $host === 'localhost'
+            || str_ends_with($host, '.local')
+            || str_ends_with($host, '.internal')
+            || str_ends_with($host, '.invalid')
+            || str_ends_with($host, '.test')
+        ) {
+            throw new RuntimeException('Provider output URL host is blocked.');
+        }
+
+        if (filter_var($host, FILTER_VALIDATE_IP) !== false) {
+            $isPublicIp = filter_var(
+                $host,
+                FILTER_VALIDATE_IP,
+                FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE
+            ) !== false;
+
+            if (! $isPublicIp) {
+                throw new RuntimeException('Provider output URL host is not publicly routable.');
+            }
+        }
+
+        $allowedHosts = array_values(array_filter(array_map(
+            static fn (mixed $value): string => strtolower(trim((string) $value)),
+            (array) config('ai-editing.outputs.allowed_hosts', [])
+        )));
+
+        if ($allowedHosts === []) {
+            return;
+        }
+
+        foreach ($allowedHosts as $allowedHost) {
+            if ($allowedHost === '') {
+                continue;
+            }
+
+            if ($host === $allowedHost || str_ends_with($host, '.'.$allowedHost)) {
+                return;
+            }
+        }
+
+        throw new RuntimeException('Provider output URL host is not in allowed host list.');
+    }
+
+    /**
+     * @param  array<string, mixed>  $output
+     * @return array{
+     *     provider_url: ?string,
+     *     provider_asset_id: ?string,
+     *     storage_disk: ?string,
+     *     storage_path: ?string,
+     *     mime_type: ?string,
+     *     width: ?int,
+     *     height: ?int,
+     *     bytes: ?int,
+     *     checksum: ?string,
+     *     metadata: array<string, mixed>
+     * }
+     */
+    private function normalizeOutput(array $output): array
+    {
+        return [
+            'provider_url' => $this->normalizeOptionalString((string) Arr::get($output, 'provider_url', '')),
+            'provider_asset_id' => $this->normalizeOptionalString((string) Arr::get($output, 'provider_asset_id', '')),
+            'storage_disk' => $this->normalizeOptionalString((string) Arr::get($output, 'storage_disk', '')),
+            'storage_path' => $this->normalizeOptionalString((string) Arr::get($output, 'storage_path', '')),
+            'mime_type' => $this->normalizeOptionalString((string) Arr::get($output, 'mime_type', '')),
+            'width' => is_numeric(Arr::get($output, 'width')) ? (int) Arr::get($output, 'width') : null,
+            'height' => is_numeric(Arr::get($output, 'height')) ? (int) Arr::get($output, 'height') : null,
+            'bytes' => is_numeric(Arr::get($output, 'bytes')) ? (int) Arr::get($output, 'bytes') : null,
+            'checksum' => $this->normalizeOptionalString((string) Arr::get($output, 'checksum', '')),
+            'metadata' => is_array(Arr::get($output, 'metadata')) ? (array) Arr::get($output, 'metadata') : [],
+        ];
+    }
+
+    private function normalizeOptionalString(?string $value): ?string
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        $trimmed = trim($value);
+
+        return $trimmed !== '' ? $trimmed : null;
+    }
+
+    private function normalizeMimeType(?string $value): string
+    {
+        $mimeType = strtolower(trim((string) $value));
+
+        if ($mimeType === '') {
+            return 'image/jpeg';
+        }
+
+        $parts = explode(';', $mimeType);
+
+        return trim((string) $parts[0]) !== '' ? trim((string) $parts[0]) : 'image/jpeg';
+    }
+
+    private function extensionForMimeType(string $mimeType, string $url): string
+    {
+        $map = [
+            'image/jpeg' => 'jpg',
+            'image/png' => 'png',
+            'image/webp' => 'webp',
+            'image/gif' => 'gif',
+            'image/heic' => 'heic',
+            'image/heif' => 'heif',
+        ];
+
+        if (array_key_exists($mimeType, $map)) {
+            return $map[$mimeType];
+        }
+
+        $path = (string) parse_url($url, PHP_URL_PATH);
+        $extension = strtolower(pathinfo($path, PATHINFO_EXTENSION));
+        if ($extension !== '') {
+            return $extension;
+        }
+
+        return 'jpg';
+    }
+
+    /**
+     * @param  array{
+     *     provider_url: ?string,
+     *     provider_asset_id: ?string,
+     *     storage_disk: ?string,
+     *     storage_path: ?string,
+     *     mime_type: ?string,
+     *     width: ?int,
+     *     height: ?int,
+     *     bytes: ?int,
+     *     checksum: ?string,
+     *     metadata: array<string, mixed>
+     * }  $output
+     * @return array{
+     *     provider_url: ?string,
+     *     provider_asset_id: ?string,
+     *     storage_disk: ?string,
+     *     storage_path: ?string,
+     *     mime_type: ?string,
+     *     width: ?int,
+     *     height: ?int,
+     *     bytes: ?int,
+     *     checksum: ?string,
+     *     metadata: array<string, mixed>
+     * }
+     */
+    private function withStorageFailure(array $output, string $code, string $message): array
+    {
+        $metadata = $output['metadata'];
+        $metadata['storage'] = array_merge(
+            is_array($metadata['storage'] ?? null) ? $metadata['storage'] : [],
+            [
+                'failed' => true,
+                'error_code' => $code,
+                'error_message' => Str::limit($message, 500, ''),
+                'failed_at' => now()->toIso8601String(),
+            ]
+        );
+
+        $output['metadata'] = $metadata;
+
+        return $output;
+    }
+}