crewli/dev-docs/RFC-WS-6.md

RFC-WS-6 — FormBindingApplicator Pipeline Architecture

1. Status

• State: Authoritative for sessions 1, 2, 3 of WS-6
• Frozen: 2026-04-25 (v1.0); refined post-session-2 cleanup as v1.1, then v1.2 (sessie 3a.5), then v1.3 (architectural review 2026-05-07); v1.3.1 (2026-05-08) — code-vs-docs drift closure pre-D1 implementation — see §10
• Implementation status: v1.3.1 fully implemented in main as of 2026-05-08 (D1: PR #10 c6f4d1b, D2: PR #11 23a5696)
• Version: v1.3.1
• Owner: Bert Hausmans
• Origin: Architectural session 2026-04-25 (Claude Chat) — 13 design decisions, 4 refinements, 3 observations
• Related:
  • ARCH-FORM-BUILDER.md §17 (form_field_bindings) and §31 (integration contracts)
  • ARCH-CONSOLIDATION-2026-04.md §6.1 (WS-5a binding table), §6.2 (WS-6 charter)
  • ARCH-CONSOLIDATION-ADDENDUM-2026-04-24.md Q1 (ULID exception retired), Q2 (denormalized organisation_id)
  • SCHEMA.md §3.5.12 (form_submissions, form_field_bindings)
  • BACKLOG.md items: FORM-BINDING-SNAPSHOT-MULTI, FORM-05, FORM-BUILDER-LIBRARY-AUDIT-LOG

2. Why this RFC exists

Charter §6.2 estimated WS-6 at 4-5 days. The architectural review on 2026-04-25 identified scope previously absent from the charter:

• Two-transaction failure-write pattern
• Separate apply_status column distinct from identity_match_status
• form_submission_action_failures table with retry/resolve/dismiss flows
• Dual-route admin UI (platform + organisation)
• Per-purpose PublishGuard framework with ~9 concrete guards
• Append-strategy collection-only restriction
• Section-level apply stub structure (feature-flagged)
• IDOR-class FK-chain policy

Revised estimate: 7-8.5 days across three Claude Code sessions. The overrun is accepted — eerlijke scope, eerlijke inschatting. WS-6 lands as enterprise-grade fundament, not an MVP.

This RFC captures every decision so sessions 2 and 3 do not drift from the architecture established in session 1's planning phase.

3. Decisions

Q1 — Listener ordering on FormSubmissionSubmitted

Decision (v1.3): One synchronous listener (ApplyBindingsOnFormSubmit); all other listeners — including TriggerPersonIdentityMatchOnFormSubmit — queued and parallel.

v1.2 → v1.3: v1.2 had two synchronous listeners (ApplyBindingsOnFormSubmit → TriggerPersonIdentityMatchOnFormSubmit). The 2026-05-07 architectural review reduced the SYNC chain to one listener; identity matching moves to queued. Rationale below.

SYNC chain (registered in EventServiceProvider in this order):
  1. ApplyBindingsOnFormSubmit         ← creates Person (when applicable),
                                          applies all bindings, writes
                                          identity_match_status='pending'
                                          as initial state

QUEUED (no inter-ordering required, all gated on apply_status=COMPLETED):
  - TriggerPersonIdentityMatchOnFormSubmit   ← writes final identity_match_status
  - SyncTagPickerSelectionsOnSubmit
  - CreateProvisionalShiftAssignmentsFromRegistration
  - AddPersonToApplicableCrowdListsOnRegistration
  - FormWebhookDispatcher → DeliverFormWebhookJob
  - RegistrationConfirmation mailable (and other purpose-specific mailables)

Rationale for moving identity-match to queued

PersonIdentityService::detectMatches joins person_identity_matches against persons scoped to the organisation. In organisations with 10k+ Persons (festival with multi-year crew database, or a publisher running many events) this is not "a few hundred milliseconds" — it is seconds, sometimes more. On a public flow at peak (volunteer registration window opens, 100+ concurrent submissions) a synchronous identity-match blocks PHP-FPM workers, queue depth balloons, and the public form endpoint becomes the slow path of the system. This is operationally unacceptable for enterprise SaaS.

The v1.2 rationale for sync identity-match was UX-driven: "the response should carry the right state so the IdentityMatchBanner shows correct copy without a reload." That is a UX requirement, not an architectural one. Stripe, Plaid, and other enterprise products do identity-resolution asynchronously and push state via real-time channels. Soketi is already in the Crewli stack.

What stays sync

ApplyBindingsOnFormSubmit remains 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 response.

Q1 v1.3 addition 1 — Initial identity_match_status='pending' written by ApplyBindings

ApplyBindingsOnFormSubmit::handle writes identity_match_status='pending' inside the inner transaction, immediately after subject resolution. This guarantees the HTTP response carries pending (not null), matching the existing FormSubmissionResource S3a contract for the identity_match block. The portal IdentityMatchBanner renders correctly on first paint with "we're checking matches…" copy.

Q1 v1.3 addition 2 — Echo broadcast on identity_match_status change

TriggerPersonIdentityMatchOnFormSubmit::handle ends with a broadcast on the submission.{submission_id} private channel after writing the final status. Payload:

broadcast(new FormSubmissionIdentityMatchResolved(
    submissionId: $submission->id,
    status: $submission->identity_match_status,  // 'matched' | 'no_match' | 'multiple_candidates'
    matchCount: $submission->identity_match_count,
))->toOthers();

Frontend follow-up (separate ticket, not in WS-6 scope): portal IdentityMatchBanner subscribes to this channel via Laravel Echo and refetches the submission resource when the broadcast lands. This is a small frontend addition that lands after the backend pipeline is stable.

Until the frontend follow-up ships, the existing TanStack Query refetch-on-window-focus behaviour gives users a reasonable experience: status arrives within seconds of returning to the tab. This is acceptable interim behaviour, not the target.

Q1 v1.3 addition 3 — Queued-listener gating invariant

Every queued listener begins with:

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. Without this gate, a failed ApplyBindings (which leaves apply_status=failed and subject_id=null) would still trigger queued listeners that assume a valid Person exists — leading to cascading failures whose root cause is hard to trace.

ARCH-BINDINGS §5.6 (new section) documents this invariant. The listener-registration test (EventServiceProviderListenerOrderTest) extends to assert the invariant via listener-class introspection (each ShouldQueue listener has the gate as its first statement). If a contributor adds a queued listener without the gate, the test fails before code review.

Q1 v1.3 addition 4 — Sync-chain hard timeout

ApplyBindingsOnFormSubmit runs inside a 5-second deadline wrapper. Implementation:

$applicator->withDeadline(seconds: 5)->apply($submission);

Internal: a wrapper service tracks elapsed time per binding-resolution step. On deadline-exceeded: throws FormBindingApplicatorTimeoutException, caught by the outer transaction handler, written as a form_submission_action_failures row with exception_class=FormBindingApplicatorTimeoutException and apply_status='failed'.

The 5-second value is configurable via config('form_builder.apply_deadline_seconds') with default 5. Documented in config/form_builder.php with a comment block on when to tune it (very large schemas with many bindings, identity-key resolution on massive person pools — neither expected in v1.0).

This addition guarantees that no submission can hang the public flow for more than a bounded interval. Slow paths surface as failures, not as hung connections.

Q1 v1.3.1 clarification — apply_status four-case enumeration

apply_status has four states:

• pending — apply has started but the inner transaction has not committed
• completed — every binding in the pass succeeded; the inner transaction committed
• partial — at least one binding in the pass failed AND at least one succeeded; the inner transaction committed (per BindingPassResult::applyStatus()); see BACKLOG PARTIAL-BINDING-SUCCESS for the long-term direction
• failed — every binding failed OR the deadline-wrapper threw; the inner transaction rolled back; an entry exists in form_submission_action_failures

NULL means apply has not yet run on this submission.

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. Per RFC v1.3 §Q3 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 ARCH-BINDINGS §5.6).

