feat(form-builder): retry history table + integration (WS-6)

Per-attempt retry history (timestamp, user, outcome, exception detail
if failed) replaces the counter-only retry_count tracking.

Changes:

- New `form_submission_action_failure_retry_attempts` table (cascade on
  parent delete, nullOnDelete on user). Explicit short FK names
  (`fsafra_failure_fk`, `fsafra_user_fk`) — auto-generated names exceed
  MySQL's 64-char identifier limit.
- New FormSubmissionActionFailureRetryAttempt model + factory +
  succeeded() state.
- Parent FormSubmissionActionFailure gets retryAttempts() HasMany
  relation (latest('attempted_at')).
- New FormFailureRetryService centralises the retry-flow logic. Both
  the API controller and the artisan command delegate to it. Service
  writes a retry_attempt record per attempt; parent's retry_count
  stays as denormalised cache for index-view performance.
- Successful retry: attempt(succeeded) + parent.retry_count++ +
  parent.resolved_at + parent.resolved_by_user_id + parent.resolved_note
  ("Geslaagde retry door {actor.name}" or "Geslaagde retry
  (geautomatiseerd)" for command-line invocation without an actor).
- Failed retry: attempt(failed) with NEW exception details +
  parent.retry_count++. Parent's exception_class/_message stay
  audit-immutable — they represent the FIRST failure.
- canBeRetried() now correctly checks both resolved_at AND
  dismissed_at (sessie 2's open question Q2 closure).
- New FailureNotRetriableException (controller → 422) and
  ParentSubmissionGoneException (controller → 410) for cleaner
  flow control.

12 new tests:
- FormSubmissionActionFailureRetryAttemptTest (5 unit tests)
- RetryFlowProducesRetryAttemptsTest (7 integration tests covering
  succeeded path, failed path, resolved/dismissed blocking,
  multiple-retries chronological ordering, canBeRetried truth tables)

Pre-existing tests touched:
- FormSubmissionActionFailureTest::test_can_be_retried_only_for_open_state
  — updated to reflect Q2 closure (resolved now blocks too).
- Ws6FoundationMigrationTest::test_down_methods_clean_up_columns_and_table
  — child table must drop before parent (FK constraint).
- 5 backfill test step-counts bumped +1 (new migration sits at top).

SCHEMA.md → v2.9. Schema dump regenerated.

Refs: RFC-WS-6.md §3 Q5 addendum, sessie 2 Q2

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

api/app/Console/Commands/RetryFormSubmissionActionFailures.php

@@ -4,14 +4,12 @@ declare(strict_types=1);
 
 namespace App\Console\Commands;
 
-use App\Enums\FormBuilder\ApplyStatus;
-use App\FormBuilder\Bindings\FormBindingApplicator;
-use App\Models\FormBuilder\FormSubmission;
+use App\Exceptions\FormBuilder\FailureNotRetriableException;
+use App\Exceptions\FormBuilder\ParentSubmissionGoneException;
 use App\Models\FormBuilder\FormSubmissionActionFailure;
+use App\Services\FormBuilder\FormFailureRetryService;
 use Illuminate\Console\Command;
 use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Support\Facades\DB;
-use Throwable;
 
 /**
  * RFC-WS-6 §3 (Q5) — replay open failures via the applicator.
@@ -29,7 +27,7 @@ final class RetryFormSubmissionActionFailures extends Command
 
     protected $description = 'Replay open FormSubmissionActionFailure rows via the applicator';
 
-    public function handle(FormBindingApplicator $applicator): int
+    public function handle(FormFailureRetryService $retryService): int
     {
         if (
             $this->option('id') === null
@@ -54,10 +52,11 @@ final class RetryFormSubmissionActionFailures extends Command
         foreach ($failures as $failure) {
             if ($this->option('dry-run')) {
                 $rows[] = ['id' => (string) $failure->id, 'submission' => (string) $failure->form_submission_id, 'result' => 'would-retry'];
+
                 continue;
             }
 
-            $rows[] = $this->retryOne($failure, $applicator);
+            $rows[] = $this->retryOne($failure, $retryService);
         }
 
         $this->table(['id', 'submission', 'result'], $rows);
@@ -95,48 +94,28 @@ final class RetryFormSubmissionActionFailures extends Command
     /**
      * @return array{id:string, submission:string, result:string}
      */
-    private function retryOne(FormSubmissionActionFailure $failure, FormBindingApplicator $applicator): array
+    private function retryOne(FormSubmissionActionFailure $failure, FormFailureRetryService $retryService): array
     {
-        $submission = FormSubmission::query()->withoutGlobalScopes()->find($failure->form_submission_id);
-        if ($submission === null) {
-            return ['id' => (string) $failure->id, 'submission' => (string) $failure->form_submission_id, 'result' => 'submission-gone'];
-        }
-
         try {
-            DB::transaction(function () use ($applicator, $submission): void {
-                $result = $applicator->apply($submission);
-                FormSubmission::query()
-                    ->whereKey($submission->id)
-                    ->update([
-                        'apply_status' => $result->applyStatus()->value,
-                        'apply_completed_at' => now(),
-                    ]);
-            });
-            $failure->retry_count = (int) $failure->retry_count + 1;
-            $failure->resolved_at = now();
-            $failure->save();
+            $result = $retryService->retry($failure);
 
-            return ['id' => (string) $failure->id, 'submission' => (string) $submission->id, 'result' => 'succeeded'];
-        } catch (Throwable $e) {
-            // Append a NEW row preserving history, increment retry_count on original.
-            DB::transaction(function () use ($failure, $submission, $e): void {
-                FormSubmissionActionFailure::query()->create([
-                    'form_submission_id' => $submission->id,
-                    'listener_class' => $failure->listener_class,
-                    'failed_at' => now(),
-                    'exception_class' => $e::class,
-                    'exception_message' => $e->getMessage(),
-                    'context' => ['retry_of' => (string) $failure->id],
-                ]);
-                FormSubmissionActionFailure::query()
-                    ->whereKey($failure->id)
-                    ->update(['retry_count' => (int) $failure->retry_count + 1]);
-                FormSubmission::query()
-                    ->whereKey($submission->id)
-                    ->update(['apply_status' => ApplyStatus::FAILED->value]);
-            });
-
-            return ['id' => (string) $failure->id, 'submission' => (string) $submission->id, 'result' => 'failed-again'];
+            return [
+                'id' => (string) $failure->id,
+                'submission' => (string) $failure->form_submission_id,
+                'result' => $result['outcome'] === 'succeeded' ? 'succeeded' : 'failed-again',
+            ];
+        } catch (FailureNotRetriableException $e) {
+            return [
+                'id' => (string) $failure->id,
+                'submission' => (string) $failure->form_submission_id,
+                'result' => "skipped-{$e->reason}",
+            ];
+        } catch (ParentSubmissionGoneException) {
+            return [
+                'id' => (string) $failure->id,
+                'submission' => (string) $failure->form_submission_id,
+                'result' => 'submission-gone',
+            ];
         }
     }
 }

api/app/Exceptions/FormBuilder/FailureNotRetriableException.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\FormBuilder;
+
+use RuntimeException;
+
+/**
+ * Thrown by FormFailureRetryService when canBeRetried() returns false.
+ * Controller maps to 422; artisan command displays the reason and skips.
+ */
+final class FailureNotRetriableException extends RuntimeException
+{
+    public function __construct(public readonly string $reason)
+    {
+        parent::__construct("Failure is {$reason}; cannot retry.");
+    }
+}

api/app/Exceptions/FormBuilder/ParentSubmissionGoneException.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\FormBuilder;
+
+use RuntimeException;
+
+/**
+ * Thrown by FormFailureRetryService when the failure's parent
+ * submission has been deleted. Controller maps to 410 Gone.
+ */
+final class ParentSubmissionGoneException extends RuntimeException
+{
+    public function __construct()
+    {
+        parent::__construct('Parent submission has been deleted.');
+    }
+}

api/app/Http/Controllers/Api/V1/FormBuilder/FormSubmissionActionFailureController.php

@@ -4,22 +4,21 @@ declare(strict_types=1);
 
 namespace App\Http\Controllers\Api\V1\FormBuilder;
 
-use App\Enums\FormBuilder\ApplyStatus;
 use App\Enums\FormBuilder\DismissalReasonType;
-use App\FormBuilder\Bindings\FormBindingApplicator;
+use App\Exceptions\FormBuilder\FailureNotRetriableException;
+use App\Exceptions\FormBuilder\ParentSubmissionGoneException;
 use App\Http\Controllers\Controller;
 use App\Http\Requests\FormBuilder\DismissFailureRequest;
 use App\Http\Requests\FormBuilder\ResolveFailureRequest;
 use App\Http\Resources\FormBuilder\FormSubmissionActionFailureResource;
-use App\Models\FormBuilder\FormSubmission;
 use App\Models\FormBuilder\FormSubmissionActionFailure;
 use App\Models\Organisation;
+use App\Services\FormBuilder\FormFailureRetryService;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
 use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
-use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Gate;
-use Throwable;
 
 /**
  * RFC-WS-6 §3 (Q5) + §4 (V3) — admin endpoints for the binding-pipeline
@@ -41,7 +40,7 @@ final class FormSubmissionActionFailureController extends Controller
 
         $failures = FormSubmissionActionFailure::query()
             ->whereHas('submission', function ($q) use ($organisation): void {
-                /** @var \Illuminate\Database\Eloquent\Builder<FormSubmission> $q */
+                /** @var \Illuminate\Database\Eloquent\Builder<\App\Models\FormBuilder\FormSubmission> $q */
                 $q->where('organisation_id', $organisation->id);
             })
             ->latest('failed_at')
