feat(ai): finalize AI magic edits epic rollout and operations

tests/Feature/Ai/AiEditingDataModelTest.php

@@ -29,6 +29,7 @@ class AiEditingDataModelTest extends TestCase
             'key',
             'provider',
             'provider_model',
+            'version',
             'requires_source_image',
             'is_premium',
         ] as $column) {

tests/Feature/Api/Event/EventAiEditControllerTest.php

@@ -5,6 +5,7 @@ namespace Tests\Feature\Api\Event;
 use App\Models\AiEditingSetting;
 use App\Models\AiEditRequest;
 use App\Models\AiStyle;
+use App\Models\AiUsageLedger;
 use App\Models\Event;
 use App\Models\EventPackage;
 use App\Models\EventPackageAddon;
@@ -302,6 +303,7 @@ class EventAiEditControllerTest extends TestCase
 
         $response->assertOk()
             ->assertJsonPath('data.0.id', $allowed->id)
+            ->assertJsonPath('data.0.version', 1)
             ->assertJsonCount(1, 'data')
             ->assertJsonPath('meta.required_feature', 'ai_styling')
             ->assertJsonPath('meta.allow_custom_prompt', false)
@@ -594,6 +596,129 @@ class EventAiEditControllerTest extends TestCase
         $second->assertStatus(429);
     }
 