Q2 — Refactor of TriggerPersonIdentityMatchOnFormSubmit

Decision (v1.3): Remove the "no subject → pending" failsafe path. Replace with an explicit invariant and a strict throw routed through the existing form_submission_action_failures pipeline.

v1.2 → v1.3: v1.2 trimmed the "no subject → pending" path to a logged warning failsafe and kept it as defensive code. The 2026-05-07 review judged the failsafe architecturally dishonest (path either needed coherently or removed) and converted it to an explicit invariant + strict throw. Companion: RequiresIdentityKeyBinding wires unconditionally for event_registration (drop the ConditionalRequirement wrapper). The two listeners stay separate (testability, single-responsibility).

Rationale for removing the failsafe

A path that "should never trigger but stays as a logged warning failsafe" is architecturally dishonest. Either the path is needed (and should have a coherent behaviour, not a half-measure), or it is not (and should be removed).

The v1.2 rationale was catches misconfigured schemas and silent ApplyBindings failures. Both motivations dissolve under scrutiny:

• Misconfigured schemas: should be caught by publish-guards. If a schema lands in a state where post-ApplyBindings subject_type=null for event_registration, there is a gap in the publish-guard logic. The fix is to close that gap, not to paper over it with a runtime warning.
• Silent ApplyBindings failures: already write a form_submission_action_failures row. A second Log::warning in a downstream listener creates two parallel audit trails that can drift out of sync. In production, incident triage works on one canonical source.

The replaced behaviour

TriggerPersonIdentityMatchOnFormSubmit::handle:

public function handle(FormSubmissionSubmitted $event): void
{
    $submission = $event->submission->fresh();

    // Gate (per §Q1 addition 3)
    if ($submission->apply_status !== ApplyStatus::COMPLETED) {
        return;
    }

    // Non-person purposes are no-ops by design
    if ($submission->subject_type !== 'person') {
        return;
    }

    // Invariant: post-ApplyBindings for event_registration with subject_type='person'
    // means subject_id is non-null. If it isn't, that's a schema-level bug
    // that publish-guards failed to catch. Strict throw via the same pipeline.
    if ($submission->subject_id === null) {
        throw new IdentityMatchInvariantViolation(
            "subject_type='person' but subject_id=null after ApplyBindings COMPLETED. "
            . "submission_id={$submission->id}"
        );
    }

    $person = Person::withoutGlobalScopes()->find($submission->subject_id);
    $result = $this->personIdentityService->detectMatches($person);

    $submission->update([
        'identity_match_status' => $result->status,
        'identity_match_count' => $result->matchCount,
    ]);

    broadcast(new FormSubmissionIdentityMatchResolved(
        submissionId: $submission->id,
        status: $result->status,
        matchCount: $result->matchCount,
    ))->toOthers();
}

The throw path: caught by Laravel's queue worker, written via the existing exception handler to GlitchTip with full context, and written to form_submission_action_failures if the listener-level handler is configured to do so (proposed: yes, for cross-listener auditability — see §Q3 below). This gives one canonical failure trail.

The new invariant — explicit

ARCH-BINDINGS §7.3 documents the invariant, not a failsafe-pad description:

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.

Companion change — RequiresIdentityKeyBinding always required for event_registration

The v1.2 publish-guard provider for event_registration wraps RequiresIdentityKeyBinding('person', 'email') in ConditionalRequirement(predicate: public_token !== null, …). This means private event_registration schemas (organizer-driven, used for managed crew rosters) can publish without an identity-key binding — and then ApplyBindings has nothing to provision against, the failsafe-pad triggers, the architecture leaks.

Revised guard wiring (v1.3): drop the predicate. RequiresIdentityKeyBinding('person', 'email') wires unconditionally for event_registration. The semantic is: "this purpose creates or matches a Person — that always requires an identity-key, regardless of form visibility." Private schemas without an email-binding fail to publish with a clear error message.

This closes the gap the failsafe-pad was protecting against. The pad is no longer needed because the schema can no longer reach a state where it is needed.

Companion change — FormSubmissionResource.identity_match

For non-person purposes (signature_contract, user_profile, incident_report, post_event_evaluation, supplier_intake, artist_advance), the resource block:

"identity_match": null

Currently the contract leaves this implicit. v1.3 makes it explicit and adds a contract test in tests/Feature/Api/FormSubmissionResourceTest that asserts the field is null for all non-person purposes. This prevents a future refactor from silently introducing ambiguity.

Q3 — Strict-fail backend, log-and-swallow listener

Decision: FormBindingApplicator (service) throws strictly on invalid state; ApplyBindingsOnFormSubmit (listener) catches, records via form_submission_action_failures, swallows.

Service-layer throws on invalid MergeStrategy, missing required binding spec keys, deleted target columns, type-shape mismatches. Pre-publish guards (PurposeGuardProvider::publishGuards()) catch ~95% of these at config time. Runtime throws are reserved for "DB modified out from under us" rare cases.

Listener catches the throw, writes a row to form_submission_action_failures (in a separate transaction — see Q4), logs at error, swallows so sibling listeners (tag sync, shifts, webhooks, mail) keep running.

SyncTagPickerSelectionsOnSubmit is NOT folded into ApplyBindings. TAG_PICKER → user_organisation_tags is a pivot-table-with-source-discrimination operation, semantically distinct from a binding-target-attribute write. Document the deliberate parallel paths in ARCH-BINDINGS.md so future readers don't try to consolidate them.

Q3 v1.3 — Failure-UX additions

v1.2 → v1.3: spine unchanged (strict service / log-and-swallow listener / two-transaction pattern / pre-publish guards as primary defence). Three additions bring failure-UX to enterprise baseline; a fourth captures schema-drift detection as a tracked BACKLOG item.

Q3 v1.3 addition 1 — Real-time admin alert for public-form failures

GlitchTip (operational since WS-7) runs an alert rule:

event.exception.values[0].type = "FormBindingApplicatorException"
AND tags.form_schema.public_token IS NOT NULL
AND tags.environment = "production"
→ alert: email to ops@crewli + Slack webhook

This sluit the operational loop: a public form failing for any reason (typically a schema-config issue that slipped past publish-guards, or an infra blip) surfaces within seconds, not "the next day when admin checks the failures UI." For enterprise operations during an active festival registration window this is the difference between a 5-minute incident and a 4-hour incident.

Implementation: LogContextEnricher (already exists per ARCH-OBSERVABILITY) tags GlitchTip events with form_schema.public_token (boolean: present or not). ApplyBindingsOnFormSubmit's exception-report path includes Sentry::captureException($e, ['tags' => ['form_schema.has_public_token' => …]]). Alert rule configured in GlitchTip web UI; documented in dev-docs/runbooks/observability-triage.md under "Form-builder binding failures".

Scope: WS-6 sessie 3 (Admin UI) includes the GlitchTip configuration as a deployment task; the tagging happens in sessie 2 (Pipeline) as part of ApplyBindingsOnFormSubmit.

Q3 v1.3 addition 2 — Custom exception hierarchy + error_code in HTTP response

FormBindingApplicatorException is the abstract base. Three subclasses:

Subclass	Cause	HTTP code	User-facing copy class
FormBindingSchemaConfigException	Schema misconfiguration that publish-guards missed (e.g., column renamed without schema invalidation)	422	schema_config_error — "This form has a configuration issue. Please contact the organiser. Reference: F-{ulid}"
FormBindingInfraException	Database connection lost, timeout, race condition on lockForUpdate	503	temporary_error — "Temporary issue, please try again." with retry-after header
FormBindingDataIntegrityException	Type mismatch, foreign-key violation, attempt to write to a soft-deleted entity	422	data_integrity_error — same copy as schema_config (user-perceptible same; admin sees difference via tag)

Listener catches the parent class, inspects subclass, writes appropriate response:

// In ApplyBindingsOnFormSubmit::handle's catch block, after the failure-record write:
$response = match (true) {
    $e instanceof FormBindingInfraException        => ['error_code' => 'temporary_error',     'http_status' => 503],
    $e instanceof FormBindingSchemaConfigException => ['error_code' => 'schema_config_error', 'http_status' => 422],
    $e instanceof FormBindingDataIntegrityException => ['error_code' => 'data_integrity_error','http_status' => 422],
    default                                         => ['error_code' => 'unknown_error',       'http_status' => 500],
};
$submission->update(['failure_response_code' => $response['error_code']]);

The failure_response_code column on form_submissions (new in WS-6 sessie 1) is read by the response renderer; the controller serializes this into the API response body when apply_status=failed. Frontend renders contextual copy keyed on error_code. Reference ID is the submission.id ULID — admin uses it to find the matching form_submission_action_failures row.

Q3 v1.3 addition 3 — "All-or-nothing per pass" — explicit BACKLOG entry

ARCH-BINDINGS §19 currently says: "Granular partial-success is a future RFC topic." That is too open-ended for a no-compromises release.

Revised treatment: Move from "future RFC topic" to explicit BACKLOG entry PARTIAL-BINDING-SUCCESS with:

• Trigger condition: First enterprise customer reports the all-or-nothing behaviour as a UX issue (concretely: a registration form submission rolls back due to one binding failing, customer complains that "the user filled in 12 fields and lost everything")
• Design hints: SAGA pattern with per-binding compensation OR per-binding transaction with idempotency-keys per binding-application (the latter requires rethinking the trust-precedence resolution)
• Estimated work: 4-6 days, not in scope until trigger fires
• Refs: ARCH-BINDINGS §19, RFC-WS-6 §Q3 v1.3

ARCH-BINDINGS §19 is rewritten to point at this BACKLOG entry rather than leaving the door half-open.

Q3 v1.3 addition 4 — Schema-drift detection (separate BACKLOG entry, not v1.0 work)

The 5% of runtime-throws that the RFC attributes to "DB modified out from under us" deserve more architectural respect than a one-line acknowledgement. New BACKLOG entry FORM-SCHEMA-DRIFT-DETECTION:

• Scope: A migration-listener that, when a binding_target_type-affected column is renamed/dropped/type-changed, scans form_field_bindings.target_attribute for matches and marks affected form_schemas with needs_revalidation=true. Schema-detail UI shows a banner; affected schemas can't have new submissions accepted until an organiser re-publishes.
• Trigger condition: First production incident where a runtime-throw is traced to a stale binding after a migration.
• Estimated work: 2-3 days.
• Refs: ARCH-BINDINGS §6.5 (binding-change safety, related but distinct), RFC-WS-6 §Q3 v1.3.

This is not v1.0 scope but should be on the radar so it doesn't surface as a surprise during the first 6 months of enterprise rollout.

Q4 — Two-transaction atomicity pattern

Decision: ApplyBindings + Identity status update in one inner DB transaction. Failure-record write in a separate outer transaction. Event firing AFTER commit.

try {
    DB::transaction(function () use ($submission) {
        $subject = $this->provisioner->provision($submission);
        $resolved = $this->resolveBindings($submission);
        $this->applyAll($subject, $resolved);
        $this->writeApplyStatus($submission, ApplyStatus::COMPLETED);
        $this->triggerIdentityMatch($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'            => [...],
        ]);
        FormSubmission::query()
            ->whereKey($submission->id)
            ->update(['apply_status' => ApplyStatus::FAILED->value]);
    });
    Log::error('form-builder.apply.transaction_rolled_back', [
        'submission_id' => $submission->id,
        'exception'     => $e::class,
    ]);
}

Person provision uses SELECT ... FOR UPDATE on email lookup. Race conditions resolve to firstOrCreate semantics.

The inner transaction rollback survives the failure-record write because the failure row is in a different transaction. The second transaction is small (one insert + one update) — its failure path is Sentry-only, with explicit error log line for filterability.

FormSubmissionSubmitted event fires AFTER the inner transaction commits. This is non-negotiable: queued listeners (tag sync, shifts, webhooks, mail) must never see pre-commit state. Implementation uses explicit ordering in FormSubmissionService::submit() — service fires the event, not the Eloquent observer (per O2).

Q5 — form_submission_action_failures complete in WS-6 (incl. admin UI)

Decision: Full table + write path + retry artisan command + dual-route admin UI (super_admin platform-wide + org_admin scoped) + retry/resolve/dismiss flows. All in WS-6 across sessions 2 (backend) and 3 (UI).

Schema:

form_submission_action_failures:
  id                    ulid pk
  form_submission_id    ulid fk → form_submissions, cascade delete
  listener_class        string(255)
  binding_id            ulid fk nullable → form_field_bindings, null on delete
  failed_at             timestamp
  exception_class       string(255)
  exception_message     text
  context               json
  retry_count           unsignedTinyInteger default 0
  resolved_at           timestamp nullable
  resolved_by_user_id   ulid fk nullable → users
  resolved_note         text nullable
  dismissed_at          timestamp nullable
  dismissed_by_user_id  ulid fk nullable → users
  dismissed_reason_type string(40) nullable    -- DismissalReasonType enum
  dismissed_reason_note string(500) nullable   -- required when type = 'other'
  created_at, updated_at

No soft delete. Retention follows the parent submission via cascade-delete.

No organisation_id column on this table — tenant scope flows via form_submission_id → form_submissions.organisation_id. See V3 below for policy implications.

Three actions in the admin UI:

• Retry — re-runs the applicator for this submission. Idempotent. Increments retry_count. On success: sets resolved_at = now(). On repeat failure: another row appended (history preserved).
• Mark as resolved — manual close, optional resolved_note. Used when an admin fixed the data via a different path.
• Dismiss — final close, requires dismissed_reason_type (enum), dismissed_reason_note required only when type = OTHER. Used when retry is impossible (schema deleted, target deleted).

Daily digest mailable is deferred to the notification framework (out of scope WS-6 — depends on infrastructure not yet in place).

Q6 — Snapshot is truth, not live schema

Decision: FormBindingApplicator reads bindings from form_submissions.schema_snapshot.fields[*].bindings, not from the live form_field_bindings table.

Webhook payload, GDPR export, and audit replay all use schema_snapshot. Bindings follow the same pattern. The live table is consulted only for pre-publish validation by FormSchemaService.

This guarantees that a retry-from-failures-table executed a week after the original submission applies the bindings as they were configured at submit time, not as they may have been edited since. Reproducibility for audit.

Q7 — Conflict resolution: candidate set + trust precedence

Decision: Candidate set = bindings whose source form_field has a row in form_values for this submission, regardless of whether the value is null. Sort by trust_level DESC, tie-break by form_field.sort_order ASC. Empty winner writes null when merge_strategy allows it.

The candidate distinction matters: a row in form_values with value = null is an explicit clear by the user (multi-step form, edit-resubmit). Absence of a row means the field was not submitted (conditional logic skipped it, validation rejected it, etc.). The binary "row exists" is the gate; value content is decided afterwards.

Per-strategy null-winner matrix:

merge_strategy	Winner value = null	Behaviour
overwrite	null	Write null to target (intent: clear)
append	null	No-op (nothing to append; target unchanged)
replace	null	No-op when target is already non-null; no-op when target is null
first_write_wins	null	Write null when target is null (claim the slot); skip when target has any value

append is restricted to collection-typed targets per V1 — the matrix entry above describes the no-op case for completeness.

Write-path invariant test required (session 2): for every form_field that should be visible after conditional-logic evaluation at submit time, a form_values row exists after submit, even with null value. Otherwise "explicit null" is indistinguishable from "skipped by logic" and Q7 collapses.

Q8 — Single identity-key per target_entity

Decision: At most one binding per (target_entity) may have is_identity_key = true, enforced by the MaxOneIdentityKeyPerTargetEntity publish guard. PersonProvisioner::provisionFromBindings uses Person::firstOrCreate(['email' => $value, 'organisation_id' => $orgId], $otherBindings). Race-safe via DB-driver firstOrCreate semantics.

Composite identity (email OR (first_name + last_name + DOB)) is out of scope for v1.0. Backlog item FORM-BINDING-COMPOSITE-IDENTITY tracks the future work. Identity-matching against existing user accounts (via person_identity_matches) is a separate flow, not in scope here — that's PersonIdentityService running after provision.