@@ -74,59 +73,30 @@ final class FormSubmissionActionFailureController extends Controller
         return new FormSubmissionActionFailureResource($formSubmissionActionFailure);
     }
 
-    public function retry(?Organisation $organisation, FormSubmissionActionFailure $formSubmissionActionFailure, FormBindingApplicator $applicator): FormSubmissionActionFailureResource|JsonResponse
-    {
+    public function retry(
+        ?Organisation $organisation,
+        FormSubmissionActionFailure $formSubmissionActionFailure,
+        Request $request,
+        FormFailureRetryService $retryService,
+    ): FormSubmissionActionFailureResource|JsonResponse {
         unset($organisation);
         $failure = $formSubmissionActionFailure;
         $this->authorizeOrNotFound('retry', $failure);
 
-        if (! $failure->canBeRetried()) {
+        try {
+            $retryService->retry($failure, $request->user());
+        } catch (FailureNotRetriableException $e) {
             return response()->json([
                 'error' => 'cannot_retry',
-                'message' => 'Failure is dismissed; cannot retry.',
+                'message' => $e->getMessage(),
             ], 422);
-        }
-
-        $submission = $failure->submission;
-        if ($submission === null) {
+        } catch (ParentSubmissionGoneException $e) {
             return response()->json([
                 'error' => 'submission_gone',
-                'message' => 'Parent submission has been deleted.',
+                'message' => $e->getMessage(),
             ], 410);
         }
 
-        try {
-            DB::transaction(function () use ($applicator, $submission): void {
-                $result = $applicator->apply($submission);
-                FormSubmission::query()
-                    ->whereKey($submission->id)
-                    ->update([
-                        'apply_status' => $result->applyStatus()->value,
-                        'apply_completed_at' => now(),
-                    ]);
-            });
-            $failure->retry_count = (int) $failure->retry_count + 1;
-            $failure->resolved_at = now();
-            $failure->save();
-        } catch (Throwable $e) {
-            DB::transaction(function () use ($failure, $submission, $e): void {
-                FormSubmissionActionFailure::query()->create([
-                    'form_submission_id' => $submission->id,
-                    'listener_class' => $failure->listener_class,
-                    'failed_at' => now(),
-                    'exception_class' => $e::class,
-                    'exception_message' => $e->getMessage(),
-                    'context' => ['retry_of' => (string) $failure->id],
-                ]);
-                FormSubmissionActionFailure::query()
-                    ->whereKey($failure->id)
-                    ->update(['retry_count' => (int) $failure->retry_count + 1]);
-                FormSubmission::query()
-                    ->whereKey($submission->id)
-                    ->update(['apply_status' => ApplyStatus::FAILED->value]);
-            });
-        }
-
         return new FormSubmissionActionFailureResource($failure->refresh());
     }
 

api/app/Models/FormBuilder/FormSubmissionActionFailure.php

@@ -11,6 +11,7 @@ use Illuminate\Database\Eloquent\Concerns\HasUlids;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 
 /**
  * RFC-WS-6 §3 (Q5) — audit table for binding-pipeline failures.
@@ -29,6 +30,7 @@ final class FormSubmissionActionFailure extends Model
 {
     /** @use HasFactory<\Database\Factories\FormBuilder\FormSubmissionActionFailureFactory> */
     use HasFactory;
+
     use HasUlids;
 
     protected $table = 'form_submission_action_failures';
@@ -85,6 +87,19 @@ final class FormSubmissionActionFailure extends Model
         return $this->belongsTo(User::class, 'dismissed_by_user_id');
     }
 
+    /**
+     * RFC-WS-6 Q5 addendum (sessie 3c) — per-attempt retry history.
+     * `retry_count` on this model stays as denormalized cache; the
+     * detail UI consumes this relation for per-attempt timeline.
+     *
+     * @return HasMany<FormSubmissionActionFailureRetryAttempt, $this>
+     */
+    public function retryAttempts(): HasMany
+    {
+        return $this->hasMany(FormSubmissionActionFailureRetryAttempt::class, 'form_submission_action_failure_id')
+            ->latest('attempted_at');
+    }
+
     /**
      * @param  Builder<FormSubmissionActionFailure>  $query
      * @return Builder<FormSubmissionActionFailure>
@@ -117,8 +132,14 @@ final class FormSubmissionActionFailure extends Model
         return $this->resolved_at === null && $this->dismissed_at === null;
     }
 
+    /**
+     * Sessie 3c (Q2 closure): a resolved failure also blocks retry —
+     * retrying a closed failure would either no-op or trigger a
+     * spurious state transition. Both are unwanted. Open is the only
+     * retriable state.
+     */
     public function canBeRetried(): bool
     {
-        return $this->dismissed_at === null;
+        return $this->resolved_at === null && $this->dismissed_at === null;
     }
 }