+    public function test_guest_submit_endpoint_enforces_event_scope_rate_limit_across_devices(): void
+    {
+        config([
+            'ai-editing.abuse.guest_submit_per_minute' => 10,
+            'ai-editing.abuse.guest_submit_per_hour' => 100,
+            'ai-editing.abuse.guest_submit_per_event_per_minute' => 1,
+        ]);
+
+        $event = Event::factory()->create([
+            'status' => 'published',
+        ]);
+        $this->attachEntitledEventPackage($event);
+
+        $photo = Photo::factory()->for($event)->create([
+            'tenant_id' => $event->tenant_id,
+            'status' => 'approved',
+        ]);
+
+        $token = app(EventJoinTokenService::class)
+            ->createToken($event, ['label' => 'guest-ai-event-rate-limit'])
+            ->getAttribute('plain_token');
+
+        $first = $this->withHeaders(['X-Device-Id' => 'guest-device-event-limit-a'])
+            ->postJson("/api/v1/events/{$token}/photos/{$photo->id}/ai-edits", [
+                'prompt' => 'First request.',
+                'idempotency_key' => 'guest-event-rate-limit-1',
+            ]);
+        $first->assertCreated();
+
+        $second = $this->withHeaders(['X-Device-Id' => 'guest-device-event-limit-b'])
+            ->postJson("/api/v1/events/{$token}/photos/{$photo->id}/ai-edits", [
+                'prompt' => 'Second request.',
+                'idempotency_key' => 'guest-event-rate-limit-2',
+            ]);
+        $second->assertStatus(429);
+    }
+
+    public function test_guest_cannot_create_ai_edit_when_hard_budget_cap_is_reached(): void
+    {
+        $event = Event::factory()->create([
+            'status' => 'published',
+        ]);
+        $this->attachEntitledEventPackage($event);
+
+        $tenantSettings = (array) ($event->tenant->settings ?? []);
+        data_set($tenantSettings, 'ai_editing.budget.hard_cap_usd', 0.01);
+        $event->tenant->update(['settings' => $tenantSettings]);
+
+        $photo = Photo::factory()->for($event)->create([
+            'tenant_id' => $event->tenant_id,
+            'status' => 'approved',
+        ]);
+        AiUsageLedger::query()->create([
+            'tenant_id' => $event->tenant_id,
+            'event_id' => $event->id,
+            'entry_type' => AiUsageLedger::TYPE_DEBIT,
+            'quantity' => 1,
+            'unit_cost_usd' => 0.02,
+            'amount_usd' => 0.02,
+            'currency' => 'USD',
+            'recorded_at' => now(),
+        ]);
+
+        $token = app(EventJoinTokenService::class)
+            ->createToken($event, ['label' => 'guest-ai-budget-hard-cap'])
+            ->getAttribute('plain_token');
+
+        $response = $this->withHeaders(['X-Device-Id' => 'guest-device-budget-cap'])
+            ->postJson("/api/v1/events/{$token}/photos/{$photo->id}/ai-edits", [
+                'prompt' => 'Stylize image.',
+                'idempotency_key' => 'guest-budget-cap-1',
+            ]);
+
+        $response->assertForbidden()
+            ->assertJsonPath('error.code', 'budget_hard_cap_reached')
+            ->assertJsonPath('error.meta.budget.hard_reached', true);
+    }
+
+    public function test_guest_prompt_block_records_abuse_metadata_when_escalation_threshold_is_reached(): void
+    {
+        config([
+            'ai-editing.abuse.escalation_threshold_per_hour' => 1,
+            'ai-editing.abuse.escalation_cooldown_minutes' => 1,
+        ]);
+        AiEditingSetting::flushCache();
+        AiEditingSetting::query()->create(array_merge(
+            AiEditingSetting::defaults(),
+            ['blocked_terms' => ['explicit']]
+        ));
+
+        $event = Event::factory()->create([
+            'status' => 'published',
+        ]);
+        $this->attachEntitledEventPackage($event);
+
+        $photo = Photo::factory()->for($event)->create([
+            'tenant_id' => $event->tenant_id,
+            'status' => 'approved',
+        ]);
+
+        $token = app(EventJoinTokenService::class)
+            ->createToken($event, ['label' => 'guest-ai-escalation'])
+            ->getAttribute('plain_token');
+
+        $response = $this->withHeaders(['X-Device-Id' => 'guest-device-escalation'])
+            ->postJson("/api/v1/events/{$token}/photos/{$photo->id}/ai-edits", [
+                'prompt' => 'Create an explicit style image.',
+                'idempotency_key' => 'guest-escalation-1',
+            ]);
+
+        $response->assertCreated()
+            ->assertJsonPath('data.status', AiEditRequest::STATUS_BLOCKED)
+            ->assertJsonFragment(['abuse_escalation_threshold_reached']);
+
+        $requestId = (int) $response->json('data.id');
+        $editRequest = AiEditRequest::query()->find($requestId);
+
+        $this->assertNotNull($editRequest);
+        $this->assertIsArray($editRequest?->metadata);
+        $this->assertSame('prompt_block', $editRequest?->metadata['abuse']['type'] ?? null);
+        $this->assertTrue((bool) ($editRequest?->metadata['abuse']['escalated'] ?? false));
+    }
+
     public function test_guest_cannot_create_ai_edit_when_event_ai_feature_is_disabled(): void
     {
         $event = Event::factory()->create([

tests/Feature/Api/Tenant/TenantAiEditControllerTest.php

@@ -5,6 +5,7 @@ namespace Tests\Feature\Api\Tenant;
 use App\Models\AiEditingSetting;
 use App\Models\AiEditRequest;
 use App\Models\AiStyle;
+use App\Models\AiUsageLedger;
 use App\Models\Event;
 use App\Models\EventPackage;
 use App\Models\EventPackageAddon;
@@ -305,6 +306,7 @@ class TenantAiEditControllerTest extends TenantTestCase
 
         $response->assertOk()
             ->assertJsonPath('data.0.id', $active->id)
+            ->assertJsonPath('data.0.version', 1)
             ->assertJsonCount(1, 'data')
             ->assertJsonPath('meta.required_feature', 'ai_styling')
             ->assertJsonPath('meta.event_enabled', false)
@@ -540,6 +542,148 @@ class TenantAiEditControllerTest extends TenantTestCase
         $second->assertStatus(429);
     }
 
+    public function test_tenant_submit_endpoint_enforces_event_scope_rate_limit(): void
+    {
+        config([
+            'ai-editing.abuse.tenant_submit_per_minute' => 10,
+            'ai-editing.abuse.tenant_submit_per_hour' => 100,
+            'ai-editing.abuse.tenant_submit_per_event_per_minute' => 1,
+        ]);
+
+        $event = Event::factory()->create([
+            'tenant_id' => $this->tenant->id,
+            'status' => 'published',
+        ]);
+        $this->attachEntitledEventPackage($event);
+
+        $photo = Photo::factory()->for($event)->create([
+            'tenant_id' => $this->tenant->id,
+            'status' => 'approved',
+        ]);
+        $style = AiStyle::query()->create([
+            'key' => 'tenant-event-rate-limit-style',
+            'name' => 'Tenant Event Rate Limit',
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'requires_source_image' => true,
+            'is_active' => true,
+        ]);
+
+        $first = $this->authenticatedRequest('POST', "/api/v1/tenant/events/{$event->slug}/ai-edits", [
+            'photo_id' => $photo->id,
+            'style_id' => $style->id,
+            'prompt' => 'First request.',
+            'idempotency_key' => 'tenant-event-rate-limit-1',
+        ]);
+        $first->assertCreated();
+
+        $second = $this->authenticatedRequest('POST', "/api/v1/tenant/events/{$event->slug}/ai-edits", [
+            'photo_id' => $photo->id,
+            'style_id' => $style->id,
+            'prompt' => 'Second request.',
+            'idempotency_key' => 'tenant-event-rate-limit-2',
+        ]);
+        $second->assertStatus(429);
+    }
+
+    public function test_tenant_cannot_create_ai_edit_when_hard_budget_cap_is_reached(): void
+    {
+        $event = Event::factory()->create([
+            'tenant_id' => $this->tenant->id,
+            'status' => 'published',
+        ]);
+        $this->attachEntitledEventPackage($event);
+
+        $tenantSettings = (array) ($this->tenant->settings ?? []);
+        data_set($tenantSettings, 'ai_editing.budget.hard_cap_usd', 0.01);
+        $this->tenant->update(['settings' => $tenantSettings]);
+
+        $photo = Photo::factory()->for($event)->create([
+            'tenant_id' => $this->tenant->id,
+            'status' => 'approved',
+        ]);
+        $style = AiStyle::query()->create([
+            'key' => 'tenant-budget-cap-style',
+            'name' => 'Tenant Budget Cap',
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'requires_source_image' => true,
+            'is_active' => true,
+        ]);
+        AiUsageLedger::query()->create([
+            'tenant_id' => $this->tenant->id,
+            'event_id' => $event->id,
+            'entry_type' => AiUsageLedger::TYPE_DEBIT,
+            'quantity' => 1,
+            'unit_cost_usd' => 0.02,
+            'amount_usd' => 0.02,
+            'currency' => 'USD',
+            'recorded_at' => now(),
+        ]);
+
+        $response = $this->authenticatedRequest('POST', "/api/v1/tenant/events/{$event->slug}/ai-edits", [
+            'photo_id' => $photo->id,
+            'style_id' => $style->id,
+            'prompt' => 'Apply AI style.',
+            'idempotency_key' => 'tenant-budget-cap-1',
+        ]);
+
+        $response->assertForbidden()
+            ->assertJsonPath('error.code', 'budget_hard_cap_reached')
+            ->assertJsonPath('error.meta.budget.hard_reached', true);
+    }
+
+    public function test_tenant_prompt_block_records_abuse_metadata_when_escalation_threshold_is_reached(): void
+    {
+        config([
+            'ai-editing.abuse.escalation_threshold_per_hour' => 1,
+            'ai-editing.abuse.escalation_cooldown_minutes' => 1,
+        ]);
+        AiEditingSetting::flushCache();
+        AiEditingSetting::query()->create(array_merge(
+            AiEditingSetting::defaults(),
+            ['blocked_terms' => ['weapon']]
+        ));
+
+        $event = Event::factory()->create([
+            'tenant_id' => $this->tenant->id,
+            'status' => 'published',
+        ]);
+        $this->attachEntitledEventPackage($event);
+
+        $photo = Photo::factory()->for($event)->create([
+            'tenant_id' => $this->tenant->id,
+            'status' => 'approved',
+        ]);
+        $style = AiStyle::query()->create([
+            'key' => 'tenant-escalation-style',
+            'name' => 'Tenant Escalation',
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'requires_source_image' => true,
+            'is_active' => true,
+        ]);
+
+        $response = $this->authenticatedRequest('POST', "/api/v1/tenant/events/{$event->slug}/ai-edits", [
+            'photo_id' => $photo->id,
+            'style_id' => $style->id,
+            'prompt' => 'Add weapon effects.',
+            'idempotency_key' => 'tenant-escalation-1',
+        ]);
+
+        $response->assertCreated()
+            ->assertJsonPath('data.status', AiEditRequest::STATUS_BLOCKED)
+            ->assertJsonFragment(['abuse_escalation_threshold_reached']);
+
+        $requestId = (int) $response->json('data.id');
+        $editRequest = AiEditRequest::query()->find($requestId);
+
+        $this->assertNotNull($editRequest);
+        $this->assertIsArray($editRequest?->metadata);
+        $this->assertSame('prompt_block', $editRequest?->metadata['abuse']['type'] ?? null);
+        $this->assertTrue((bool) ($editRequest?->metadata['abuse']['escalated'] ?? false));
+    }
+
     public function test_tenant_cannot_create_ai_edit_when_event_ai_feature_is_disabled(): void
     {
         $event = Event::factory()->create([
@@ -685,7 +829,10 @@ class TenantAiEditControllerTest extends TenantTestCase
             ->assertJsonPath('data.total', 2)
             ->assertJsonPath('data.status_counts.succeeded', 1)
             ->assertJsonPath('data.status_counts.failed', 1)
-            ->assertJsonPath('data.failed_total', 1);
+            ->assertJsonPath('data.failed_total', 1)
+            ->assertJsonPath('data.usage.debit_count', 0)
+            ->assertJsonPath('data.observability.provider_runs_total', 0)
+            ->assertJsonPath('data.budget.hard_stop_enabled', true);
     }
 
     private function attachEntitledEventPackage(Event $event): EventPackage

tests/Feature/Console/AiEditsPruneCommandTest.php

@@ -0,0 +1,172 @@
+<?php
+
+namespace Tests\Feature\Console;
+
+use App\Models\AiEditOutput;
+use App\Models\AiEditRequest;
+use App\Models\AiProviderRun;
+use App\Models\AiStyle;
+use App\Models\AiUsageLedger;
+use App\Models\Event;
+use App\Models\Photo;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class AiEditsPruneCommandTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_command_prunes_stale_requests_and_ledgers(): void
+    {
+        config([
+            'ai-editing.retention.request_days' => 90,
+            'ai-editing.retention.usage_ledger_days' => 365,
+        ]);
+
+        [$oldRequest, $recentRequest] = $this->createRequestsForPruning();
+        [$oldLedger, $recentLedger] = $this->createLedgerEntriesForPruning($oldRequest, $recentRequest);
+
+        $this->artisan('ai-edits:prune')
+            ->expectsOutputToContain('AI prune candidates')
+            ->expectsOutputToContain('Pruned AI data')
+            ->assertExitCode(0);
+
+        $this->assertDatabaseMissing('ai_edit_requests', ['id' => $oldRequest->id]);
+        $this->assertDatabaseMissing('ai_provider_runs', ['request_id' => $oldRequest->id]);
+        $this->assertDatabaseMissing('ai_edit_outputs', ['request_id' => $oldRequest->id]);
+        $this->assertDatabaseHas('ai_edit_requests', ['id' => $recentRequest->id]);
+
+        $this->assertDatabaseMissing('ai_usage_ledgers', ['id' => $oldLedger->id]);
+        $this->assertNotNull($recentLedger);
+        if ($recentLedger) {
+            $this->assertDatabaseHas('ai_usage_ledgers', ['id' => $recentLedger->id]);
+        }
+    }
+
+    public function test_command_pretend_mode_does_not_delete_records(): void
+    {
+        config([
+            'ai-editing.retention.request_days' => 90,
+            'ai-editing.retention.usage_ledger_days' => 365,
+        ]);
+
+        [$oldRequest] = $this->createRequestsForPruning();
+        [$oldLedger] = $this->createLedgerEntriesForPruning($oldRequest, null);
+
+        $this->artisan('ai-edits:prune', ['--pretend' => true])
+            ->expectsOutputToContain('AI prune candidates')
+            ->expectsOutput('Pretend mode enabled. No records were deleted.')
+            ->assertExitCode(0);
+
+        $this->assertDatabaseHas('ai_edit_requests', ['id' => $oldRequest->id]);
+        $this->assertDatabaseHas('ai_usage_ledgers', ['id' => $oldLedger->id]);
+    }
+
+    /**
+     * @return array{0: AiEditRequest, 1: AiEditRequest}
+     */
+    private function createRequestsForPruning(): array
+    {
+        $event = Event::factory()->create(['status' => 'published']);
+        $photo = Photo::factory()->for($event)->create([
+            'tenant_id' => $event->tenant_id,
+            'status' => 'approved',
+        ]);
+        $style = AiStyle::query()->create([
+            'key' => 'prune-style',
+            'name' => 'Prune Style',
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'requires_source_image' => true,
+            'is_active' => true,
+        ]);
+
+        $oldRequest = AiEditRequest::query()->create([
+            'tenant_id' => $event->tenant_id,
+            'event_id' => $event->id,
+            'photo_id' => $photo->id,
+            'style_id' => $style->id,
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'status' => AiEditRequest::STATUS_SUCCEEDED,
+            'safety_state' => 'passed',
+            'prompt' => 'Old request',
+            'idempotency_key' => 'old-prune-request',
+            'queued_at' => now()->subDays(121),
+            'started_at' => now()->subDays(120),
+            'completed_at' => now()->subDays(120),
+            'expires_at' => now()->subDays(30),
+        ]);
+
+        AiProviderRun::query()->create([
+            'request_id' => $oldRequest->id,
+            'provider' => 'runware',
+            'attempt' => 1,
+            'provider_task_id' => 'old-task-id',
+            'status' => AiProviderRun::STATUS_SUCCEEDED,
+            'started_at' => now()->subDays(120),
+            'finished_at' => now()->subDays(120),
+        ]);
+        AiEditOutput::query()->create([
+            'request_id' => $oldRequest->id,
+            'provider_asset_id' => 'old-asset-id',
+            'provider_url' => 'https://cdn.example.invalid/old.jpg',
+            'safety_state' => 'passed',
+            'generated_at' => now()->subDays(120),
+        ]);
+
+        $recentRequest = AiEditRequest::query()->create([
+            'tenant_id' => $event->tenant_id,
+            'event_id' => $event->id,
+            'photo_id' => $photo->id,
+            'style_id' => $style->id,
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'status' => AiEditRequest::STATUS_SUCCEEDED,
+            'safety_state' => 'passed',
+            'prompt' => 'Recent request',
+            'idempotency_key' => 'recent-prune-request',
+            'queued_at' => now()->subDays(11),
+            'started_at' => now()->subDays(10),
+            'completed_at' => now()->subDays(10),
+        ]);
+
+        return [$oldRequest, $recentRequest];
+    }
+
+    /**
+     * @return array{0: AiUsageLedger, 1: ?AiUsageLedger}
+     */
+    private function createLedgerEntriesForPruning(AiEditRequest $oldRequest, ?AiEditRequest $recentRequest): array
+    {
+        $oldLedger = AiUsageLedger::query()->create([
+            'tenant_id' => $oldRequest->tenant_id,
+            'event_id' => $oldRequest->event_id,
+            'request_id' => $oldRequest->id,
+            'entry_type' => AiUsageLedger::TYPE_DEBIT,
+            'quantity' => 1,
+            'unit_cost_usd' => 0.01,
+            'amount_usd' => 0.01,
+            'currency' => 'USD',
+            'recorded_at' => now()->subDays(400),
+        ]);
+
+        if (! $recentRequest) {
+            return [$oldLedger, null];
+        }
+
+        $recentLedger = AiUsageLedger::query()->create([
+            'tenant_id' => $recentRequest->tenant_id,
+            'event_id' => $recentRequest->event_id,
+            'request_id' => $recentRequest->id,
+            'entry_type' => AiUsageLedger::TYPE_DEBIT,
+            'quantity' => 1,
+            'unit_cost_usd' => 0.01,
+            'amount_usd' => 0.01,
+            'currency' => 'USD',
+            'recorded_at' => now()->subDays(30),
+        ]);
+
+        return [$oldLedger, $recentLedger];
+    }
+}

tests/Feature/Console/AiEditsRecoverStuckCommandTest.php

@@ -0,0 +1,125 @@
+<?php
+
+namespace Tests\Feature\Console;
+
+use App\Jobs\PollAiEditRequest;
+use App\Jobs\ProcessAiEditRequest;
+use App\Models\AiEditRequest;
+use App\Models\AiProviderRun;
+use App\Models\AiStyle;
+use App\Models\Event;
+use App\Models\Photo;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Queue;
+use Tests\TestCase;
+
+class AiEditsRecoverStuckCommandTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_command_requeues_stuck_requests_with_scope_aware_job_selection(): void
+    {
+        [$queuedRequest, $processingRequest] = $this->createStuckRequests();
+
+        Queue::fake();
+
+        $this->artisan('ai-edits:recover-stuck', [
+            '--minutes' => 10,
+            '--requeue' => true,
+        ])->assertExitCode(0);
+
+        Queue::assertPushed(ProcessAiEditRequest::class, 1);
+        Queue::assertPushed(PollAiEditRequest::class, 1);
+        $this->assertDatabaseHas('ai_edit_requests', [
+            'id' => $queuedRequest->id,
+            'status' => AiEditRequest::STATUS_QUEUED,
+        ]);
+        $this->assertDatabaseHas('ai_edit_requests', [
+            'id' => $processingRequest->id,
+            'status' => AiEditRequest::STATUS_PROCESSING,
+        ]);
+    }
+
+    public function test_command_can_mark_stuck_requests_as_failed(): void
+    {
+        [$queuedRequest, $processingRequest] = $this->createStuckRequests();
+
+        $this->artisan('ai-edits:recover-stuck', [
+            '--minutes' => 10,
+            '--fail' => true,
+        ])->assertExitCode(0);
+
+        $this->assertDatabaseHas('ai_edit_requests', [
+            'id' => $queuedRequest->id,
+            'status' => AiEditRequest::STATUS_FAILED,
+            'failure_code' => 'operator_recovery_marked_failed',
+        ]);
+        $this->assertDatabaseHas('ai_edit_requests', [
+            'id' => $processingRequest->id,
+            'status' => AiEditRequest::STATUS_FAILED,
+            'failure_code' => 'operator_recovery_marked_failed',
+        ]);
+    }
+
+    /**
+     * @return array{0: AiEditRequest, 1: AiEditRequest}
+     */
+    private function createStuckRequests(): array
+    {
+        $event = Event::factory()->create(['status' => 'published']);
+        $photo = Photo::factory()->for($event)->create([
+            'tenant_id' => $event->tenant_id,
+            'status' => 'approved',
+        ]);
+        $style = AiStyle::query()->create([
+            'key' => 'recovery-style',
+            'name' => 'Recovery Style',
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'requires_source_image' => true,
+            'is_active' => true,
+        ]);
+
+        $queued = AiEditRequest::query()->create([
+            'tenant_id' => $event->tenant_id,
+            'event_id' => $event->id,
+            'photo_id' => $photo->id,
+            'style_id' => $style->id,
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'status' => AiEditRequest::STATUS_QUEUED,
+            'safety_state' => 'pending',
+            'prompt' => 'Transform image style.',
+            'idempotency_key' => 'stuck-queued-1',
+            'queued_at' => now()->subMinutes(45),
+            'updated_at' => now()->subMinutes(45),
+        ]);
+
+        $processing = AiEditRequest::query()->create([
+            'tenant_id' => $event->tenant_id,
+            'event_id' => $event->id,
+            'photo_id' => $photo->id,
+            'style_id' => $style->id,
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'status' => AiEditRequest::STATUS_PROCESSING,
+            'safety_state' => 'pending',
+            'prompt' => 'Transform image style.',
+            'idempotency_key' => 'stuck-processing-1',
+            'queued_at' => now()->subMinutes(50),
+            'started_at' => now()->subMinutes(40),
+            'updated_at' => now()->subMinutes(40),
+        ]);
+
+        AiProviderRun::query()->create([
+            'request_id' => $processing->id,
+            'provider' => 'runware',
+            'attempt' => 1,
+            'provider_task_id' => 'runware-task-recovery-1',
+            'status' => AiProviderRun::STATUS_RUNNING,
+            'started_at' => now()->subMinutes(39),
+        ]);
+
+        return [$queued, $processing];
+    }
+}

tests/Feature/Jobs/PollAiEditRequestTest.php

@@ -0,0 +1,142 @@
+<?php
+
+namespace Tests\Feature\Jobs;
+
+use App\Jobs\PollAiEditRequest;
+use App\Models\AiEditingSetting;
+use App\Models\AiEditRequest;
+use App\Models\AiProviderRun;
+use App\Models\AiStyle;
+use App\Models\Event;
+use App\Models\Photo;
+use App\Services\AiEditing\AiProviderResult;
+use App\Services\AiEditing\Providers\RunwareAiImageProvider;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use RuntimeException;
+use Tests\TestCase;
+
+class PollAiEditRequestTest extends TestCase
+{
+    use RefreshDatabase;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        AiEditingSetting::flushCache();
+    }
+
+    public function test_it_marks_request_failed_when_poll_attempts_are_exhausted(): void
+    {
+        AiEditingSetting::query()->create(array_merge(
+            AiEditingSetting::defaults(),
+            [
+                'runware_mode' => 'live',
+                'queue_auto_dispatch' => false,
+                'queue_max_polls' => 1,
+            ]
+        ));
+
+        $event = Event::factory()->create(['status' => 'published']);
+        $photo = Photo::factory()->for($event)->create([
+            'tenant_id' => $event->tenant_id,
+            'status' => 'approved',
+        ]);
+        $style = AiStyle::query()->create([
+            'key' => 'poll-exhaust-style',
+            'name' => 'Poll Exhaust',
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'requires_source_image' => true,
+            'is_active' => true,
+        ]);
+
+        $request = AiEditRequest::query()->create([
+            'tenant_id' => $event->tenant_id,
+            'event_id' => $event->id,
+            'photo_id' => $photo->id,
+            'style_id' => $style->id,
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'status' => AiEditRequest::STATUS_PROCESSING,
+            'safety_state' => 'pending',
+            'prompt' => 'Transform image style.',
+            'idempotency_key' => 'poll-exhaust-1',
+            'queued_at' => now()->subMinutes(3),
+            'started_at' => now()->subMinutes(2),
+        ]);
+
+        $providerRun = AiProviderRun::query()->create([
+            'request_id' => $request->id,
+            'provider' => 'runware',
+            'attempt' => 1,
+            'provider_task_id' => 'runware-task-1',
+            'status' => AiProviderRun::STATUS_RUNNING,
+            'started_at' => now()->subMinute(),
+        ]);
+
+        $provider = \Mockery::mock(RunwareAiImageProvider::class);
+        $provider->shouldReceive('poll')
+            ->once()
+            ->withArgs(function (AiEditRequest $polledRequest, string $taskId): bool {
+                return $polledRequest->id > 0 && $taskId === 'runware-task-1';
+            })
+            ->andReturn(AiProviderResult::processing('runware-task-1'));
+        $this->app->instance(RunwareAiImageProvider::class, $provider);
+
+        PollAiEditRequest::dispatchSync($request->id, 'runware-task-1', 1);
+
+        $request->refresh();
+        $providerRun->refresh();
+        $latestRun = $request->providerRuns()->latest('attempt')->first();
+
+        $this->assertSame(AiEditRequest::STATUS_FAILED, $request->status);
+        $this->assertSame('provider_poll_timeout', $request->failure_code);
+        $this->assertNotNull($request->completed_at);
+        $this->assertNotNull($latestRun);
+        $this->assertSame(AiProviderRun::STATUS_FAILED, $latestRun?->status);
+        $this->assertSame('Polling exhausted after 1 attempt(s).', $latestRun?->error_message);
+    }
+
+    public function test_poll_job_failed_hook_marks_request_as_failed(): void
+    {
+        $event = Event::factory()->create(['status' => 'published']);
+        $photo = Photo::factory()->for($event)->create([
+            'tenant_id' => $event->tenant_id,
+            'status' => 'approved',
+        ]);
+        $style = AiStyle::query()->create([
+            'key' => 'poll-failed-hook-style',
+            'name' => 'Poll Failed Hook',
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'requires_source_image' => true,
+            'is_active' => true,
+        ]);
+
+        $request = AiEditRequest::query()->create([
+            'tenant_id' => $event->tenant_id,
+            'event_id' => $event->id,
+            'photo_id' => $photo->id,
+            'style_id' => $style->id,
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'status' => AiEditRequest::STATUS_PROCESSING,
+            'safety_state' => 'pending',
+            'prompt' => 'Transform image style.',
+            'idempotency_key' => 'poll-failed-hook-1',
+            'queued_at' => now()->subMinute(),
+            'started_at' => now()->subSeconds(30),
+        ]);
+
+        $job = new PollAiEditRequest($request->id, 'runware-task-2', 2);
+        $job->failed(new RuntimeException('Polling crashed'));
+
+        $request->refresh();
+
+        $this->assertSame(AiEditRequest::STATUS_FAILED, $request->status);
+        $this->assertSame('queue_job_failed', $request->failure_code);
+        $this->assertSame('Polling crashed', $request->failure_message);
+        $this->assertNotNull($request->completed_at);
+    }
+}

tests/Feature/Jobs/ProcessAiEditRequestTest.php

@@ -9,7 +9,10 @@ use App\Models\AiStyle;
 use App\Models\AiUsageLedger;
 use App\Models\Event;
 use App\Models\Photo;
+use App\Services\AiEditing\AiProviderResult;
+use App\Services\AiEditing\Providers\RunwareAiImageProvider;
 use Illuminate\Foundation\Testing\RefreshDatabase;
+use RuntimeException;
 use Tests\TestCase;
 
 class ProcessAiEditRequestTest extends TestCase
@@ -187,5 +190,106 @@ class ProcessAiEditRequestTest extends TestCase
         $this->assertNotNull($request->completed_at);
         $this->assertSame(0, $request->outputs()->count());
         $this->assertSame(1, $request->providerRuns()->count());
+        $this->assertIsArray($request->metadata);
+        $this->assertSame('output_block', $request->metadata['abuse']['type'] ?? null);
+    }
+
+    public function test_it_marks_request_failed_when_provider_returns_processing_without_task_id(): void
+    {
+        AiEditingSetting::query()->create(array_merge(
+            AiEditingSetting::defaults(),
+            [
+                'runware_mode' => 'live',
+                'queue_auto_dispatch' => false,
+            ]
+        ));
+
+        $event = Event::factory()->create(['status' => 'published']);
+        $photo = Photo::factory()->for($event)->create([
+            'tenant_id' => $event->tenant_id,
+            'status' => 'approved',
+        ]);
+        $style = AiStyle::query()->create([
+            'key' => 'processing-no-task',
+            'name' => 'Processing Without Task ID',
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'requires_source_image' => true,
+            'is_active' => true,
+        ]);
+
+        $request = AiEditRequest::query()->create([
+            'tenant_id' => $event->tenant_id,
+            'event_id' => $event->id,
+            'photo_id' => $photo->id,
+            'style_id' => $style->id,
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'status' => AiEditRequest::STATUS_QUEUED,
+            'safety_state' => 'pending',
+            'prompt' => 'Transform image style.',
+            'idempotency_key' => 'job-processing-no-task',
+            'queued_at' => now(),
+        ]);
+
+        $provider = \Mockery::mock(RunwareAiImageProvider::class);
+        $provider->shouldReceive('submit')
+            ->once()
+            ->andReturn(new AiProviderResult(status: 'processing', providerTaskId: ''));
+        $this->app->instance(RunwareAiImageProvider::class, $provider);
+
+        ProcessAiEditRequest::dispatchSync($request->id);
+
+        $request->refresh();
+        $run = $request->providerRuns()->first();
+
+        $this->assertSame(AiEditRequest::STATUS_FAILED, $request->status);
+        $this->assertSame('provider_task_id_missing', $request->failure_code);
+        $this->assertNotNull($request->completed_at);
+        $this->assertNotNull($run);
+        $this->assertSame('failed', $run?->status);
+        $this->assertSame('Provider returned processing state without task identifier.', $run?->error_message);
+    }
+
+    public function test_process_job_failed_hook_marks_request_as_failed(): void
+    {
+        $event = Event::factory()->create(['status' => 'published']);
+        $photo = Photo::factory()->for($event)->create([
+            'tenant_id' => $event->tenant_id,
+            'status' => 'approved',
+        ]);
+        $style = AiStyle::query()->create([
+            'key' => 'failed-hook-style',
+            'name' => 'Failed Hook Style',
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'requires_source_image' => true,
+            'is_active' => true,
+        ]);
+
+        $request = AiEditRequest::query()->create([
+            'tenant_id' => $event->tenant_id,
+            'event_id' => $event->id,
+            'photo_id' => $photo->id,
+            'style_id' => $style->id,
+            'provider' => 'runware',
+            'provider_model' => 'runware-default',
+            'status' => AiEditRequest::STATUS_PROCESSING,
+            'safety_state' => 'pending',
+            'prompt' => 'Transform image style.',
+            'idempotency_key' => 'job-failed-hook-1',
+            'queued_at' => now()->subMinute(),
+            'started_at' => now()->subSeconds(30),
+        ]);
+
+        $job = new ProcessAiEditRequest($request->id);
+        $job->failed(new RuntimeException('Queue worker timeout'));
+
+        $request->refresh();
+
+        $this->assertSame(AiEditRequest::STATUS_FAILED, $request->status);
+        $this->assertSame('queue_job_failed', $request->failure_code);
+        $this->assertSame('Queue worker timeout', $request->failure_message);
+        $this->assertNotNull($request->completed_at);
     }
 }