Q8 v1.1 addendum — Person provisioning is scoped by event_id, not organisation_id

The v1.0 text above describes the firstOrCreate predicate as (email, organisation_id). That is incorrect for the actual Person model: Person::$organisationScopeColumn = 'event_id' (single source of truth for tenant scoping on this model — organisation_id is the denormalised parent column, event_id is the scope discriminator).

PersonProvisioner::provisionFromSubmission() therefore looks up and creates by (email, event_id):

Person::query()
    ->withoutGlobalScopes()
    ->where('email', $emailValue)
    ->where('event_id', $submission->event_id)
    ->lockForUpdate()
    ->first();
// ...
Person::query()
    ->withoutGlobalScopes()
    ->firstOrCreate(
        ['email' => $emailValue, 'event_id' => $submission->event_id],
        $attributes,
    );

Practical consequence: the same email registering for two different events in the same organisation creates two distinct Person rows. Cross-event identity reconciliation is the job of PersonIdentityService / person_identity_matches (existing flow, out of scope for WS-6 — see RFC §6).

PersonProvisioner raises PersonProvisioningException('no_event', ...) when submission.event_id is null on an event_registration submission. Schemas reaching apply without event_id is a structural defect; the publish guard SchemaHasLinkedEvent prevents it at config time, the runtime throw is the failsafe.

Q9 — Apply uniform across all 7 purposes; provisioning per PurposeDefinition

Decision: FormBindingApplicator::apply() is purpose-agnostic. Subject resolution lives on PurposeDefinition::resolveOrProvisionSubject(FormSubmission, PersonProvisioner): ?Model.

event_registration       → PersonProvisioner::provisionByEmailBinding (may create)
artist_advance           → ArtistResolver::fromPortalToken (existing context, throws if absent)
supplier_intake          → CompanyResolver::fromProductionRequest
post_event_evaluation    → PersonResolver::fromAuth
incident_report          → PersonResolver::fromAuth OR null (anonymous-allowed)
signature_contract       → UserResolver::fromAuth
user_profile             → UserResolver::fromAuth

Test coverage: 4 cases per purpose minimum (happy-path, missing required binding, conflict-resolution, anonymous-when-applicable) → 28 + ~20 purpose-agnostic = ~48 pipeline tests in session 2.

Q9 v1.1 addendum — form_schemas.default_crowd_type_id replaces CrowdType::oldest()

Person.crowd_type_id is NOT NULL on the migration; PersonProvisioner must supply a value at create time. Session 2 used a silent CrowdType::oldest()->where('organisation_id', ...) heuristic — fragile (depends on insertion order, breaks across organisations, no auditable intent) and undocumented in the published schema.

Decision (v1.1): add form_schemas.default_crowd_type_id (nullable ULID column) to make the target CrowdType an explicit, versioned schema attribute. PersonProvisioner::resolveCrowdTypeId() reads $submission->schema->default_crowd_type_id and throws PersonProvisioningException('no_default_crowd_type', ...) when null.

A new universal-on-event_registration publish guard RequiresDefaultCrowdType blocks publish when the column is null on a schema with purpose = event_registration. The runtime throw remains as a failsafe for live-table edits between publish and apply.

Schema-level FK omitted intentionally. The migration adds the column without a database-level foreign key. SQLite's table-rebuild on ALTER TABLE ADD FOREIGN KEY cascade-deletes existing form_fields rows when an unrelated FK on the rebuilt table happens to overlap — observed in WS-5b/c backfill tests. Application-level integrity (publish guard + runtime failsafe + Eloquent belongsTo for read-side correctness) is sufficient: writes always go through FormSchemaService::publish(), which runs the guard, and the runtime throw blocks any apply that slipped past.

Snapshot impact: none. The published schema_snapshot does not embed default_crowd_type_id directly; provisioning reads from the live FormSchema row by FK from FormSubmission::form_schema_id. Audit replay (RFC Q6) of an old snapshot uses whatever the schema's current default_crowd_type_id is at retry time — admins are expected to either update the column before retrying or dismiss with reason SCHEMA_DELETED / OTHER.

FormBuilderDevSeeder resolves a CrowdType via VOLUNTEER → first-active → create-as-needed fallback chain when seeding event_registration schemas, so dev environments don't fail the publish guard out of the box.

Q9 v1.2 addendum — Registry alignment with model columns

Sessie 3a surfaced that several entries in the BindingTypeRegistry config did not match actual Eloquent model column names (person.phone_number vs phone, company.email vs contact_email, company.phone_number vs contact_phone) and that an Artist Eloquent model class is absent.

Sessie 3a.5 corrected this:

• Renames (registry → matches model column): person.phone_number → person.phone, company.email → company.contact_email, company.phone_number → company.contact_phone.
• New column: companies.kvk_number (nullable, indexed) added so the registry's B2B identity-key candidate is now legitimately bindable.
• Removed entries (intentional v1 deferrals): person.dietary_preferences (custom_fields JSON path; BACKLOG FORM-BINDING-JSON-PATH), artist.email / artist.stage_name / artist.tech_rider / artist.hospitality_rider (column absent + Artist model absent), and the artist entity removed entirely from the registry (BACKLOG ARTIST-ADV-BINDING-MODEL).
• Drift-prevention test: BindingTypeRegistryConsistencyTest extended with a model-existence + column-existence assertion. Future drift surfaces as a test failure, not a runtime surprise.

artist_advance schemas may still exist in v1 with empty required_bindings; the applicator runs and resolves to an empty binding list, COMPLETED state. See ARCH-BINDINGS.md appendix for the rationale.

Q10 — Section-level submit: stub now, activate later

Decision: Build the listener-class structure now; gate the runtime via config('form_builder.section_apply_enabled', false); activate when ARTIST_ADVANCE feature work lands.

class ApplyBindingsOnFormSectionSubmitted implements ShouldQueue
{
    public function handle(FormSubmissionSectionSubmitted $event): void
    {
        if (!config('form_builder.section_apply_enabled', false)) {
            return;
        }
        $this->applicator->apply($event->submission, sectionId: $event->sectionId);
    }
}

