crewli/dev-docs/ARCH-BINDINGS.md

# ARCH-BINDINGS.md — FormBindingApplicator Pipeline

**Version:** v1.2 — incorporates RFC-WS-6 v1.3.1 drift closure (2026-05-08)
**Aligned to:** `main` HEAD `4a84b9e` (post WS-6 closure, 2026-05-04)
**Authoritative:** Yes. This document supersedes `RFC-WS-6.md` for ongoing maintenance — RFC-WS-6 remains as a historical record of the 2026-04-25 design session that produced this architecture.

---

## 1. Status & how to use this doc

This document is the canonical reference for the FormBindingApplicator pipeline: the system that turns a submitted form into mutations on domain entities (persons, users, artists, companies, etc.). The pipeline lives behind the `FormSubmissionSubmitted` event and runs synchronously where ordering matters and queued where it does not.

ARCH-BINDINGS is the **second-tier** form-builder reference. ARCH-FORM-BUILDER is the umbrella doc covering the full form-builder domain (schemas, fields, sections, submissions, values, library, webhooks, integrations). ARCH-BINDINGS narrows in on the pipeline that connects submissions to domain entities.

### Read this for…

| Goal | Read |
|---|---|
| Modify the apply pipeline (add a strategy, change a listener) | §2, §5, §6, §17 |
| Build the Form Builder UI bindings editor | §3, §4, §8, §9 |
| Wire observability for binding events | §7, §11, §14 |
| Add a new FormPurpose | §3, §9 |
| Diagnose a production binding failure | §11, §12, §14 |
| Understand why a guard rejected a publish | §8 |
| Implement library-bindings UI | §15 |
| Audit GDPR compliance of a submission | §14, §16 |

### Cross-document relations

- **ARCH-FORM-BUILDER.md** — sibling, authoritative for `form_field_bindings` table shape (§17), per-purpose lifecycles (§3.2), integration contracts to non-binding listeners (§31), purpose registry mechanics (§17.3)
- **SCHEMA.md §3.5.12** — authoritative for `form_submissions`, `form_field_bindings`, `form_submission_action_failures` table shape
- **RFC-WS-6.md** — historical design source; cited in this doc as `RFC-WS-6 §X` for the "why" behind any decision
- **ARCH-CONSOLIDATION-2026-04.md** §6.2 — WS-6 charter and post-WS-6 deliverables list
- **ARCH-CONSOLIDATION-ADDENDUM-2026-04-24.md** Q1, Q2 — ULID exception retired, denormalized `organisation_id`
- **ARCH-OBSERVABILITY.md** (WS-8b, forthcoming) — how pipeline events surface in GlitchTip and Telescope, PII-scrubbing contract for failure exports
- **BACKLOG.md** — deferred items referenced throughout this doc

### Stability commitment

The contracts in §3 (`BindingTypeRegistry`), §4 (merge strategies), §5 (listener chain), §6 (two-transaction pattern), §7 (status columns), §8 (PublishGuard interface), §9 (PurposeGuardProvider) are stable. Changes require an RFC and a coordinated update of this doc + tests + ARCH-FORM-BUILDER cross-refs.

The contracts in §10 (section-level apply), §11 (`form_submission_action_failures`), §12 (retry/resolve/dismiss flows) are stable but feature-flagged or admin-only — additive changes are expected.

---

## 2. The pipeline at a glance

### 2.1 Diagram

```
┌─────────────────────────────────────────────────────────────────┐
│ FormSubmissionService::submit($submission)                      │
│                                                                 │
│   DB::transaction (inner):                                      │
│     1. validate                                                 │
│     2. write form_values                                        │
│     3. update submission.status                                 │
│     4. write submission.schema_snapshot (canonicalized)         │
│   commit                                                        │
│                                                                 │
│   event(new FormSubmissionSubmitted($submission->refresh()))    │
└─────────────────────────────────────────────────────────────────┘
                               │
       ┌───────────────────────┴────────────────────────┐
       │                                                │
       ▼ SYNC chain (registration order)                ▼ QUEUED listeners
                                                         (parallel, no ordering)
  ┌─────────────────────────────────┐
  │ ApplyBindingsOnFormSubmit       │      ┌──────────────────────────────┐
  │  ├─ resolveOrProvisionSubject   │      │ SyncTagPickerSelectionsOnSubmit
  │  ├─ DB::transaction (inner)     │      ├──────────────────────────────┤
  │  │   ├─ resolve bindings        │      │ CreateProvisionalShift…OnReg.│
  │  │   ├─ apply per binding       │      ├──────────────────────────────┤
  │  │   ├─ writeApplyStatus(OK)    │      │ FormWebhookDispatcher        │
  │  │   └─ triggerIdentityMatch    │      │   → DeliverFormWebhookJob    │
  │  │     (status update only)     │      ├──────────────────────────────┤
  │  ├─ catch → DB::transaction     │      │ AddPersonToApplicableCrowd…  │
  │  │   (outer, separate)          │      ├──────────────────────────────┤
  │  │   ├─ FormSubmissionAction…   │      │ RegistrationConfirmation     │
  │  │   │   Failure::create        │      │   (purpose-specific mailable)│
  │  │   └─ writeApplyStatus(FAIL)  │      └──────────────────────────────┘
  │  └─ swallow exception           │
  └─────────────────────────────────┘
                │
                ▼
  ┌─────────────────────────────────┐
  │ TriggerPersonIdentityMatch…     │
  │  (sync, runs second)            │
  │  ├─ if subject_type=null:       │
  │  │   log warning, set 'pending' │
  │  └─ else:                       │
  │     PersonIdentityService::     │
  │       detectMatches($person)    │
  └─────────────────────────────────┘
```

### 2.2 What the pipeline is — and is not

The pipeline **is**:
- A mechanism for translating form values into domain-entity attribute mutations under purpose-specific rules
- A pre-publish validation framework that prevents structurally unsafe schemas from going live
- An audit infrastructure (apply_status, action_failures, activity log)
- A failure-recovery surface (retry / resolve / dismiss flows)

The pipeline **is not**:
- A workflow engine — there are no per-step states, approvals, or human-in-the-loop branches
- A scheduler — all work fires from `FormSubmissionSubmitted` in real time (sync) or near-real-time (queued)
- A data-transformation layer — values are written as-resolved, not transformed mid-flight
- A notification system — mailables are siblings of the pipeline, not part of it

### 2.3 Glossary

| Term | Meaning |
|---|---|
| **binding** | A row in `form_field_bindings` connecting a `form_field` to a `target_entity.target_attribute` with a `merge_strategy`, `trust_level`, and optional `is_identity_key` flag |
| **target_entity** | The Eloquent model class (morph alias) that receives the mutation: `person`, `user`, `artist`, `company`, etc. |
| **target_attribute** | The attribute path on the target_entity, e.g. `email`, `profile.t_shirt_size`, `tags` (collection) |
| **trust_level** | Integer 0–100 expressing how authoritative this binding is when multiple bindings target the same attribute |
| **merge_strategy** | One of `overwrite`, `append`, `replace`, `first_write_wins` — see §4 |
| **is_identity_key** | Boolean flag marking a binding as the lookup key for `firstOrCreate` semantics; max one per `target_entity` per schema |
| **apply_status** | Column on `form_submissions` tracking pipeline-completion state: `null` (not applicable), `pending`, `completed`, `failed` |
| **identity_match_status** | Existing column on `form_submissions` tracking person-identity-match progress: `pending`, `matched`, `no_match`, `auto_linked` |
| **PublishGuard** | A pre-publish check that returns `PublishGuardResult` (passed or one or more violation messages); see §8 |
| **PurposeGuardProvider** | A service interface returning the `list<PublishGuard>` for a given purpose; see §9 |
| **action failure** | A row in `form_submission_action_failures` recording a binding-pipeline exception that survived the inner-transaction rollback |
| **DismissalReasonType** | Enum of 6 reasons an action failure can be dismissed without retry |

---

## 3. Configuration: BindingTypeRegistry & config files

### 3.1 `config/form_builder/bindings.php`

The `BindingTypeRegistry` is the **single source of truth** for what shape a target attribute has at runtime. The file maps every supported `target_entity.target_attribute` pair to a `BindingTargetType`:

```php
return [
    'targets' => [
        'person' => [
            'email' => BindingTargetType::SCALAR,
            'first_name' => BindingTargetType::SCALAR,
            'last_name' => BindingTargetType::SCALAR,
            'date_of_birth' => BindingTargetType::SCALAR,
            'phone' => BindingTargetType::SCALAR,
            'tags' => BindingTargetType::COLLECTION,
            'crowd_type_id' => BindingTargetType::RELATION,
            // ...
        ],
        'user' => [
            'email' => BindingTargetType::SCALAR,
            'profile.t_shirt_size' => BindingTargetType::SCALAR,
            'profile.dietary_preferences' => BindingTargetType::COLLECTION,
            // ...
        ],
        // ...
    ],
];
```

`BindingTargetType` (PHP backed enum) has three cases:

| Case | Semantics | Example |
|---|---|---|
| `SCALAR` | Single value; `merge_strategy` choice meaningful for conflict resolution | `person.email`, `user.first_name` |
| `COLLECTION` | Set of values with deduplication; `append` becomes idempotent | `person.tags`, `user.profile.languages` |
| `RELATION` | Foreign-key reference; `merge_strategy` of `overwrite` is the only sane choice | `person.crowd_type_id` |

**Convention-not-contract is forbidden.** The registry is queried explicitly. Name-suffix matching (e.g. attributes ending in `_tags` are collection) was rejected per RFC-WS-6 §4 V1 because it would silently misclassify edge cases (`user_tags_count` would falsely qualify).

### 3.2 `config/form_builder/purposes.php`

Each purpose entry has a `guards_class` key alongside the existing `subject_type`, `requiredBindings`, `submission_mode`, and `public_token_supported`:

```php
'event_registration' => [
    'subject_type' => 'person',
    'submission_mode' => SubmissionMode::DRAFT_SINGLE,
    'public_token_supported' => true,
    'requiredBindings' => [
        ['target_entity' => 'person', 'target_attribute' => 'email', 'is_identity_key' => true],
    ],
    'guards_class' => EventRegistrationGuardProvider::class,
],
```

`PurposeRegistry::guardProviderFor(string $slug): PurposeGuardProvider` instantiates and caches the class. See §9.

### 3.3 `config/form_builder/section_apply.php`

Section-level binding apply is feature-flagged. The config file consists of one boolean and a comment block documenting the removal trigger:

```php
return [
    /*
     * Section-level binding apply is gated until ARTIST_ADVANCE feature
     * work begins (post-S5).
     *
     * To enable:
     * 1. Set 'enabled' => true (or via FORM_BUILDER_SECTION_APPLY env var)
     * 2. Activate ApplyBindingsOnFormSectionSubmitted listener registration
     *    in EventServiceProvider
     * 3. Write section-scoped tests against FormBindingApplicator::apply($s, sectionId: $id)
     * 4. Remove the early-return guard from the listener
     * 5. Remove this entire feature-flag config — section-level apply
     *    becomes the default for purposes with section_level_submit=true.
     *
     * Tracking: BACKLOG.md → ARTIST-ADV-SECTION-APPLY
     */
    'enabled' => env('FORM_BUILDER_SECTION_APPLY', false),
];
```

### 3.4 Adding a new target attribute

To extend the registry with a new bindable attribute (e.g. `person.country_code`):

1. Add the entry under `targets.person.country_code` in `config/form_builder/bindings.php` with the correct `BindingTargetType`
2. Add a fixture row in `database/factories/FormFieldBindingFactory.php` if test coverage uses the new attribute
3. Add a single positive test asserting `BindingTypeRegistry::resolve('person', 'country_code')->equals(BindingTargetType::SCALAR)` (or whichever)
4. **Optional:** add a `PublishGuard` if the new attribute imposes constraints on schema authors (e.g. `RequiresFieldType('text', minCount: 1)` for a country-code field that must appear in the schema)

No migration is needed — the registry is config, and the `form_field_bindings` table already has the columns.

---

## 4. Merge strategies & target-type contract

### 4.1 The four strategies

`MergeStrategy` (PHP backed enum):

| Strategy | Semantics |
|---|---|
| `overwrite` | Winner value (after trust precedence) replaces the target attribute unconditionally |
| `append` | Winner value is added to the target collection; duplicates deduplicated by collection semantics. **Restricted to `BindingTargetType::COLLECTION` per V1.** |
| `replace` | Winner value replaces the target only if the target is currently null. Non-null targets are preserved. |
| `first_write_wins` | Winner value writes only if the target is null AND the winner value is non-null. |

### 4.2 Strategy × target-type validity matrix

|  | SCALAR | COLLECTION | RELATION |
|---|---|---|---|
| `overwrite` | ✅ valid | ⚠ valid but unusual (overwrites entire collection) | ✅ valid |
| `append` | ❌ rejected at publish-time | ✅ valid (idempotent on retry) | ❌ rejected at publish-time |
| `replace` | ✅ valid | ✅ valid (only writes if collection is null/empty) | ✅ valid |
| `first_write_wins` | ✅ valid | ✅ valid | ✅ valid |

The `AppendStrategyRequiresCollectionTarget` PublishGuard (§8) enforces the two ❌ cells at publish time. Runtime apply assumes publish has succeeded.

### 4.3 Null-winner matrix (Q7 conflict resolution)

After trust precedence, the winning binding may have a null value. Behaviour per strategy:

| `merge_strategy` | Winner value = null | Behaviour |
|---|---|---|
| `overwrite` | null | Writes null to target — explicit clear |
| `append` | null | No-op — nothing to append, target unchanged |
| `replace` | null | No-op when target is non-null; no-op when target is null (no value to write) |
| `first_write_wins` | null | Writes null when target is null (claims the slot); skipped when target has any value |

The candidate-set definition that supports this matrix lives in §17. The short version: a `form_values` row with `value=null` is an explicit clear by the user (multi-step edit-resubmit), distinct from absence of a row (skipped by conditional logic).

### 4.4 Why `append` is collection-only

Appending to scalars (string concatenation, comma-separated lists) requires a fingerprint mechanism to detect duplicate-append on retry. Embedding fingerprints in domain data is an architectural smell. Collection types with set semantics (deduplicated JSON arrays, pivot relations) make retry naturally idempotent. Restricting `append` to collections eliminates the entire problem class.

If a use-case ever surfaces for "append a string segment to a text field", model it as a collection with later projection to a single string at read-time, not as an `append` on a scalar.

---

## 5. Listener chain — sync, queued, ordering

### 5.1 Registration

`EventServiceProvider::$listen` is the single source of truth for listener registration. One synchronous listener fires on `FormSubmissionSubmitted`; all others are queued and run in parallel:

```php
protected $listen = [
    FormSubmissionSubmitted::class => [
        // SYNC — only ApplyBindings, because subject_id must be on the
        // submission before the HTTP response serializes
        ApplyBindingsOnFormSubmit::class,
        // QUEUED — order does not matter; all gated on apply_status=COMPLETED
        TriggerPersonIdentityMatchOnFormSubmit::class,
        SyncTagPickerSelectionsOnSubmit::class,
        CreateProvisionalShiftAssignmentsFromRegistration::class,
        AddPersonToApplicableCrowdListsOnRegistration::class,
        FormWebhookDispatcher::class,
        // Plus purpose-specific mailables (RegistrationConfirmation etc.)
    ],
];
```

The single SYNC listener does not implement `ShouldQueue`. All others do. Laravel's listener-array order is the ordering primitive; no `Subscriber` pattern, no `$priority` flag.

> **v1.0 → v1.1:** v1.0 had two synchronous listeners (`ApplyBindingsOnFormSubmit` →
> `TriggerPersonIdentityMatchOnFormSubmit`). RFC-WS-6 v1.3 (2026-05-07 review) reduced
> the SYNC chain to one: identity-match joins against `persons` scoped to organisation
> and runs in seconds at scale; blocking PHP-FPM workers on it during peak public
> registration is operationally unacceptable. See §5.6 for the gating invariant that
> queued listeners must include.

### 5.2 Listener catalogue

| Listener | Sync/Queued | Trigger condition | What it does | Failure mode |
|---|---|---|---|---|
| `ApplyBindingsOnFormSubmit` | sync | Any submission | Provisions or resolves subject; applies all bindings; writes `apply_status`; writes initial `identity_match_status='pending'` for `subject_type='person'`. Runs inside a 5s deadline wrapper — exceeded deadline throws `FormBindingApplicatorTimeoutException` routed via outer transaction. | Catches strict `FormBindingApplicator` throws, writes `form_submission_action_failures` row in outer transaction (with `failure_response_code` mirrored onto `form_submissions`), swallows |
| `TriggerPersonIdentityMatchOnFormSubmit` | queued | Gated on `apply_status=COMPLETED` (per §5.6); `subject_type='person'`. Throws `IdentityMatchInvariantViolation` if `subject_id IS NULL` despite COMPLETED state — that condition is a structural defect, not a failsafe (RFC-WS-6 §Q2 v1.3). | Calls `PersonIdentityService::detectMatches($person)`, writes final `identity_match_status` + `identity_match_count`, broadcasts `FormSubmissionIdentityMatchResolved` on the `submission.{id}` private channel | Throw routed via Laravel queue worker → GlitchTip + `form_submission_action_failures` row; does not block siblings |
| `SyncTagPickerSelectionsOnSubmit` | queued | Gated on `apply_status=COMPLETED` (per §5.6); `purpose='event_registration'` AND TAG_PICKER values present | Rebuilds `user_organisation_tags` (source=self_reported) for the linked Person | Logs at error, swallows; idempotent on retry |
| `CreateProvisionalShiftAssignmentsFromRegistration` | queued | Gated on `apply_status=COMPLETED` (per §5.6); `purpose='event_registration'` AND AVAILABILITY_PICKER values present | Creates `claim_pending` ShiftAssignments for matching shifts | Logs at error, swallows |
| `AddPersonToApplicableCrowdListsOnRegistration` | queued | Gated on `apply_status=COMPLETED` (per §5.6); `purpose='event_registration'` AND new Person created | Adds Person to crowd_lists matching auto_add_criteria | Logs at error, swallows |
| `FormWebhookDispatcher` | queued | Gated on `apply_status=COMPLETED` (per §5.6); any submission with active `form_schema_webhooks` | Dispatches `DeliverFormWebhookJob` per active webhook | Per-webhook job has its own retry chain (§17.5 in ARCH-FORM-BUILDER) |
| `RegistrationConfirmation` (and siblings) | queued | Gated on `apply_status=COMPLETED` (per §5.6); per-purpose mailable trigger conditions | Sends purpose-specific email to submitter | Failed sends logged via existing CrewliMailable infrastructure |

### 5.3 Why SYNC for ApplyBindings only

`ApplyBindingsOnFormSubmit` is synchronous because `subject_id` must be on the submission before the HTTP response serializes — the submission resource needs a non-null `subject` reference, and the frontend immediately routes on the resolved Person. Provisioning is the only operation that must complete before the response leaves `FormSubmissionService::submit()`.

The portal IdentityMatchBanner reads `identity_match_status` from the resource payload. To keep first-paint copy correct ("we're checking matches…"), `ApplyBindingsOnFormSubmit::handle` writes `identity_match_status='pending'` inside the inner transaction, immediately after subject resolution. This satisfies the `FormSubmissionResource` S3a contract for the `identity_match` block. The final state (`matched` / `no_match` / `multiple_candidates`) is written by the queued `TriggerPersonIdentityMatchOnFormSubmit`, and propagated to the portal via an Echo broadcast on the `submission.{id}` private channel; until the frontend follow-up subscribes to that channel, TanStack Query refetch-on-window-focus is the interim path.

#### Sync-chain hard timeout

`ApplyBindingsOnFormSubmit` runs inside a 5-second deadline wrapper (`$applicator->withDeadline(seconds: 5)`). The deadline is configurable via `config('form_builder.apply_deadline_seconds')` with default 5. On exceeded deadline, the wrapper throws `FormBindingApplicatorTimeoutException`, caught by the outer transaction handler and written as a `form_submission_action_failures` row with `apply_status='failed'`. This guarantees no submission can hang the public flow for more than a bounded interval — slow paths surface as failures, not as hung connections.

> **v1.0 → v1.1:** v1.0 had two SYNC listeners with rationale "ordering primitive +
> response carries identity-match state." RFC-WS-6 v1.3 reduced SYNC to one
> (ApplyBindings) and added the deadline wrapper. The "response carries
> identity-match state" requirement is satisfied by writing `pending` inside the
> inner transaction; the final state lands asynchronously via Echo broadcast.

### 5.4 Why `SyncTagPickerSelectionsOnSubmit` is not folded into ApplyBindings

