feat(form-builder): ApplyBindings listener chain with two-transaction pattern (WS-6)

ApplyBindingsOnFormSubmit (sync) wraps the applicator in DB::transaction
and writes apply_status post-commit. On exception: outer catch records
FormSubmissionActionFailure in a separate transaction (survives inner
rollback), marks apply_status=failed, swallows so siblings keep running
(RFC Q3, Q4). When ApplyBindings provisions a Person on a previously
no-subject submission, the listener also writes subject_type/subject_id
back so TriggerPersonIdentityMatchOnFormSubmit (next sync listener) can
find the freshly-provisioned subject.

ApplyBindingsOnFormSectionSubmitted (queued, feature-flagged) ready
for ARTIST_ADVANCE activation per RFC Q10.

Listener chain on FormSubmissionSubmitted explicitly registered in
AppServiceProvider::boot for deterministic ordering (RFC Q1):
ApplyBindings → IdentityMatch → queued siblings.

FormBindingApplicator dropped 'final readonly' to 'class' so listener
tests can subclass it for throw-path coverage; constructor properties
remain readonly individually.

Refs: RFC-WS-6.md §3 (Q1, Q3, Q4, Q10)

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

api/app/FormBuilder/Bindings/FormBindingApplicator.php

@@ -27,13 +27,17 @@ use Throwable;
  *   - Q10: optional sectionId for future section-level apply.
  *   - Q12: hierarchical activity log via BindingActivityLogger.
  */
-final readonly class FormBindingApplicator
+// Not final + not readonly: listener tests need to override `apply()` for
+// throw-path coverage (Mockery can't mock final classes; PHP doesn't allow
+// extending readonly with non-readonly child). Properties stay readonly
+// individually to preserve immutability.
+class FormBindingApplicator
 {
     public function __construct(
-        private PurposeRegistry $purposeRegistry,
-        private BindingConflictResolver $conflictResolver,
-        private BindingTypeRegistry $typeRegistry,
-        private BindingActivityLogger $activityLogger,
+        private readonly PurposeRegistry $purposeRegistry,
+        private readonly BindingConflictResolver $conflictResolver,
+        private readonly BindingTypeRegistry $typeRegistry,
+        private readonly BindingActivityLogger $activityLogger,
     ) {}
 
     /**

api/app/Listeners/FormBuilder/ApplyBindingsOnFormSectionSubmitted.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Listeners\FormBuilder;
+
+use App\Events\FormBuilder\FormSubmissionSectionSubmitted;
+use App\FormBuilder\Bindings\FormBindingApplicator;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * RFC-WS-6 §3 (Q10) — STUB, feature-flagged off by default.
+ *
+ * REMOVAL TRIGGER: enable when ARTIST_ADVANCE feature work begins
+ * (post-S5). At enablement: write section-scoped tests, activate the
+ * dispatch from FormSubmissionService, remove the early-return guard,
+ * remove FORM_BUILDER_SECTION_APPLY from config.
+ *
+ * Tracking: BACKLOG.md → ARTIST-ADV-SECTION-APPLY
+ */
+final class ApplyBindingsOnFormSectionSubmitted implements ShouldQueue
+{
+    use InteractsWithQueue;
+
+    public function __construct(private readonly FormBindingApplicator $applicator) {}
+
+    public function handle(FormSubmissionSectionSubmitted $event): void
+    {
+        if (! (bool) config('form_builder.section_apply_enabled', false)) {
+            return;
+        }
+
+        // Active path: forward to applicator with sectionId filter.
+        // Wrapped in transaction (mirrors ApplyBindingsOnFormSubmit).
+        DB::transaction(function () use ($event): void {
+            $this->applicator->apply(
+                $event->submission,
+                sectionId: (string) $event->sectionStatus->form_schema_section_id,
+            );
+        });
+    }
+}

api/app/Listeners/FormBuilder/ApplyBindingsOnFormSubmit.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Listeners\FormBuilder;
+
+use App\Enums\FormBuilder\ApplyStatus;
+use App\Events\FormBuilder\FormSubmissionSubmitted;
+use App\FormBuilder\Bindings\FormBindingApplicator;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\FormBuilder\FormSubmission;
+use App\Models\FormBuilder\FormSubmissionActionFailure;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Throwable;
+
+/**
+ * RFC-WS-6 §3 (Q1, Q3, Q4) — applies bindings synchronously on
+ * FormSubmissionSubmitted. Two-transaction pattern: inner transaction
+ * for the apply pass + apply_status update; outer catch records a
+ * FormSubmissionActionFailure in a separate transaction (survives
+ * inner rollback).
+ *
+ * Throws are swallowed (RFC Q3) — sibling listeners must keep running.
+ *
+ * SYNCHRONOUS by design — does NOT implement ShouldQueue. Identity
+ * match runs after this in the registered listener order.
+ */
+final readonly class ApplyBindingsOnFormSubmit
+{
+    public function __construct(private FormBindingApplicator $applicator) {}
+
+    public function handle(FormSubmissionSubmitted $event): void
+    {
+        $submission = $event->submission->fresh(['schema']);
+        if (! $submission instanceof FormSubmission) {
+            return;
+        }
+
+        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(),
+                    ]);
+
+                if ($result->provisionedSubjectType !== null && $submission->subject_type === null) {
+                    // ApplyBindings just provisioned a Person; reflect it
+                    // on the submission so TriggerPersonIdentityMatch (next
+                    // sync listener) can find it.
+                    FormSubmission::query()
+                        ->whereKey($submission->id)
+                        ->update([
+                            'subject_type' => $result->provisionedSubjectType,
+                            'subject_id' => $result->provisionedSubjectId,
+                        ]);
+                }
+            });
+        } catch (Throwable $e) {
+            // OUTSIDE the failed transaction — survives rollback.
+            DB::transaction(function () use ($submission, $e): void {
+                $schema = $submission->schema;
+                $purposeValue = $schema instanceof FormSchema ? $schema->purpose->value : null;
+                FormSubmissionActionFailure::query()->create([
+                    'form_submission_id' => $submission->id,
+                    'listener_class' => self::class,
+                    'failed_at' => now(),
+                    'exception_class' => $e::class,
+                    'exception_message' => $e->getMessage(),
+                    'context' => [
+                        'purpose' => $purposeValue,
+                    ],
+                ]);
+                FormSubmission::query()
+                    ->whereKey($submission->id)
+                    ->update([
+                        'apply_status' => ApplyStatus::FAILED->value,
+                        'apply_completed_at' => now(),
+                    ]);
+            });
+            Log::error('form-builder.apply.transaction_rolled_back', [
+                'submission_id' => (string) $submission->id,
+                'exception' => $e::class,
+                'message' => $e->getMessage(),
+            ]);
+        }
+    }
+}