FormBindingApplicator::apply() accepts an optional sectionId parameter. Null = all bindings. Set = only bindings whose source form_field's section_id matches. Listener registered in EventServiceProvider from session 2.

Publish guards land NOW for section-aware schemas, regardless of feature flag. A schema with section_level_submit = true and an is_identity_key binding in section 3 is structurally unsafe; it must not pass publish even if the runtime listener is gated off. The IdentityKeyBindingsOnlyInFirstSection guard wires into every PurposeGuardProvider as a universal guard from session 1 (no-op for non-section schemas).

Feature flag has explicit removal trigger documented in config/form_builder/section_apply.php comment block: "Enable when ARTIST_ADVANCE feature work begins. At enablement: write section-scoped tests, activate stub listener registration, remove this flag and the early-return guard. Tracking: BACKLOG.md → ARTIST-ADV-SECTION-APPLY."

A minimal wiring test asserts the stub listener is registered and forwards correctly to the applicator signature — no business logic, just keeping the path alive.

Q11 — Library-binding propagation: copy at instantiation, no runtime cascade

Decision: When a form_field is created from a FormFieldLibrary entry with bindings, the library-bindings are copied to form_field_bindings rows with owner_type = 'form_field'. Subsequent updates to the library-bindings do NOT propagate to existing field instances. Future "library re-sync" admin action lives on the BACKLOG.

This matches the WS-5d decision for form_field_options and is consistent with template-source semantics. Predictable for versioning. Documented explicitly in ARCH-BINDINGS.md: "the library is a template-source, not a live link."

Q12 — Activity log: hierarchical pass + per-binding entries

Decision: One form_submission.bindings_pass_completed activity per applicator invocation, plus one form_submission.binding_applied activity per binding (linked via properties.parent_activity_id).

activity 1: form_submission.bindings_pass_completed
  subject: form_submission Z
  properties: {
    binding_count: 12,
    succeeded: 11,
    failed: 1,
    person_provisioned: true
  }

activity 2..13: form_submission.binding_applied
  subject: person X (or whichever target entity)
  properties: {
    parent_activity_id: <activity 1 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: ...,
    source_submission_id: Z
  }

Spatie/laravel-activitylog supports arbitrary properties; parent_activity_id is just a properties field. UI renders this hierarchically as a collapse: pass-level visible, per-binding expandable. Failed bindings get their own activity entry too (properties.error_class/error_message), in addition to their form_submission_action_failures row.

Two sources of truth for failures (activity_log + action_failures) is intentional: activity_log is the human-readable timeline, action_failures is the machine-replayable workflow.

Q13 — Pre-publish validation: PurposeGuardProvider framework

Decision: Pre-publish rules live on a parallel PurposeGuardProvider interface (NOT on PurposeDefinition, which stays an immutable value object). Each purpose's concrete provider returns a list<PublishGuard>. FormSchemaService::publish() walks the list, runs every guard, collects all violations, and throws a PublishGuardViolationException with the full list (not first-fail).

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

Nine concrete guards in App\FormBuilder\Publishing\:

1. RequiresIdentityKeyBinding(entity, attribute) — flag-check (binding existence enforced separately by assertRequiredBindingsPresent)
2. MaxOneIdentityKeyPerTargetEntity — universal
3. RequiresFieldType(type, minCount)
4. SchemaHasLinkedEvent
5. TagCategoriesConfiguredOnAllPickers
6. IdentityKeyBindingsOnlyInFirstSection — universal (no-op for non-section schemas)
7. AppendStrategyRequiresCollectionTarget — universal (paired with V1)
8. NoAmbiguousTrustLevels — universal
9. ConditionalRequirement(predicate, subGuard) — higher-order composer

Universal guards (2, 6, 7, 8) wire into every purpose. Purpose-specific guards per the Task 8 table.

The PurposeGuardProvider is wired into purposes.php via a new guards_class key per purpose. PurposeRegistry::guardProviderFor(string $slug) instantiates and caches.

Open-closed: a new purpose adds its own PurposeDefinition config entry plus a new PurposeGuardProvider class; FormSchemaService::publish() does not change.

4. Refinements

V1 — Append strategy is collection-only

Decision: merge_strategy = APPEND is valid only when the target attribute resolves to BindingTargetType::COLLECTION per BindingTypeRegistry. Pre-publish guard AppendStrategyRequiresCollectionTarget enforces this.

Rationale: append on 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 (JSON array with deduplication, pivot relations) make retry naturally idempotent. This restriction eliminates the entire problem class.

The BindingTypeRegistry is the single source of truth for target shape — NOT name-suffix matching (e.g. attributes ending in _tags or _skills). Name-suffix matching is convention-not-contract and would silently misclassify any attribute that doesn't follow the convention or accidentally matches it (e.g. user_tags_count would falsely qualify as collection).

V2 — DismissalReasonType enum + resolve action separated

Decision: Six enum values (schema_deleted, target_entity_deleted, binding_removed, duplicate_submission, data_quality_issue, other). Free-text dismissed_reason_note required only for other. Resolve is a separate action with its own resolved_note (no enum), distinct from dismiss.

Three admin actions on a failure:

• Retry — replay the applicator
• Mark as resolved — manual close (succeeded via another path)
• Dismiss — final close (will not be replayed); requires reason enum

Dismiss-without-enum was rejected because "diversen-syndroom" makes failure analytics impossible after six months. manually_resolved as a dismissal reason was rejected because resolve and dismiss are semantically different workflows.

V3 — IDOR-class FK-chain policy

Decision: FormSubmissionActionFailurePolicy resolves tenant via failure.submission.organisation_id, NOT via route binding. Cross-tenant access returns false from the policy; controllers translate to 404 (not 403, which would confirm resource existence and enable enumeration).

Security tests in this class are explicitly named as IDOR-class so they are findable in audit. Pattern follows ARCH §22.9 FormResourceSecurityTest.

V4 — Concurrent-test via PHPUnit state-injection