api/app/Models/FormBuilder/FormSubmissionActionFailureRetryAttempt.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models\FormBuilder;
+
+use App\Models\User;
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * RFC-WS-6.md §3 Q5 addendum — per-attempt retry history.
+ *
+ * Each retry of a FormSubmissionActionFailure produces a row here.
+ * Outcome is 'succeeded' (parent gets resolved_at + system note) or
+ * 'failed' (parent remains open with retry_count incremented; if the
+ * exception details differ from the original, they're captured
+ * per-attempt). Parent's own `exception_class` / `exception_message`
+ * stay audit-immutable — they represent the FIRST failure, not the
+ * latest retry.
+ */
+final class FormSubmissionActionFailureRetryAttempt extends Model
+{
+    /** @use HasFactory<\Database\Factories\FormBuilder\FormSubmissionActionFailureRetryAttemptFactory> */
+    use HasFactory;
+
+    use HasUlids;
+
+    protected $table = 'form_submission_action_failure_retry_attempts';
+
+    protected $fillable = [
+        'form_submission_action_failure_id',
+        'attempted_at',
+        'attempted_by_user_id',
+        'outcome',
+        'exception_class',
+        'exception_message',
+    ];
+
+    /** @var array<string, string> */
+    protected $casts = [
+        'attempted_at' => 'datetime',
+    ];
+
+    /** @return BelongsTo<FormSubmissionActionFailure, $this> */
+    public function failure(): BelongsTo
+    {
+        return $this->belongsTo(FormSubmissionActionFailure::class, 'form_submission_action_failure_id');
+    }
+
+    /** @return BelongsTo<User, $this> */
+    public function attemptedBy(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'attempted_by_user_id');
+    }
+}