TAG_PICKER → `user_organisation_tags` is semantically different from a binding-target-attribute write. Tag sync rebuilds a pivot table with source-discrimination (`source=self_reported` is rebuildable; `source=organiser_assigned` is preserved). Bindings write attribute mutations. Conflating them would introduce a special-case path inside `FormBindingApplicator::applyAll` that handles "this isn't really a target attribute, it's a tag-pivot rebuild" — exactly the kind of branch that turns simple code into legacy code over time.

The two are deliberate parallel paths. Future contributors should not consolidate them. See ARCH-FORM-BUILDER §31.10 for the tag-sync listener contract.

### 5.5 Listener ordering test

`tests/Feature/FormBuilder/EventServiceProviderListenerOrderTest.php` asserts that:

1. `ApplyBindingsOnFormSubmit` is registered as the first listener for `FormSubmissionSubmitted` and does NOT implement `ShouldQueue`
2. `TriggerPersonIdentityMatchOnFormSubmit` is registered AFTER `ApplyBindingsOnFormSubmit` AND implements `ShouldQueue`
3. `SyncTagPickerSelectionsOnSubmit`, `CreateProvisionalShiftAssignmentsFromRegistration`, `AddPersonToApplicableCrowdListsOnRegistration`, `FormWebhookDispatcher` all implement `ShouldQueue`
4. Every `ShouldQueue` listener for this event includes the §5.6 gating invariant as the first executable statement of `handle()` — verified via `ReflectionMethod` introspection of the AST first node, asserting it is the canonical early-return on `apply_status !== ApplyStatus::COMPLETED`

This is a structural test — if a future change reorders listeners, queues a previously sync listener wrong, or omits the gating invariant on a new queued listener, the test fails before any behaviour test would.

### 5.6 Queued-listener gating invariant

Every queued listener for `FormSubmissionSubmitted` begins with this gate as the first executable statement of `handle()`:

```php
if ($event->submission->fresh()->apply_status !== ApplyStatus::COMPLETED) {
    Log::info('form-builder.queued-listener.skipped_apply_failed', [
        'listener' => static::class,
        'submission_id' => $event->submission->id,
    ]);
    return;
}
```

**This is a hard invariant**, not a recommendation. ApplyBindings runs synchronously before any queued listener; if its inner transaction throws, the outer-transaction failure-record path leaves the submission with `apply_status=failed` and `subject_id=null`. Without this gate, queued listeners would still trigger and assume a valid Person exists — leading to cascading failures whose root cause is hard to trace.