Decision: PHPUnit-based concurrent test with state-injection (insert conflicting Person row inside lockForUpdate window, assert firstOrCreate recovery). NOT an Artisan command + manual TEST_SCENARIO.md step.

A handmatige test is geen test. State-injection in PHPUnit tests the recovery path under the actual conflict condition — which is what matters. Real wall-clock load testing belongs in a separate "Load-test foundation" workstream against staging (BACKLOG: LOAD-TEST-FOUNDATION).

5. Observations

O1 — apply_status default for legacy rows = NULL

Existing seed-data and pre-WS-6 staging submissions have no apply_status. Migration adds the column WITHOUT a default. Admin UI's "open work" filter explicitly excludes NULL rows so legacy submissions don't appear as "pending applicator work that will never run." Document in migration file comment block.

O2 — Event firing AFTER DB::afterCommit() (or explicit post-commit dispatch)

FormSubmissionSubmitted must fire after the inner transaction commits, not before. Implementation: FormSubmissionService::submit() runs the transaction, then explicitly calls event(new FormSubmissionSubmitted($submission->refresh())). Do NOT rely on Eloquent observers firing the event from within the transaction — that pre-commit fire would let queued listeners enqueue with state that may never commit.

O3 — RFC-WS-6.md as session-handover anchor

This document. Sessions 2 and 3 reference RFC sections by number rather than re-establishing context. Drift between chat decisions and code implementation is prevented by committing the RFC before any session-1 code lands.

6. Out of scope (explicit non-goals for v1)

• Composite identity-key resolution (multi-attribute matching) → BACKLOG: FORM-BINDING-COMPOSITE-IDENTITY
• Cross-event submission deduplication (one Person, multiple events with separate registrations) → handled by existing identity-match flow, not a binding concern
• Library-binding runtime cascade (updates propagate to instantiated fields) → BACKLOG: FORM-LIBRARY-RESYNC
• Append strategy on scalar targets → architecturally rejected (V1)
• Active section-level apply → stub structure only; activated when ARTIST_ADVANCE feature work begins (BACKLOG: ARTIST-ADV-SECTION-APPLY)
• Daily failure digest mailable → depends on notification framework not yet built
• Wall-clock concurrent load testing → BACKLOG: LOAD-TEST-FOUNDATION (separate workstream)

7. Sessions split

Session	Scope	Estimate
1 — Foundation	Schema migrations (apply_status, action_failures), enums (ApplyStatus, DismissalReasonType, BindingTargetType), MergeStrategy enum methods, value objects (ResolvedBinding, BindingApplicationResult, BindingPassResult), BindingTypeRegistry + config, Models, FormSubmissionActionFailurePolicy, PublishGuard framework + 9 concrete guards, PurposeGuardProvider interface + 7 concrete providers, FormSchemaService publish integration, ARCH-BINDINGS.md skeleton, this RFC	2-2.5 days
2 — Pipeline	FormBindingApplicator service, PersonProvisioner, multi-purpose subject resolvers, listener chain (sync ApplyBindings + sync TriggerPersonIdentityMatch + queued siblings), two-transaction pattern, ApplyBindings stub for section-submit, retry/resolve/dismiss artisan commands + controllers + Form Requests + Resources, all backend tests (~100-120 new), ARCH-BINDINGS.md sections 6-9 filled	3-4 days
3 — Admin UI	Vuexy admin UI on /platform/form-failures (super_admin) and /orgs/{org}/form-failures (org_admin), retry + resolve + dismiss flows, IDOR-class API security tests, ARCH-BINDINGS.md final, ARCH-OBSERVABILITY.md initial draft	1.5-2 days

Total: 7-8.5 days. Charter §6.2 had 4-5 days; the overrun is explicit and accepted (see §2 of this RFC).

8. Test coverage targets

Session	New tests	Cumulative backend
Pre-WS-6 baseline	—	1208
Session 1	~90-110	~1300-1320
Session 2	~110	~1410-1430
Session 3	~35	~1445-1465

9. Open follow-ups (post-WS-6)

BACKLOG item	Trigger
FORM-BINDING-COMPOSITE-IDENTITY	When a purpose requires multi-attribute identity resolution
FORM-LIBRARY-RESYNC	When organisations report friction updating library-derived fields
ARTIST-ADV-SECTION-APPLY	When ARTIST_ADVANCE feature work begins (post-S5)
LOAD-TEST-FOUNDATION	Pre-release hardening, separate workstream
FORM-BINDING-SNAPSHOT-MULTI	When patterns require multi-binding-per-field snapshot shape
Daily failure digest	When notification framework lands
Observability	Sentry SDK, structured logs, metrics, alerts — see ARCH-OBSERVABILITY.md skeleton (sessie 3b). WS-7 sessie 1 fills it in.

Observability strategy for the WS-6 binding pipeline (Sentry $dontReport decisions, log levels, metric names) is documented in ARCH-OBSERVABILITY.md. The skeleton landed in WS-6 sessie 3b with §3 ($dontReport) concrete; the remaining sections are filled in WS-7 sessie 1.

10. Document history

• 2026-04-25 — v1.0 — Initial RFC, frozen at start of WS-6 session 1.
• 2026-04-28 — v1.1 — Post-session-2 cleanup addenda (no architectural reversals; corrections + one schema addition):
  • §3 Q8 addendum — Person provisioning scopes by (email, event_id), not (email, organisation_id). Aligns with Person::$organisationScopeColumn = 'event_id'.
  • §3 Q9 addendum — form_schemas.default_crowd_type_id (nullable ULID, no DB-level FK) replaces the silent CrowdType::oldest() heuristic. New RequiresDefaultCrowdType publish guard wired into EventRegistrationGuards. Runtime failsafe in PersonProvisioner::resolveCrowdTypeId().
  • Snapshot dual-key cleanup (separate from RFC §3): legacy binding (singular) snapshot key dropped; bindings (plural list) is the single source of truth in schema_snapshot.fields[*]. ARCH-BINDINGS.md §6.4 / §6.1 already specified the plural list — code converged.
  • Route model binding (separate from RFC §3): controller-level workaround $request->route('formSubmissionActionFailure') replaced with explicit Route::bind() in AppServiceProvider::boot() plus ->withoutScopedBindings() on org-scoped routes. Type-hinted parameters restored. RFC V3 (FK-chain tenant policy) unchanged.