api/app/Services/FormBuilder/FormFailureRetryService.php

@@ -0,0 +1,135 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\FormBuilder;
+
+use App\Enums\FormBuilder\ApplyStatus;
+use App\Exceptions\FormBuilder\FailureNotRetriableException;
+use App\Exceptions\FormBuilder\ParentSubmissionGoneException;
+use App\FormBuilder\Bindings\FormBindingApplicator;
+use App\Models\FormBuilder\FormSubmission;
+use App\Models\FormBuilder\FormSubmissionActionFailure;
+use App\Models\FormBuilder\FormSubmissionActionFailureRetryAttempt;
+use App\Models\User;
+use Illuminate\Support\Facades\DB;
+use Throwable;
+
+/**
+ * RFC-WS-6 §3 (Q5) sessie 3c — centralised retry-flow logic.
+ *
+ * The controller's `retry` action AND the artisan command both delegate
+ * here so the per-attempt record write stays consistent across paths.
+ *
+ * Flow:
+ *   1. canBeRetried() guard (open = resolved_at IS NULL AND dismissed_at IS NULL)
+ *   2. Run the applicator inside a transaction
+ *   3. On success: write retry_attempt(outcome=succeeded), increment
+ *      retry_count, set resolved_at + system note + resolved_by_user_id
+ *   4. On failure: write retry_attempt(outcome=failed) with the NEW
+ *      exception details, increment retry_count. Parent's own
+ *      exception_class / exception_message stay audit-immutable —
+ *      they represent the FIRST failure.
+ */
+final readonly class FormFailureRetryService
+{
+    public function __construct(private FormBindingApplicator $applicator) {}
+
+    /**
+     * @return array{outcome: 'succeeded'|'failed', attempt: FormSubmissionActionFailureRetryAttempt}
+     *
+     * @throws FailureNotRetriableException
+     * @throws ParentSubmissionGoneException
+     */
+    public function retry(FormSubmissionActionFailure $failure, ?User $actor = null): array
+    {
+        if (! $failure->canBeRetried()) {
+            throw new FailureNotRetriableException($failure->resolved_at !== null ? 'resolved' : 'dismissed');
+        }
+
+        /** @var FormSubmission|null $submission */
+        $submission = FormSubmission::query()->withoutGlobalScopes()->find($failure->form_submission_id);
+        if ($submission === null) {
+            throw new ParentSubmissionGoneException;
+        }
+
+        try {
+            DB::transaction(function () use ($submission): void {
+                $result = $this->applicator->apply($submission);
+                FormSubmission::query()
+                    ->whereKey($submission->id)
+                    ->update([
+                        'apply_status' => $result->applyStatus()->value,
+                        'apply_completed_at' => now(),
+                    ]);
+            });
+
+            $attempt = $this->recordSuccess($failure, $actor);
+
+            return ['outcome' => 'succeeded', 'attempt' => $attempt];
+        } catch (Throwable $e) {
+            $attempt = $this->recordFailure($failure, $submission, $actor, $e);
+
+            return ['outcome' => 'failed', 'attempt' => $attempt];
+        }
+    }
+
+    private function recordSuccess(FormSubmissionActionFailure $failure, ?User $actor): FormSubmissionActionFailureRetryAttempt
+    {
+        return DB::transaction(function () use ($failure, $actor): FormSubmissionActionFailureRetryAttempt {
+            /** @var FormSubmissionActionFailureRetryAttempt $attempt */
+            $attempt = FormSubmissionActionFailureRetryAttempt::query()->create([
+                'form_submission_action_failure_id' => $failure->id,
+                'attempted_at' => now(),
+                'attempted_by_user_id' => $actor?->id,
+                'outcome' => 'succeeded',
+                'exception_class' => null,
+                'exception_message' => null,
+            ]);
+
+            $note = $actor instanceof User
+                ? "Geslaagde retry door {$actor->name}"
+                : 'Geslaagde retry (geautomatiseerd)';
+
+            FormSubmissionActionFailure::query()
+                ->whereKey($failure->id)
+                ->update([
+                    'retry_count' => DB::raw('retry_count + 1'),
+                    'resolved_at' => now(),
+                    'resolved_by_user_id' => $actor?->id,
+                    'resolved_note' => $note,
+                ]);
+
+            return $attempt;
+        });
+    }
+
+    private function recordFailure(
+        FormSubmissionActionFailure $failure,
+        FormSubmission $submission,
+        ?User $actor,
+        Throwable $e,
+    ): FormSubmissionActionFailureRetryAttempt {
+        return DB::transaction(function () use ($failure, $submission, $actor, $e): FormSubmissionActionFailureRetryAttempt {
+            /** @var FormSubmissionActionFailureRetryAttempt $attempt */
+            $attempt = FormSubmissionActionFailureRetryAttempt::query()->create([
+                'form_submission_action_failure_id' => $failure->id,
+                'attempted_at' => now(),
+                'attempted_by_user_id' => $actor?->id,
+                'outcome' => 'failed',
+                'exception_class' => $e::class,
+                'exception_message' => $e->getMessage(),
+            ]);
+
+            FormSubmissionActionFailure::query()
+                ->whereKey($failure->id)
+                ->update(['retry_count' => DB::raw('retry_count + 1')]);
+
+            FormSubmission::query()
+                ->whereKey($submission->id)
+                ->update(['apply_status' => ApplyStatus::FAILED->value]);
+
+            return $attempt;
+        });
+    }
+}