api/app/Providers/AppServiceProvider.php

@@ -50,7 +50,10 @@ use App\Models\UserInvitation;
 use App\Models\UserOrganisationTag;
 use App\Models\UserProfile;
 use App\Models\VolunteerAvailability;
+use App\Events\FormBuilder\FormSubmissionSectionSubmitted;
 use App\Events\FormBuilder\FormSubmissionSubmitted;
+use App\Listeners\FormBuilder\ApplyBindingsOnFormSectionSubmitted;
+use App\Listeners\FormBuilder\ApplyBindingsOnFormSubmit;
 use App\Listeners\FormBuilder\SyncTagPickerSelectionsOnSubmit;
 use App\Listeners\FormBuilder\TriggerPersonIdentityMatchOnFormSubmit;
 use App\Observers\FormBuilder\FormFieldChildTablesCascadeObserver;
@@ -129,18 +132,39 @@ class AppServiceProvider extends ServiceProvider
         FormField::observe(FormFieldChildTablesCascadeObserver::class);
         FormFieldLibrary::observe(FormFieldChildTablesCascadeObserver::class);
 
-        // ARCH §31.10 — FORM-02 TAG_PICKER sync listener.
+        // RFC-WS-6 §3 (Q1) — sync chain on FormSubmissionSubmitted, in
+        // this exact order:
+        //   1. ApplyBindingsOnFormSubmit                (sync)
+        //   2. TriggerPersonIdentityMatchOnFormSubmit   (sync)
+        // Queued listeners on the same event (SyncTagPickerSelectionsOnSubmit,
+        // future webhook dispatcher, mailables) run in parallel after the
+        // sync chain via the queue. Their relative registration position
+        // is irrelevant.
+
+        // RFC Q1 — applies bindings sync before identity match runs.
+        \Illuminate\Support\Facades\Event::listen(
+            FormSubmissionSubmitted::class,
+            ApplyBindingsOnFormSubmit::class,
+        );
+
+        // ARCH §31.10 — FORM-02 TAG_PICKER sync listener (queued).
         \Illuminate\Support\Facades\Event::listen(
             FormSubmissionSubmitted::class,
             SyncTagPickerSelectionsOnSubmit::class,
         );
 
-        // ARCH §31.1 — identity-match trigger on event_registration.
+        // ARCH §31.1 — identity-match trigger on event_registration (sync).
         \Illuminate\Support\Facades\Event::listen(
             FormSubmissionSubmitted::class,
             TriggerPersonIdentityMatchOnFormSubmit::class,
         );
 
+        // RFC Q10 — section-level apply stub. Runtime gated by feature flag.
+        \Illuminate\Support\Facades\Event::listen(
+            FormSubmissionSectionSubmitted::class,
+            ApplyBindingsOnFormSectionSubmitted::class,
+        );
+
         ResetPassword::createUrlUsing(function ($user, string $token) {
             return config('crewli.portal_url') . '/wachtwoord-resetten?token=' . $token . '&email=' . urlencode($user->email);
         });