• 2026-04-28 — v1.2 — Registry alignment with model columns (sessie 3a.5):
  • 3 renames (registry → model): person.phone_number → phone, company.email → contact_email, company.phone_number → contact_phone.
  • 5 removals (deferred to BACKLOG): person.dietary_preferences (FORM-BINDING-JSON-PATH); artist.email/stage_name/tech_rider/hospitality_rider plus the artist entity itself (ARTIST-ADV-BINDING-MODEL).
  • 1 new model column: companies.kvk_number (nullable, indexed).
  • BindingTypeRegistryConsistencyTest extended with a model-existence + column-existence assertion preventing future drift.
• 2026-05-07 — v1.3 — Architectural review (Claude Chat, post WS-7 closure). Five refinements; spine unchanged (pre-publish guards, strict service / log-and-swallow listener, two-transaction pattern, sync ApplyBindings, snapshot-isolation, single-identity-key per target_entity):
  • §Q1 — Listener-volgorde. SYNC chain reduced to one listener (ApplyBindingsOnFormSubmit); TriggerPersonIdentityMatchOnFormSubmit moves to QUEUED. Four additions: ApplyBindings writes identity_match_status='pending' as initial state; queued listener ends with Echo broadcast on submission.{id} private channel; queued-listener gating invariant (apply_status=COMPLETED) as first statement of every queued listener; sync-chain hard timeout (5s deadline wrapper) → FormBindingApplicatorTimeoutException.
  • §Q2 — TriggerPersonIdentityMatchOnFormSubmit refactor. Failsafe-pad ("no subject → pending" logged warning) replaced with explicit invariant + strict throw routed via form_submission_action_failures. Companion: RequiresIdentityKeyBinding('person', 'email') wires unconditionally for event_registration (drop the ConditionalRequirement(public_token !== null) wrapper). Companion: FormSubmissionResource.identity_match=null made an explicit contract for non-person purposes.
  • §Q3 — Strict-fail vs compatibility. Spine confirmed unchanged. Three failure-UX additions: GlitchTip alert rule on FormBindingApplicatorException for production public flows; custom exception hierarchy (FormBindingSchemaConfigException / FormBindingInfraException / FormBindingDataIntegrityException) + failure_response_code column on form_submissions + error_code in HTTP response body; "all-or-nothing per pass" gets explicit BACKLOG entry PARTIAL-BINDING-SUCCESS. Fourth addition: schema-drift detection as separate BACKLOG entry FORM-SCHEMA-DRIFT-DETECTION (not v1.0 scope).
  • Companion: ARCH-BINDINGS.md advances to v1.1 (twelve section edits per the v1.3 amendment companion table); BACKLOG.md adds PARTIAL-BINDING-SUCCESS and FORM-SCHEMA-DRIFT-DETECTION under Form Builder backlog. RFC-WS-6 v1.3, ARCH-BINDINGS v1.1, and the BACKLOG additions land in the same commit.
• 2026-05-08 — v1.3.1 — Pre-D1-implementation drift closure. (1) Updated apply_status enumerations throughout §3 to include the PARTIAL case (which exists in code per BindingPassResult::applyStatus() and was not anticipated by the v1.3 amendment author). (2) ARCH-BINDINGS §5.6 received a PARTIAL-handling clarification: gate treats PARTIAL identically to FAILED, deferring granular partial-success to BACKLOG PARTIAL-BINDING-SUCCESS. (3) ARCH-BINDINGS §7.1 status-columns table extended with apply_completed_at row + cross-reference to the D2 retry-service symmetry fix. No spine changes; no behaviour changes; documentation truth-in-naming. Companion: ARCH-BINDINGS.md advances to v1.2.
• 2026-05-08 — v1.3-delta closure — RFC v1.3.1 fully implemented in main. D1 (PR #10 c6f4d1b, 2026-05-08) delivered the data-layer prerequisites: failure_response_code column on form_submissions, abstract FormBindingApplicatorException hierarchy with 4 reason-coded subclasses (FormBindingSchemaConfigException, FormBindingInfraException, FormBindingApplicatorTimeoutException, FormBindingDataIntegrityException), IdentityMatchInvariantViolation sibling DomainException, FormBindingExceptionClassifier helper, FormSubmissionIdentityMatchResolved broadcast event class, FormFieldBindingMergeStrategy::validForTargetType matrix method, plus cast + factory state. D2 (PR #11 23a5696, 2026-05-08) wired the building blocks into the listener chain: ApplyBindingsOnFormSubmit writes initial identity_match_status='pending', uses the deadline wrapper, and consumes the classifier in its outer-transaction catch block; TriggerPersonIdentityMatchOnFormSubmit becomes queued with the gating-invariant first statement, the strict invariant throw, and broadcast dispatch; routes/channels.php introduces broadcasting infrastructure (NEW wiring) with submitter-only authorization (org-admin extension tracked as BACKLOG TECH-CHANNEL-AUTH-ORG-ADMIN); queued listeners gain the apply_status=COMPLETED first-statement gate; FormFailureRetryService::recordFailure consumes the classifier and writes apply_completed_at for symmetry with the listener; apply_deadline_seconds config key (default 5) added; six existing tests adapted to the v1.3 layout. Test counts: pre-D1 baseline 1551 → post-D2 1621 (+70). 0 Larastan errors. The remaining v1.3 add (Q3 v1.3 add 1 — GlitchTip alert rule on apply_status=failed AND form_schema.has_public_token=true) is an operational task, configured in the GlitchTip web UI on monitoring.hausdesign.nl outside the code lifecycle; runbook procedure documented in dev-docs/runbooks/observability-triage.md §7. Frontend Echo subscription for FormSubmissionIdentityMatchResolved is a separate frontend follow-up, out of WS-6 scope.