The gate is enforced by the §5.5 listener-ordering test: a contributor adding a queued listener without the gate sees a structural test failure before code review. Adding a queued listener that *intentionally* needs to run on FAILED submissions is a structural-defect signal — that listener belongs on a different event (or its trigger condition belongs in the gate's positive branch, not as an exception to the gate).

The gate uses `fresh()` rather than the in-memory event submission because the inner-transaction commit + outer-transaction failure-record write happens between event dispatch and queued-listener execution. The DB has the canonical `apply_status` value; the in-memory model does not.

#### PARTIAL handling

`apply_status=partial` means the inner transaction committed but at least one binding in the pass failed (per `BindingPassResult::applyStatus()`). The gate skips PARTIAL submissions identically to FAILED submissions: queued listeners cannot safely assume the subject + bindings are coherent. For example, `SyncTagPickerSelectionsOnSubmit` rebuilds `user_organisation_tags` against a Person whose tag-binding may have been the binding that failed; running the listener would propagate the partial state into derived data.

Until BACKLOG `PARTIAL-BINDING-SUCCESS` lands, the gate's positive branch is restricted to `COMPLETED` only. The PARTIAL row stays visible in the failures UI through the per-binding failure rows that `FormBindingApplicator` writes inside `BindingPassResult::failures()`, so admins can triage without losing audit data.

If a future contributor extends the gate to accept PARTIAL, the structural test asserting "skip on every non-COMPLETED state" must be updated alongside the listener changes — never one without the other.

---

## 6. Atomicity — two-transaction failure-write pattern

### 6.1 The pattern

```php
// Inside ApplyBindingsOnFormSubmit::handle($event)
$submission = $event->submission;

try {
    DB::transaction(function () use ($submission) {
        $subject = $this->purposeDef
            ->resolveOrProvisionSubject($submission, $this->personProvisioner);

        $resolved = $this->applicator->resolveBindings($submission);
        $this->applicator->applyAll($subject, $resolved);

        $submission->update(['apply_status' => ApplyStatus::COMPLETED->value]);

        // identity-match status update, NOT the matching itself
        // (PersonIdentityService runs in the next sync listener)
        $this->markIdentityMatchPending($submission);
    });
} catch (\Throwable $e) {
    DB::transaction(function () use ($submission, $e) {
        FormSubmissionActionFailure::create([
            'form_submission_id' => $submission->id,
            'listener_class'     => self::class,
            'failed_at'          => now(),
            'exception_class'    => $e::class,
            'exception_message'  => $e->getMessage(),
            'context'            => [
                'apply_phase' => $this->applicator->lastPhase() ?? 'unknown',
                'subject_type' => $submission->subject_type,
                'subject_id'   => $submission->subject_id,
            ],
        ]);

        FormSubmission::query()
            ->whereKey($submission->id)
            ->update(['apply_status' => ApplyStatus::FAILED->value]);
    });

    Log::error('form-builder.apply.transaction_rolled_back', [
        'submission_id' => $submission->id,
        'exception_class' => $e::class,
    ]);
}
```

### 6.2 Why two transactions

The inner transaction wraps subject provisioning, binding application, and status writes. If anything inside throws, the rollback is total — no half-applied state. But that rollback also discards any failure-record we might have tried to write.

The outer transaction is independent. It writes `form_submission_action_failures` plus the `apply_status=failed` update on the submission, in a small two-statement transaction that can succeed even when the inner transaction has rolled back the entire binding-apply attempt.

If the outer transaction itself fails (database connection lost between inner rollback and outer commit), GlitchTip captures the `Throwable` from the inner-`Log::error` call and the failure becomes invisible to the admin UI — but still captured in error tracking. This is a degenerate case; the system does not pretend to handle infrastructure-level failures gracefully beyond logging.

> **v1.0 → v1.1 — deadline wrapper.** The inner transaction runs inside a 5-second
> deadline wrapper (`$applicator->withDeadline(seconds: 5)`, configurable via
> `config('form_builder.apply_deadline_seconds')`). On exceeded deadline the wrapper
> throws `FormBindingApplicatorTimeoutException`, which is caught by the outer
> transaction handler exactly like any other applicator throw. The failure-record
> row carries `exception_class=FormBindingApplicatorTimeoutException` and
> `apply_status='failed'` — the public flow never hangs longer than the deadline
> bound. See §5.3 for the rationale; RFC-WS-6 §Q1 v1.3 addition 4 for the source
> decision.

> **v1.0 → v1.1 — `failure_response_code` mirror.** Per RFC-WS-6 §Q3 v1.3 addition 2,
> the outer-transaction failure path also writes `failure_response_code` onto the
> `form_submissions` row (`schema_config_error` / `temporary_error` /
> `data_integrity_error` / `unknown_error`), driven by which subclass of
> `FormBindingApplicatorException` was thrown. The controller serializes this into
> the API response body when `apply_status=failed`; frontend renders contextual
> copy keyed on `error_code`.

### 6.3 Event-firing timing

`FormSubmissionSubmitted` fires **after** the `FormSubmissionService::submit()` transaction commits, not from inside the transaction:

```php
// Inside FormSubmissionService::submit()
$submission = DB::transaction(function () use ($payload) {
    // ... build submission, write form_values, snapshot schema, etc.
    return $submission;
});

event(new FormSubmissionSubmitted($submission->refresh()));
```

This is non-negotiable. Eloquent observers that fire events from inside a transaction have a known race: queued listeners enqueue with state that may never commit. By dispatching the event explicitly after `DB::transaction()` returns, all listeners see committed state.

Do not move event firing into a model observer. Do not use `DB::afterCommit()` — explicit ordering inside `FormSubmissionService` is clearer and unambiguous.

### 6.4 Person provisioning races

`PersonProvisioner::provisionByEmailBinding` uses `Person::firstOrCreate()` with `lockForUpdate()` semantics on the email lookup. The MySQL InnoDB driver guarantees a serializable-equivalent read for `SELECT ... FOR UPDATE` inside a transaction. Two concurrent submissions with the same email resolve to the same Person, with the first to commit creating the row and the second seeing it on its lookup.

A unique index on `(organisation_id, email)` on the `persons` table backs the guarantee — if both transactions reach the insert path simultaneously (rare under `FOR UPDATE`), the second fails with a duplicate-key error which `firstOrCreate` catches and retries with the now-existing row.

### 6.5 Outer transaction failure-mode

If the outer (failure-record) transaction throws, the `Log::error` call still fires before the listener swallows the exception. The submission ends with `apply_status=null` (the original value) which is misleading — the apply did fail, the record just didn't land. GlitchTip captures the `Throwable`. This is acceptable because:

- The outer transaction is two statements (one INSERT, one UPDATE). Failure is rare.
- The `Log::error` line is filterable in GlitchTip with `form-builder.apply.transaction_rolled_back` as the message tag.
- ARCH-OBSERVABILITY.md (§ TBD) defines an alert on this log line at threshold "more than 5 in 24h", which is conservative enough to not page-flap but tight enough to surface infrastructure issues.

---

## 7. Status columns — apply_status and identity_match_status

### 7.1 Two independent concerns

`form_submissions` carries two status columns, one failure-classification column, and one apply-finalisation timestamp that the pipeline manages:

| Column | Type | Default | Indexed | Managed by |
|---|---|---|---|---|
| `apply_status` | string(20) nullable | NULL | yes | `ApplyBindingsOnFormSubmit` (sync), retry/resolve flows |
| `identity_match_status` | string(20) nullable | NULL | yes | `ApplyBindingsOnFormSubmit` writes initial `'pending'` for `subject_type='person'`; `TriggerPersonIdentityMatchOnFormSubmit` (queued) writes final state; `PersonIdentityService::confirmMatch` (manual) |
| `failure_response_code` | string(40) nullable | NULL | yes | `ApplyBindingsOnFormSubmit` outer-transaction failure path. Values: `schema_config_error`, `temporary_error`, `data_integrity_error`, `unknown_error` (per RFC-WS-6 §Q3 v1.3 addition 2). Serialized into API response body when `apply_status=failed` so the frontend can render contextual copy. |
| `apply_completed_at` | timestamp nullable | NULL | no | `ApplyBindingsOnFormSubmit::handle` (writes `now()` in both the inner-transaction success path AND the outer-transaction failure path, paired with the corresponding `apply_status` write) and `FormFailureRetryService::retry` (success path). Set whenever `apply_status` transitions to a terminal state (COMPLETED, PARTIAL, or FAILED). NULL means apply has never run on this submission. Used by the failures UI to render "Failed at …" / "Completed at …" copy without joining to `form_submission_action_failures`. |

They are **independent**. A submission can be `apply_status=completed` AND `identity_match_status=pending` — the bindings landed, but the organizer hasn't confirmed which existing Person this submission's just-provisioned Person should link to. Both states must be visible in the UI as separate signals, not collapsed into a single "submission status" indicator. `failure_response_code` is null on success and populated only on `apply_status=failed`.

`FormFailureRetryService::recordFailure` does NOT currently write `apply_completed_at` on the retry-failure path; this asymmetry is fixed as part of the v1.3-delta D2 work (RFC v1.3 §Q3 addition 2 implementation).

### 7.2 `ApplyStatus` enum

```php
enum ApplyStatus: string
{
    case PENDING = 'pending';
    case COMPLETED = 'completed';
    case PARTIAL = 'partial';
    case FAILED = 'failed';
}
```

`PARTIAL` is not a separate runtime path through `ApplyBindingsOnFormSubmit::handle` — it is the value `BindingPassResult::applyStatus()` returns when the pass committed but at least one individual binding failed (mixed per-binding outcomes inside a single applicator pass). Per RFC-WS-6 §Q3 v1.3 addition 3, granular partial-success handling is BACKLOG `PARTIAL-BINDING-SUCCESS`. Until that work lands, `PARTIAL` is treated identically to `FAILED` by the queued-listener gate (see §5.6).

The column itself defaults to `NULL` rather than `'pending'`. This is deliberate: NULL means **this schema has no bindings to apply** (e.g., a `feedback` submission with no entity-bound fields). Using `pending` as the default would force every unrelated submission into a pipeline-state it has no business in.

State transitions:

```
NULL ──(submission of binding-bearing schema)──▶ pending
pending ──(apply succeeds, all bindings)──▶ completed
pending ──(apply commits, mixed per-binding outcomes)──▶ partial
pending ──(apply throws / deadline exceeded)──▶ failed
failed ──(retry succeeds)──▶ completed
failed ──(retry throws)──▶ failed (action_failure row gets new attempts entry)
```

`pending` is a transient state during the inner transaction; if the response serializes the submission resource with `apply_status=pending`, something is wrong (the inner transaction should have completed before the response leaves `FormSubmissionService::submit`). A monitoring rule (ARCH-OBSERVABILITY) flags submissions stuck in `pending` for more than 60 seconds.

### 7.3 `identity_match_status`

This column predates WS-6 and is documented in ARCH-FORM-BUILDER §31.1. Pipeline-relevant points:

- `ApplyBindingsOnFormSubmit` writes the initial `'pending'` state inside the inner transaction immediately after subject resolution, for any submission with `subject_type='person'`. This satisfies the `FormSubmissionResource` S3a contract — the HTTP response carries `'pending'`, never `null`, for person-typed submissions.
- `TriggerPersonIdentityMatchOnFormSubmit` (queued, gated on `apply_status=COMPLETED` per §5.6) writes the final state (`matched` / `no_match` / `multiple_candidates`) plus `identity_match_count`, then broadcasts `FormSubmissionIdentityMatchResolved` on the `submission.{id}` private channel.
- For non-person purposes (`signature_contract`, `user_profile`, `incident_report`, `post_event_evaluation`, `supplier_intake`, `artist_advance`), the column stays NULL. `FormSubmissionResource.identity_match` is `null` for these — RFC-WS-6 §Q2 v1.3 makes this contract explicit, with a contract test in `tests/Feature/Api/FormSubmissionResourceTest`.

#### Invariant (RFC-WS-6 §Q2 v1.3)

> Post `ApplyBindingsOnFormSubmit::handle` for `event_registration` purpose:
> `subject_type='person'` AND `subject_id IS NOT NULL`, OR
> `apply_status=ApplyStatus::FAILED`.
> No third state exists. Violation is a structural defect.

`TriggerPersonIdentityMatchOnFormSubmit` enforces the invariant via a strict throw — `IdentityMatchInvariantViolation` — when it observes `subject_type='person'` AND `subject_id IS NULL` AND `apply_status=COMPLETED`. The throw routes through Laravel's queue-worker exception handler to GlitchTip and writes a `form_submission_action_failures` row, exactly like any other applicator failure. There is no "no subject → pending" failsafe path. The `RequiresIdentityKeyBinding('person', 'email')` publish guard wires unconditionally for `event_registration` (see §8.5), preventing the only schema configuration that could have produced this state from ever reaching publish.

### 7.4 UI surface

The platform admin "Form failures" page (`/platform/form-failures`) and organisation admin equivalent (`/orgs/{org}/form-failures`) filter by `apply_status=failed`.

The submission-detail review UI (organizer side) shows both columns as separate badges. PR-FORM-BUILDER-UI defines the badge styling.

---

## 8. Pre-publish validation — PublishGuard framework

### 8.1 Why pre-publish, not runtime

Most binding-pipeline failures are configuration errors: the schema author wrote a binding to `person.shoe_size` (typo for `t_shirt_size`), set `merge_strategy=append` on a SCALAR target, or built a section-aware schema with an `is_identity_key` binding outside section 1. These errors are caught at publish-time by the PublishGuard framework rather than at submit-time.

Publish-time guards have three advantages over runtime errors:

1. The schema author sees the error immediately, not days later when the first submission lands
2. The error message can be specific and actionable ("Field 'Schoenmaat' has merge_strategy=append but person.shoe_size is SCALAR. Use overwrite or first_write_wins.")
3. Production submissions never see the error class — apply-time exceptions are reserved for "DB modified out from under us" rare cases

### 8.2 The interface

```php
interface PublishGuard
{
    public function check(FormSchema $schema): PublishGuardResult;
}

final readonly class PublishGuardResult
{
    public function __construct(
        public bool $passed,
        /** @var list<PublishGuardViolation> */
        public array $violations = [],
    ) {}

    public static function passed(): self
    {
        return new self(true);
    }

    public static function failed(string $message, ?string $fieldSlug = null, array $context = []): self
    {
        return new self(false, [new PublishGuardViolation($message, $fieldSlug, $context)]);
    }
}

final readonly class PublishGuardViolation
{
    public function __construct(
        public string $message,
        public ?string $fieldSlug = null,
        public array $context = [],
    ) {}
}
```

Returning a typed object (not a bool) lets the framework collect multiple violations from a single guard. A `MaxOneIdentityKeyPerTargetEntity` check can return three violations in one `PublishGuardResult` if the schema has three offending fields.

### 8.3 The collection contract

`FormSchemaService::publish(FormSchema $schema)`:

```php
public function publish(FormSchema $schema): void
{
    $provider = $this->purposeRegistry->guardProviderFor($schema->purpose);
    $guards = $provider->publishGuards();

    /** @var list<PublishGuardViolation> $violations */
    $violations = [];
    foreach ($guards as $guard) {
        $result = $guard->check($schema);
        if (! $result->passed) {
            array_push($violations, ...$result->violations);
        }
    }

    if (count($violations) > 0) {
        throw new PublishGuardViolationException($violations);
    }

    // ... continue with publish (existing logic)
}
```

The framework collects **all** violations before throwing. First-fail would be hostile: a schema with five publish-blocking issues should surface all five in one round-trip, not require five publish attempts.

### 8.4 The four universal guards

These four wire into every `PurposeGuardProvider`, regardless of purpose:

#### `MaxOneIdentityKeyPerTargetEntity`
At most one binding per `(target_entity)` may have `is_identity_key=true`. Multiple identity keys on the same entity create ambiguity in `PersonProvisioner::provisionFromBindings` — which value defines "this is the same entity"?

#### `IdentityKeyBindingsOnlyInFirstSection`
For schemas with `section_level_submit=true`, all `is_identity_key=true` bindings must live on fields in the first section. Otherwise sections 2+ might submit before section 1 has provisioned the entity, causing apply to run with no subject. No-op for non-section schemas.

#### `AppendStrategyRequiresCollectionTarget`
A binding with `merge_strategy=append` must target a `BindingTargetType::COLLECTION` per the `BindingTypeRegistry`. Per V1, append-on-scalar is architecturally rejected.

#### `NoAmbiguousTrustLevels`
Two bindings targeting the same `(target_entity, target_attribute)` must have distinct `trust_level` values — or distinct `form_field.sort_order` values as the documented tie-break. This guard catches "two bindings, both at trust 50, both at sort_order 0" which would resolve in arbitrary order across MySQL versions.

### 8.5 Purpose-specific guards (catalogue)

These wire only into providers where they apply:

| Guard | Wires into | Behaviour |
|---|---|---|
| `RequiresIdentityKeyBinding(entity, attribute)` | `event_registration` (`person`, `email`) — **unconditional, both public and private schemas**; `artist_advance` (`artist`, `id`); etc. | Asserts schema has at least one binding with `target_entity=entity`, `target_attribute=attribute`, `is_identity_key=true` |
| `RequiresFieldType(type, minCount)` | `event_registration` (`AVAILABILITY_PICKER`, 0 or more), `signature_contract` (`SIGNATURE`, 1) | Asserts at least `minCount` fields of the given type exist |
| `SchemaHasLinkedEvent` | `event_registration`, `artist_advance` | Asserts `form_schemas.linked_event_id` is non-null |
| `TagCategoriesConfiguredOnAllPickers` | `event_registration`, `user_profile` | Asserts every TAG_PICKER field has at least one `tag_category` configured |

The `ConditionalRequirement(predicate, subGuard)` higher-order composer wraps a guard with a predicate that only runs the inner guard when the predicate matches the schema. The composer is retained for purposes that genuinely need conditional wiring; it is **not** used for `RequiresIdentityKeyBinding` on `event_registration`:

> **v1.0 → v1.1 — `RequiresIdentityKeyBinding` becomes unconditional for
> `event_registration`.** v1.0 wrapped this guard in
> `ConditionalRequirement(predicate: $s->public_token !== null, …)` — meaning
> private (organizer-driven) event_registration schemas could publish without an
> email-keyed Person identity binding. Post-publish, ApplyBindings would have
> nothing to provision against, and the `TriggerPersonIdentityMatch` failsafe-pad
> would absorb the consequences. RFC-WS-6 §Q2 v1.3 closes this gap: every
> `event_registration` schema requires the binding regardless of visibility, because
> the purpose itself creates or matches a Person — that requirement is intrinsic to
> the purpose, not to the schema's visibility. The failsafe-pad in
> `TriggerPersonIdentityMatch` is removed in the same change (§7.3).

### 8.6 Adding a new guard

1. Add the class under `app/FormBuilder/Publishing/{GuardName}.php` implementing `PublishGuard`
2. Wire it into the appropriate `PurposeGuardProvider::publishGuards()` return (or add it to a universal-guards trait if it applies to all purposes)
3. Write one positive test (passing case) and one negative test (failing case with expected violation message format) under `tests/Unit/FormBuilder/Publishing/`
4. If the guard introduces new error UX, add a copy-catalogue entry under ARCH-FORM-BUILDER §30 with the violation message template

The framework is open-closed: a new guard never modifies `FormSchemaService::publish()`.

---

## 9. Purpose-specific behaviour — PurposeGuardProvider & subject resolution

### 9.1 `PurposeGuardProvider` interface

```php
interface PurposeGuardProvider
{
    /** @return list<PublishGuard> */
    public function publishGuards(): array;
}
```

Each concrete provider returns the guard list for its purpose. The four universal guards are typically composed via a trait or shared base class:

```php
final class EventRegistrationGuardProvider implements PurposeGuardProvider
{
    use HasUniversalPublishGuards;

    public function publishGuards(): array
    {
        return [
            ...$this->universalGuards(),
            new RequiresIdentityKeyBinding('person', 'email'),
            new SchemaHasLinkedEvent(),
            new TagCategoriesConfiguredOnAllPickers(),
            new ConditionalRequirement(
                fn (FormSchema $s) => $s->public_token !== null,
                new RequiresFieldType('email', minCount: 1)
            ),
        ];
    }
}
```

### 9.2 Subject resolution per purpose

`PurposeDefinition::resolveOrProvisionSubject(FormSubmission, PersonProvisioner): ?Model` is the entry point for every purpose-specific resolver. The `?Model` return type acknowledges purposes (incident_report, public_complaint) where anonymous submission is allowed.

Subject resolution table:

| Purpose | Resolver | Behaviour |
|---|---|---|
| `event_registration` | `PersonProvisioner::provisionByEmailBinding` | May create a new Person if no match found by `(organisation_id, email)`. Returns existing Person otherwise. |
| `artist_advance` | `ArtistResolver::fromPortalToken` | Resolves Artist from `form_submissions.portal_token` context. Throws `MissingArtistContextException` if absent. |
| `supplier_intake` | `CompanyResolver::fromProductionRequest` | Resolves Company from the `production_request` row whose token is in the submission context. Throws if production_request absent. |
| `post_event_evaluation` | `PersonResolver::fromAuth` | Resolves Person from authenticated user's linked Person. Throws if user has no linked Person. |
| `incident_report` | `PersonResolver::fromAuthOrNull` | Returns null for anonymous submissions. |
| `signature_contract` | `UserResolver::fromAuth` | Resolves User from auth context. |
| `user_profile` | `UserResolver::fromAuth` | Same as signature_contract. |

### 9.3 Adding a new purpose

1. Add the slug-keyed entry to `config/form_builder/purposes.php` with `subject_type`, `submission_mode`, `public_token_supported`, `requiredBindings`, `guards_class`
2. If the new purpose has a new `subject_type` not already present, register the FQCN in `AppServiceProvider::PURPOSE_SUBJECT_FQCN`. `MorphMapAlignmentTest` enforces this step.
3. Add the new `PurposeGuardProvider` class under `app/FormBuilder/Purposes/Guards/`
4. Add the new resolver class under `app/FormBuilder/Purposes/Resolvers/` if reuse of existing resolvers is not possible
5. Wire any purpose-specific listeners in `EventServiceProvider::$listen` (identity-match, tag sync, mailables, etc.)
6. Add a lifecycle paragraph to ARCH-FORM-BUILDER §3.2 and a row to the purpose catalogue table in §3.1
7. Add at least 4 pipeline tests (happy-path, missing required binding, conflict-resolution, anonymous-when-applicable) under `tests/Feature/FormBuilder/Pipeline/Purposes/`

### 9.4 Open-closed property

Adding a purpose modifies:

- `config/form_builder/purposes.php` (one new array entry)
- New PurposeGuardProvider class
- Optionally new resolver class
- Optionally new listeners
- Documentation

It does **not** modify:

- `FormSchemaService::publish()` — generic, walks the guard list
- `FormBindingApplicator::apply()` — purpose-agnostic, delegates to PurposeDefinition
- Existing `PurposeGuardProvider` classes
- Existing resolvers

This is the open-closed contract that the framework enforces. Reviewers should reject any PR that adds a purpose by branching inside `publish()` or `apply()` instead of adding a new provider.

---

## 10. Section-level apply — stub structure, feature flag, removal trigger

### 10.1 Why stubbed

Section-level submit is a feature primarily relevant for `artist_advance` and `supplier_intake` schemas with `section_level_submit=true`. These purposes let the submitter complete and submit one section at a time over weeks (typical for artist advancing), with each section-submit triggering its own pipeline pass.

Building section-aware apply is straightforward (the `FormBindingApplicator::apply()` method already accepts an optional `sectionId` parameter). However, the queued listener that consumes `FormSubmissionSectionSubmitted` events is gated until artist-advance feature work begins post-S5. Building it now and gating it costs little; activating it without artist-advance UX support would expose a half-built workflow.

### 10.2 The listener

```php
class ApplyBindingsOnFormSectionSubmitted implements ShouldQueue
{
    public function __construct(
        private FormBindingApplicator $applicator,
    ) {}

    public function handle(FormSubmissionSectionSubmitted $event): void
    {
        if (! config('form_builder.section_apply.enabled', false)) {
            return;
        }
        $this->applicator->apply(
            $event->submission,
            sectionId: $event->sectionId
        );
    }
}
```

The listener is registered in `EventServiceProvider::$listen` from session 2 onward. The early-return guard is the activation gate.

### 10.3 The applicator signature

```php
public function apply(
    FormSubmission $submission,
    ?string $sectionId = null,
): BindingApplicationResult
```

Null `sectionId` (default) applies all bindings whose source `form_field.section_id` is null OR matches the schema. Set `sectionId` filters bindings to only those whose source `form_field.section_id` equals the parameter.

### 10.4 Publish guards land regardless of feature flag

The `IdentityKeyBindingsOnlyInFirstSection` universal guard runs for every schema with `section_level_submit=true`, even with the feature flag disabled. A schema is structurally unsafe regardless of whether the runtime is gated; publish must reject it.

### 10.5 Removal trigger

`config/form_builder/section_apply.php` documents the removal trigger inline (see §3.3 above). When artist-advance feature work begins:

1. Set `'enabled' => true`
2. Write section-scoped tests against `FormBindingApplicator::apply($s, sectionId: $id)`
3. Remove the early-return guard from the listener
4. Remove the entire feature-flag config — section-level apply becomes the default for purposes with `section_level_submit=true`

BACKLOG item: `ARTIST-ADV-SECTION-APPLY`.

### 10.6 Wiring test

`tests/Feature/FormBuilder/Pipeline/SectionLevelApplyStubTest.php` asserts:

1. `ApplyBindingsOnFormSectionSubmitted` is registered as a `FormSubmissionSectionSubmitted` listener
2. With the feature flag disabled, dispatching the event does not invoke `FormBindingApplicator::apply()`
3. With the feature flag enabled (test-only override), dispatching the event invokes `apply()` with the correct `sectionId`

No business-logic test — those land when the flag goes live.

---

## 11. Failure management — `form_submission_action_failures` lifecycle

### 11.1 Table shape

See SCHEMA.md §3.5.12 for the canonical column list. Pipeline-relevant columns:

| Column | Type | Notes |
|---|---|---|
| `id` | ULID | PK |
| `form_submission_id` | ULID FK | → `form_submissions`, cascade delete |
| `listener_class` | string | The listener that caught the throw, e.g. `ApplyBindingsOnFormSubmit` |
| `failed_at` | timestamp | When the inner transaction rolled back |
| `exception_class` | string | FQCN of the throw |
| `exception_message` | text | Pruned to ~2000 chars |
| `context` | JSON | `apply_phase`, `subject_type`, `subject_id`, etc. |
| `apply_status` | string(20) | Mirrors the submission's status at failure time. `pending` while a retry is in flight; `failed` after exhaustion. |
| `resolved_at` | timestamp nullable | Set by Resolve action |
| `resolved_by_user_id` | ULID FK nullable | → `users` |
| `resolved_note` | text nullable | Free-text, optional |
| `dismissed_at` | timestamp nullable | Set by Dismiss action |
| `dismissed_by_user_id` | ULID FK nullable | → `users` |
| `dismissed_reason` | string(40) nullable | `DismissalReasonType` enum value |
| `dismissed_reason_note` | text nullable | Required only when `dismissed_reason='other'` |

No `organisation_id` column. Tenant scope flows via `form_submission_id → form_submissions.organisation_id`. Enforced by `FormSubmissionActionFailurePolicy` (§13).

> **v1.0 → v1.1 — `failure_response_code` companion column on `form_submissions`.**
> Per RFC-WS-6 §Q3 v1.3 addition 2, when ApplyBindings catches a
> `FormBindingApplicatorException` subclass, the outer-transaction handler also
> mirrors a classification onto `form_submissions.failure_response_code`
> (`schema_config_error` / `temporary_error` / `data_integrity_error` /
> `unknown_error`). The action-failures row is the machine-replayable workflow
> artefact; the `form_submissions.failure_response_code` field is the response-shape
> driver — read by the controller to render contextual user-facing copy when the
> submission is queried with `apply_status=failed`. Both rows reference the same
> `submission.id` ULID. See §7.1 for the column listing on `form_submissions`.

### 11.2 Lifecycle

```
                  ┌──────────────────────────────┐
                  │  ApplyBindingsOnFormSubmit   │
                  │  catches throw, writes row   │
                  └──────────────┬───────────────┘
                                 │
                                 ▼
                       ┌──────────────────┐
                       │  state = failed   │
                       └──────────────────┘
                          │      │      │
              ┌───────────┘      │      └────────────┐
              ▼                  ▼                   ▼
     ┌────────────────┐ ┌────────────────┐  ┌────────────────┐
     │   resolved     │ │   dismissed    │  │    retried     │
     │ (manual fix)   │ │ (DismissalType │  │  (re-run apply │
     │ resolved_at +  │ │  + note if     │  │  with snapshot)│
     │ resolved_note  │ │  'other')      │  └───────┬────────┘
     └────────────────┘ └────────────────┘          │
                                                    ▼
                                          ┌──────────────────┐
                                          │  retry succeeded │
                                          │      OR          │
                                          │   retry failed   │
                                          │  (state cycles)  │
                                          └──────────────────┘
```

`resolved` and `dismissed` are terminal states. `retried` is transient — the row exits to either `resolved` (apply succeeded) or back to `failed` (apply threw again, with new `exception_class`/`exception_message` updates and incremented internal attempts counter).

### 11.3 `DismissalReasonType` enum

```php
enum DismissalReasonType: string
{
    case SCHEMA_DELETED = 'schema_deleted';
    case TARGET_ENTITY_DELETED = 'target_entity_deleted';
    case BINDING_REMOVED = 'binding_removed';
    case DUPLICATE_SUBMISSION = 'duplicate_submission';
    case DATA_QUALITY_ISSUE = 'data_quality_issue';
    case OTHER = 'other';
}
```

Six cases. Per RFC-WS-6 §4 V2, `OTHER` is the only case that requires `dismissed_reason_note`. The other five are self-explanatory categories that drive aggregate reporting (e.g., "60% of dismissals are `duplicate_submission` — let's investigate the duplicate-detection code").

### 11.4 `resolved_note` vs `dismissed_reason_note`

- `resolved_note`: free-text, **always optional**. The user fixed the underlying issue (renamed the binding's target attribute, restored the deleted target entity, fixed bad data) and Resolve closes the failure-record without retry. The note is for future reference if the same class of failure recurs.

- `dismissed_reason_note`: free-text, **required only when `dismissed_reason='other'`**. The five other DismissalReasonType cases speak for themselves.

The two are deliberately separate columns so reports can aggregate "% resolved with notes" vs "% dismissed-as-other with notes" cleanly.

### 11.5 No soft delete

The table is append-only at the row level; rows never delete. Resolved and dismissed rows are filtered out of the active failure-management UI but retained for audit. GDPR purge on Person deletion cascades through `form_submission_id` (form_submissions has its own anonymisation flow per ARCH-FORM-BUILDER §31.2).

---

## 12. Retry / Resolve / Dismiss flows

### 12.1 Retry

#### Artisan

```bash
php artisan form-builder:retry-failures {failure-id?} {--dry-run}
```

- Without `failure-id`: walks all `state=failed` rows, dispatches retry per row, reports counts.
- With `failure-id`: retries the single row.
- `--dry-run`: walks but does not dispatch — useful for "how many would retry" counts.

#### HTTP

```
POST /api/v1/orgs/{org}/form-failures/{failure}/retry
POST /api/v1/platform/form-failures/{failure}/retry
```

Both routes use the same controller logic; only the policy gates differ (org-scoped vs platform-wide).

#### Behaviour

```
1. Load the failure row + its parent FormSubmission
2. Acquire SELECT ... FOR UPDATE on the failure row inside a small DB transaction
3. If state != 'failed': abort 409 Conflict with current state
4. Mark state = 'pending' (visible to the UI as "retry in flight")
5. Dispatch ApplyBindingsOnFormSubmit::dispatchSync(new FormSubmissionSubmitted($submission))
6. Catch the same exception classes as the original handler:
   - On success: mark state = 'resolved', set resolved_at/resolved_by_user_id, leave resolved_note null (or copy from request payload if provided)
   - On throw: update exception_class / exception_message, mark state = 'failed' again, increment internal attempts counter (in context JSON for now; no dedicated column unless we observe operational need)
```

Retry uses the submission's frozen `schema_snapshot` for binding configuration, not the live `form_field_bindings`. See §16.

#### Idempotency

Retrying an already-resolved or already-dismissed failure returns 200 with the current state. No-op. Internal attempts counter does not increment.

### 12.2 Resolve

#### HTTP

```
POST /api/v1/orgs/{org}/form-failures/{failure}/resolve
POST /api/v1/platform/form-failures/{failure}/resolve

Request body:
{
  "note": "Renamed the t_shirt_size binding to match the latest schema." // optional
}
```

Marks the failure `resolved` without retry. Used when the operator has manually applied the fix outside the pipeline (e.g., fixed the binding configuration, manually updated the target entity attribute) and the failure-record no longer represents an open issue.

If the operator wants the pipeline to re-apply, they Retry instead.

### 12.3 Dismiss

#### HTTP

```
POST /api/v1/orgs/{org}/form-failures/{failure}/dismiss
POST /api/v1/platform/form-failures/{failure}/dismiss

Request body:
{
  "reason": "duplicate_submission",
  "note": null  // required iff reason='other'
}
```

Form Request `DismissFormFailureRequest`:

```php
public function rules(): array
{
    return [
        'reason' => ['required', Rule::enum(DismissalReasonType::class)],
        'note' => [
            'nullable',
            'string',
            'max:5000',
            Rule::requiredIf(fn () => $this->input('reason') === DismissalReasonType::OTHER->value),
        ],
    ];
}
```

### 12.4 Resource shape

`FormSubmissionActionFailureResource`:

```json
{
  "id": "01HX...",
  "form_submission_id": "01HX...",
  "submission_summary": {
    "schema_name": "Volunteer Registration 2026",
    "schema_purpose": "event_registration",
    "submitter_label": "Jan Janssen <jan@example.nl>",
    "submitted_at": "2026-04-30T14:22:01Z"
  },
  "listener_class": "ApplyBindingsOnFormSubmit",
  "failed_at": "2026-04-30T14:22:02Z",
  "exception_class": "App\\FormBuilder\\Exceptions\\InvalidBindingTargetException",
  "exception_message": "Target attribute 'shoe_size' not registered on entity 'person'",
  "context": {
    "apply_phase": "binding_resolution",
    "subject_type": "person",
    "subject_id": null
  },
  "state": "failed",
  "resolved_at": null,
  "resolved_by_user": null,
  "resolved_note": null,
  "dismissed_at": null,
  "dismissed_by_user": null,
  "dismissed_reason": null,
  "dismissed_reason_note": null,
  "abilities": {
    "can_retry": true,
    "can_resolve": true,
    "can_dismiss": true
  }
}
```

The `abilities` block reflects policy-evaluated permissions for the requesting user in the requesting context. UI uses these to enable/disable action buttons rather than hard-coding role checks.

---

## 13. Authorization — IDOR-class FK-chain pattern

### 13.1 The threat

`form_submission_action_failures` has no `organisation_id` column. An IDOR-class threat scenario:

1. Org A admin authenticates, gets a list of their org's failures
2. Org B admin can hit `GET /api/v1/orgs/{org-a}/form-failures/{failure-id}/retry` with a failure ID from org A's list
3. If authorization is naive, the failure retries even though org B has no business with it

Naive authorization would be: scope route to `{org}`, fetch failure by ID, retry. The `{org}` route segment is unverified against the failure's actual organisation.

### 13.2 The pattern

`FormSubmissionActionFailurePolicy` resolves the failure's organisation via FK-chain explicitly:

```php
final class FormSubmissionActionFailurePolicy
{
    public function viewAny(User $user, ?Organisation $organisation = null): bool
    {
        if ($organisation === null) {
            // Platform route
            return $user->hasRole('super_admin');
        }
        // Org-scoped route
        return $user->isMemberOf($organisation)
            && $user->can('manage_form_failures', $organisation);
    }

    public function view(User $user, FormSubmissionActionFailure $failure, ?Organisation $organisation = null): bool
    {
        if (! $this->viewAny($user, $organisation)) {
            return false;
        }

        $failureOrgId = $failure->submission->form_schema->organisation_id;

        if ($organisation === null) {
            return true; // super_admin can view any
        }

        return $failureOrgId === $organisation->id;
    }

    public function retry(User $user, FormSubmissionActionFailure $failure, ?Organisation $organisation = null): bool
    {
        return $this->view($user, $failure, $organisation)
            && $failure->state === 'failed';
    }

    public function resolve(User $user, FormSubmissionActionFailure $failure, ?Organisation $organisation = null): bool
    {
        return $this->view($user, $failure, $organisation)
            && in_array($failure->state, ['failed', 'pending'], true);
    }

    public function dismiss(User $user, FormSubmissionActionFailure $failure, ?Organisation $organisation = null): bool
    {
        return $this->view($user, $failure, $organisation)
            && $failure->state === 'failed';
    }
}
```

The `$failure->submission->form_schema->organisation_id` walk is eager-loaded by the controller (`FormSubmissionActionFailure::with(['submission.form_schema'])`) so the policy method does not trigger N+1.

### 13.3 Why not `OrganisationScope`

`OrganisationScope` is FK-chain-resolver-aware (per WS-4 Q2 addendum). It could be configured to walk `form_submission_action_failure → form_submission → form_schema → organisation_id`. But:

1. The chain is three hops; every query against the table would carry three implicit JOINs
2. Platform-wide super_admin queries would need to bypass the scope, adding `withoutGlobalScope` boilerplate at the platform layer
3. Policy-level checks already need to walk the chain for ability evaluation; doing it once in the policy avoids duplication

The IDOR-class FK-chain pattern is the documented preference for tables where:
- Tenant-scoping is essential
- The table has no direct `organisation_id` column (because the data is scoped through a parent)
- Platform-wide views exist and need clean bypass

### 13.4 Tests

`tests/Feature/Api/FormFailureIdorClassTest.php` covers, per policy method:

- Happy path (org A admin acting on org A failure → 200)
- IDOR attempt (org A admin acting on org B failure → 403)
- Platform happy path (super_admin acting on any org's failure → 200)
- Wrong-state attempts (acting on already-resolved failure → 422 / 409 depending on action)

Five policy methods × four cases = twenty tests. The test class is the canonical regression suite for the pattern; reviewers should add a row when any change touches `FormSubmissionActionFailurePolicy`.

---

## 14. Activity log — hierarchical pass + per-binding entries

### 14.1 Two activity levels

The pipeline writes activity-log entries at two granularities:

**Pass level** — one entry per `FormBindingApplicator::apply()` invocation:

```
log_name:    form-builder
description: form_submission.bindings_pass_completed
subject:     FormSubmission Z
causer:      User who submitted (or null for public)
properties:  {
  binding_count: 12,
  succeeded: 11,
  failed: 1,
  person_provisioned: true
}
```

**Binding level** — one entry per binding (success or failure):

```
log_name:    form-builder
description: form_submission.binding_applied
subject:     Person X (or whichever target_entity)
causer:      same as pass-level entry
properties:  {
  parent_activity_id: <pass entry id>,
  target_entity: 'person',
  target_attribute: 'email',
  old_value: null,
  new_value: 'jan@example.nl',
  trust_level: 80,
  merge_strategy: 'overwrite',
  source_form_field_id: 01HX...,
  source_submission_id: Z
}
```

For failed bindings, additional properties:

```
properties: {
  ...,
  error_class: 'TypeError',
  error_message: 'Expected string, got array'
}
```

### 14.2 `parent_activity_id` is a properties field

`spatie/laravel-activitylog` does not natively support hierarchical activity. The hierarchical structure is encoded as a properties-key reference: each binding-level entry stores the pass-level entry's ID under `properties.parent_activity_id`.

This avoids schema changes to the `activity_log` table while supporting hierarchical UI rendering. The trade-off is that reverse traversal ("show me all bindings under this pass") requires a JSON query (`properties->>'$.parent_activity_id' = ?`) which MySQL 8 indexes well via virtual columns if needed (no virtual columns yet — query volume is low and read-pattern is admin-UI not user-facing).

### 14.3 Two sources of truth

Failed bindings appear in both:

- `activity_log` — human-readable timeline
- `form_submission_action_failures` — machine-replayable workflow row

This duplication is deliberate. `activity_log` is for narrative reading: "what happened to this submission". `action_failures` is for state-machine action: "what failed, what state is it in, how do we move it to resolved or dismissed".

A failed binding generates one `activity_log` entry (binding-level with error properties) AND one `form_submission_action_failures` row (only if the entire pass throws — partial-binding failures are TODO for future work; current architecture is all-or-nothing per pass).

### 14.4 UI rendering

The submission-detail review UI renders activity hierarchically:

```
[2026-04-30 14:22:02] Bindings applied (11 succeeded, 1 failed) ▼ expand
  ├ ✓ person.email = "jan@example.nl" (trust 80, overwrite, was null)
  ├ ✓ person.first_name = "Jan" (trust 60, overwrite, was null)
  ├ ✓ person.last_name = "Janssen" (trust 60, overwrite, was null)
  ├ ...
  └ ✗ person.shoe_size = "42" (TypeError) [view failure]
[2026-04-30 14:22:01] Submission submitted by jan@example.nl
```

The `[view failure]` link navigates to `/orgs/{org}/form-failures/{id}` with the failure-record details.

RFC-FORM-BUILDER-UI specifies the styling and interaction details for this view.

---

## 15. Library bindings — copy-at-instantiation semantics

### 15.1 Template-source semantics

`FormFieldLibrary` entries can carry bindings (rows in `form_field_bindings` with `owner_type='form_field_library'`). When a `form_field` is instantiated from a library entry, those bindings are **copied** as new rows with `owner_type='form_field'` and the new field's ULID as `owner_id`.

```php
// Inside FormFieldService::insertFromLibrary
$field = FormField::create([...]);

$libraryBindings = FormFieldBinding::query()
    ->where('owner_type', 'form_field_library')
    ->where('owner_id', $libraryEntry->id)
    ->get();

foreach ($libraryBindings as $libraryBinding) {
    $this->bindingService->copyBindingFor($field, $libraryBinding);
}
```

`copyBindingFor` writes a new row referencing the new field's ULID with the same `target_entity`, `target_attribute`, `merge_strategy`, `trust_level`, `is_identity_key`. The library binding is unchanged.

### 15.2 No runtime cascade

Subsequent edits to a library binding do **not** propagate to existing field instances. If an organisation edits the library entry's `default_binding` (now the relational binding row) to change `merge_strategy=overwrite` to `merge_strategy=replace`, only future field instantiations from that library entry receive the new strategy. Existing fields remain on the old strategy.

This matches the WS-5d decision for `form_field_options` (option lists also copy-at-instantiation, no runtime cascade) and the general template-source pattern documented in ARCH-FORM-BUILDER §17.

### 15.3 Why no cascade

Three reasons:

1. **Predictability for versioning.** A schema published in April uses bindings as they were configured in April. A library edit in May should not silently change the behaviour of April's published schemas.

2. **Audit reproducibility.** A retry of an April submission must apply April's bindings (this is also enforced at the snapshot layer; see §16). Cascade would create a window where the snapshot disagrees with the live state.

3. **Operational safety.** A library admin should be able to fix a typo in a library binding without worrying about which field instances across all organisations will mutate.

The trade-off is that library updates require a manual "re-sync" admin action to propagate to existing instances. That action is BACKLOG `FORM-LIBRARY-RESYNC` — implemented when organisations report friction.

### 15.4 Library audit log

Library binding changes log to `activity_log` under the library entry's subject. Tracking: BACKLOG `FORM-BUILDER-LIBRARY-AUDIT-LOG`. Currently, library edits are scoped to library admins (super_admin or library-manager role); the audit-log entries fire automatically via the existing `LogsActivity` trait on `FormFieldLibrary` and `FormFieldBinding`.

---

## 16. Reproducibility — schema_snapshot and binding contract freezing

### 16.1 The principle

A retry of an April submission must apply the bindings as they were configured at submission time, not as they may have been edited since. This is reproducibility-for-audit.

The mechanism is `form_submissions.schema_snapshot`: a JSON column populated at submission time with the canonicalized schema state. Binding configuration is part of that snapshot.

### 16.2 Snapshot shape (binding-relevant subset)

See ARCH-FORM-BUILDER §4.6.1 for the full snapshot structure. Binding-relevant fields per snapshot field:

```json
{
  "fields": [
    {
      "id": "01HX...",
      "slug": "email",
      "field_type": "email",
      "label": "Emailadres",
      "section_slug": null,
      "binding": {
        "target_entity": "person",
        "target_attribute": "email",
        "merge_strategy": "overwrite",
        "trust_level": 80,
        "is_identity_key": true
      },
      "validation_rules": [...],
      "options": null,
      "conditional_logic": null
    }
  ]
}
```

Note that the snapshot uses an inlined `binding` object per field, not a reference to `form_field_bindings.id`. The canonical contract is "what binding-config this field had at submission time", not "which binding-row backed this field".

### 16.3 Canonicalization

JSON content stored in `form_submissions.schema_snapshot` is canonicalized on write via `App\Support\Json\JsonCanonicalizer::canonicalize()`. The transformation:

- Recursive `ksort` on associative arrays (alphabetical by key)
- Numeric-indexed lists preserve order
- All other content unchanged

This guarantees byte-stability across re-emits of the same logical content. Critical for:

- **Audit-replay diffs** — without canonicalization, MySQL JSON-column round-trip can reorder keys non-deterministically, making "did the snapshot change" hard to answer
- **Webhook payload signing** — HMAC over a JSON string requires byte-stable input
- **Activity log diff regression tests** — `field.updated` activity entries land via `FormField::logFieldChange` which canonicalizes before `withProperties()`

The `SchemaSnapshotByteStableAcrossReemitsTest` test class is the end-to-end contract.

### 16.4 Retry uses the snapshot

`form-builder:retry-failures` does not re-query `form_field_bindings`. It loads the submission's `schema_snapshot`, extracts the per-field `binding` objects, and feeds them into `FormBindingApplicator::applyAll($subject, $resolvedFromSnapshot)`.

Live `form_field_bindings` is only consulted at:

- Pre-publish validation (§8) — checking the current state of the schema against guards
- Snapshot writing (§4.6.1 in ARCH-FORM-BUILDER) — emitting the canonical snapshot at submission time
- Library copying (§15) — instantiating fields from library entries

Apply-time **never** queries `form_field_bindings` directly. Reproducibility is the invariant.

### 16.5 Configuration-only fields excluded

`form_schemas.settings`, `form_schemas.translations`, and similar opaque-config columns are NOT canonicalized — key order has no semantic meaning there. Bindings, fields, sections, and the schema-level metadata that webhooks emit ARE canonicalized.

---

## 17. Conflict resolution & trust precedence

### 17.1 The problem

Two fields can bind to the same `(target_entity, target_attribute)`. Example: a registration schema with both a "Name" field bound to `person.first_name` (trust 80) and a "Display name" field bound to `person.first_name` (trust 50). What happens at apply time?

### 17.2 Candidate set

The candidate set for a given target_attribute is:

> Bindings whose source `form_field` has a row in `form_values` for this submission, regardless of whether the value is null.

The "row exists" gate is binary. Once a binding qualifies, its value is decided by §17.3 below.

The distinction matters because of multi-step / edit-resubmit flows:

- **No row in form_values for this field** → the field was skipped by conditional logic, or the user never reached it. The binding is not a candidate.
- **Row in form_values with `value=null`** → the user explicitly cleared the field (e.g., they set a value, came back to the section, deleted it, and resubmitted). The binding IS a candidate; it may end up writing null to the target depending on the strategy.

### 17.3 Sort order

Candidates are sorted:

1. `trust_level DESC` — higher trust wins
2. `form_field.sort_order ASC` — earlier-in-form wins on ties

The winner is the first row after sorting.

### 17.4 Per-strategy resolution

Once the winner is identified, the merge_strategy applies to determine what (if anything) writes to the target attribute. See §4.3 for the null-winner matrix.

For non-null winner values, the strategy applies straightforwardly:

- `overwrite` — winner value replaces target unconditionally
- `append` — winner value added to collection (deduplicated)
- `replace` — winner value replaces target if target is null
- `first_write_wins` — winner value writes if target is null

### 17.5 Write-path invariant test

For every form_field that should be visible after conditional-logic evaluation at submit time, a `form_values` row must exist after submit, even with null value. This is the invariant that distinguishes "explicit null" from "skipped by conditional logic".

`tests/Feature/FormBuilder/FormSubmissionWritePathInvariantTest.php` asserts this for the seeded fixtures. The test fails if `FormValueService::writeValues` silently drops null values on visible fields.

### 17.6 Why not "first binding wins"

The trust-level + sort-order ordering is more expressive than "first binding wins" because:

- Schema authors can express authority gradients (data from a trusted upstream system at trust 90, user-self-reported at trust 50)
- Renaming or reordering fields in the builder UI does not silently change resolution semantics — the `trust_level` is explicit
- The tie-break on `sort_order` is documented and stable

The cost is that schema authors must understand `trust_level`. The Form Builder UI surfaces this in the binding editor with a tooltip explaining the semantics; defaults are 50 (medium trust).

---

## 18. Test contract & coverage

### 18.1 Categories

Pipeline tests fall into five categories. Each category has a coverage target and a canonical test-class location.

#### Category 1 — Pipeline-agnostic (~20 tests)

Located: `tests/Feature/FormBuilder/Pipeline/`

Coverage:

- Listener registration order test (§5.5)
- Two-transaction failure-write pattern (inner rollback + outer success; outer failure with Sentry capture)
- Post-commit event firing (no listener sees pre-commit state)
- Schema snapshot byte-stability across re-emits
- ApplyStatus state transitions (NULL → pending → completed; NULL → pending → failed; failed → pending → completed via retry; failed → resolved; failed → dismissed)
- IdentityMatchStatus update interplay with apply (apply must complete before identity-match writes status)
- Section-level apply stub (registered, gated, signature forwarding)

#### Category 2 — Per-purpose pipeline (~28 tests)

Located: `tests/Feature/FormBuilder/Pipeline/Purposes/{Purpose}/`

Coverage: 4 cases × 7 purposes = 28 tests.

Per purpose (`event_registration`, `artist_advance`, `supplier_intake`, `post_event_evaluation`, `incident_report`, `signature_contract`, `user_profile`):

- Happy path — submission with all required bindings resolves, applies, persists
- Missing required binding — submission rejected at submit time (via existing form-validation), or apply fails gracefully if validation slipped
- Conflict resolution — two bindings on same target attribute, trust precedence wins
- Anonymous-when-applicable — for purposes where `subject_type` can be null, anonymous submission goes through the stub-resolver path

#### Category 3 — PublishGuard (~18 tests)

Located: `tests/Unit/FormBuilder/Publishing/{Guard}Test.php`

Coverage: 1 passing case + 1 failing case per guard × 9 guards = 18 tests.

Plus a smoke test asserting the four universal guards wire into every `PurposeGuardProvider` (catches "I added a new purpose provider but forgot the universal guards"). 

#### Category 4 — Failure management (~24 tests)

Located: `tests/Feature/FormBuilder/FailureManagement/` and `tests/Feature/Api/FormFailure*Test.php`

Coverage:

- Retry happy path (failed → resolved)
- Retry that throws again (failed → failed with new exception)
- Retry of resolved/dismissed (no-op, idempotent)
- Resolve happy path
- Resolve with optional note
- Dismiss with each `DismissalReasonType` (6 cases)
- Dismiss with `OTHER` requiring `dismissed_reason_note`
- IDOR-class tests (§13.4) — 5 policy methods × 4 cases = 20 tests

#### Category 5 — Activity log (~10 tests)

Located: `tests/Feature/FormBuilder/ActivityLog/`

Coverage:

- Pass-level entry written per applicator invocation
- Per-binding entries written, each with `parent_activity_id`
- Failed binding writes an entry with error properties
- Hierarchical query: given a pass entry ID, retrieve all child binding entries
- Activity log entries reference correct subject types (Person for person bindings, User for user bindings, etc.)

### 18.2 Coverage baseline

Pre-WS-6: 1208 backend tests.

WS-6 added ~278 tests (sessions 1, 2, 3 combined).

Post-WS-6 (main HEAD `4a84b9e`): ~1486 backend tests.

Future binding-pipeline changes should add at least one test per new decision-point and one test per new guard. Reviewers should reject PRs that add new branches in `FormBindingApplicator::apply()` or `FormSchemaService::publish()` without corresponding test additions.

### 18.3 Test data

`FormBuilderDevSeeder` provides fixtures for one event_registration schema per dev-org with 5 fields, 1 draft submission, 1 submitted submission. The submitted submission triggers the §31.10 tag-sync listener inline via `queue.connection=sync` flip in seeder context.

For pipeline tests, factories live under `database/factories/FormFieldBindingFactory.php`, `FormSubmissionFactory.php`, `FormSubmissionActionFailureFactory.php`. They support fluent state methods like `->withApplyStatus(ApplyStatus::FAILED)` and `->forPurpose('event_registration')`.

---

## 19. Out of scope — explicit non-goals + BACKLOG references

The pipeline does not handle:

| Non-goal | BACKLOG item | Rationale |
|---|---|---|
| Composite identity-key resolution (e.g. `email OR (first_name + last_name + DOB)`) | `FORM-BINDING-COMPOSITE-IDENTITY` | V1 enforces single identity-key per target_entity. Multi-attribute matching requires query-language design beyond `firstOrCreate`. |
| Cross-event submission deduplication (one Person, multiple events with separate registrations) | — | Handled by existing `PersonIdentityService` flow, not a binding concern. |
| Library-binding runtime cascade (updates propagate to instantiated fields) | `FORM-LIBRARY-RESYNC` | Copy-at-instantiation semantics chosen for predictability + audit reproducibility. |
| Append strategy on scalar targets | — | Architecturally rejected (V1). Eliminates duplicate-append-on-retry problem class. |
| Active section-level apply | `ARTIST-ADV-SECTION-APPLY` | Stubbed structure with feature flag; activated when artist_advance feature work begins. |
| Daily failure digest mailable | `FORM-FAILURE-DAILY-DIGEST` | Depends on notification framework (post-accreditation engine). |
| Wall-clock concurrent load testing | `LOAD-TEST-FOUNDATION` | Separate workstream; pre-release hardening. |
| ARTIST_ADV-specific binding-target registry entries | `ARTIST-ADV-BINDING-MODEL` | V1 omits artist binding-target registry entries entirely; landing in artist_advance feature work. |
| Partial-binding failure recovery | `PARTIAL-BINDING-SUCCESS` | Current architecture is all-or-nothing per pass: any binding throw rolls back the whole apply. v1.0 deliberate limitation; partial-success requires a SAGA pattern or per-binding-transaction redesign. Trigger: first enterprise customer reports it as a UX issue. |
| Schema-drift detection on migration | `FORM-SCHEMA-DRIFT-DETECTION` | The 5% of runtime applicator throws that the architecture attributes to "DB modified out from under us" deserve dedicated detection. Trigger: first production incident where a runtime-throw is traced to a stale binding after a migration, OR pre-emptive trigger on a large-scale column-renaming. |

When an item moves from out-of-scope to in-scope (e.g., artist_advance work begins), the corresponding BACKLOG item is the entry point. Each BACKLOG item references back to this doc and to RFC-WS-6.

---

## 20. Cross-references & document history

### 20.1 Document references

| Document | Relevance |
|---|---|
| ARCH-FORM-BUILDER.md §17 | `form_field_bindings` table shape + binding semantics in the form-builder domain |
| ARCH-FORM-BUILDER.md §17.3 | PurposeRegistry mechanics, adding a new purpose |
| ARCH-FORM-BUILDER.md §17.4 | Validation rules table (sibling to bindings, same WS-5 split pattern) |
| ARCH-FORM-BUILDER.md §31.1–§31.10 | Integration contracts to non-binding listeners (identity match, GDPR, shifts, mail, code-of-conduct, supplier intake, accreditation hooks, crowd lists, tag sync) |
| ARCH-FORM-BUILDER.md §3.2 | Per-purpose lifecycles |
| ARCH-FORM-BUILDER.md §4.6.1 | Schema snapshot structure + byte-stability addendum |
| SCHEMA.md §3.5.12 | `form_submissions`, `form_field_bindings`, `form_submission_action_failures` table shapes |
| RFC-WS-6.md (frozen 2026-04-25) | Historical design source; cited as `RFC-WS-6 §X` for "why" decisions |
| ARCH-CONSOLIDATION-2026-04.md §6.2 | WS-6 charter |
| ARCH-CONSOLIDATION-ADDENDUM-2026-04-24.md Q1, Q2 | ULID exception retired, denormalized organisation_id pattern |
| ARCH-OBSERVABILITY.md (forthcoming WS-8b) | How pipeline events surface in GlitchTip + Telescope; PII-scrubbing contract for failure exports |
| BACKLOG.md | All deferred items referenced in §19 |

### 20.2 Document history

| Version | Date | Author | Notes |
|---|---|---|---|
| v1.0 | 2026-05-05 | Bert Hausmans (architect), Claude Chat (drafting) | Initial canonical reference, post-WS-6. Aligned to main HEAD `4a84b9e`. |
| v1.1 | 2026-05-07 | Bert Hausmans (architect), Claude Chat (drafting) | Incorporates RFC-WS-6 v1.3 refinements (architectural review 2026-05-07). Twelve section edits, one new section: header version note; §5.1 SYNC chain reduced to one listener; §5.2 listener catalogue updated (TriggerPersonIdentityMatch sync→queued, gating-invariant cross-refs, deadline wrapper, failure_response_code mirror); §5.3 rewritten as "Why SYNC for ApplyBindings only" with deadline-wrapper note; §5.5 listener-ordering test extended for queueing + gating introspection; **§5.6 (new) Queued-listener gating invariant**; §6.2 deadline-wrapper + failure_response_code notes; §7.1 storage table extended with `failure_response_code`; §7.3 failsafe-pad replaced with explicit invariant statement; §8.5 `RequiresIdentityKeyBinding` becomes unconditional for `event_registration`; §11.1 cross-ref to `failure_response_code` companion column; §19 Partial-binding row points at `PARTIAL-BINDING-SUCCESS`, new row for `FORM-SCHEMA-DRIFT-DETECTION`. Spine unchanged (pre-publish guards, strict service / log-and-swallow listener, two-transaction pattern, sync ApplyBindings, snapshot-isolation, single-identity-key per target_entity). |
| v1.2 | 2026-05-08 | Bert Hausmans (architect), Claude Code (drafting) | §5.6 gained the PARTIAL-handling subsection; §7.1 gained the `apply_completed_at` row + intro update + retry-service asymmetry note; §7.2 enum block updated to four cases (added `PARTIAL`) with explanatory paragraph + state-transition diagram updated. No structural changes. Companion: RFC-WS-6 v1.3.1. |

### 20.3 Update protocol

This document updates when:

- A pipeline contract changes (any of §3, §4, §5, §6, §7, §8, §9 — RFC required)
- A failure-management flow changes (§11, §12, §13)
- An out-of-scope item is moved into scope (§19)
- WS-8b lands and §20.1 needs the ARCH-OBSERVABILITY reference filled in concretely

Section-level edits are auto-committed per CLAUDE.md Git Commit Policy. Major contract changes route through RFC + ARCH update + test update + ARCH-FORM-BUILDER cross-ref update as a single commit chain.