crewli/dev-docs/ARCH-BINDINGS.md

ARCH-BINDINGS.md — Form Builder Binding Pipeline

Status

• v0.1 (skeleton) — 2026-04-25
• Owner: Bert
• Authoritative for the binding pipeline architecture, complementing ARCH-FORM-BUILDER.md §17 and §31.
• Decisions originate from RFC-WS-6.md.

1. Scope

The binding pipeline turns a submitted form (form_submissions) into durable writes against domain entities — Person, Artist, Company, User — via per-field bindings configured in form_field_bindings (WS-5a).

This document describes the end-to-end flow from FormSubmissionSubmitted event to the post-pipeline state where the domain has been updated, identity-match has been triggered, queued listeners (tag sync, shifts, webhooks, mail) have fired, and any binding-level failures have been recorded as form_submission_action_failures rows.

The library is a template-source, not a live link. When a form_field is created from a FormFieldLibrary entry with bindings, the library's bindings are copied into form_field_bindings rows with owner_type = 'form_field'. Library updates do not propagate to existing field instances (RFC §3 Q11). Future re-sync admin action tracked in BACKLOG: FORM-LIBRARY-RESYNC.

2. Schema

2.1 form_field_bindings (WS-5a)

Polymorphic owner (owner_type ∈ {form_field, form_field_library}, owner_id ULID), target_entity × target_attribute columns, merge_strategy (Overwrite/Append/Replace/FirstWriteWins), trust_level (0-100, default 50), is_identity_key bool. UNIQUE on (owner_type, owner_id, target_entity, target_attribute). See SCHEMA.md §3.5.12.

2.2 form_submissions.apply_status / apply_completed_at (WS-6)

Two new columns added in 2026_04_25_140000_extend_form_submissions_with_apply_status:

• apply_status — string(20) nullable, no default. Values: pending|completed|partial|failed. Drives admin "open work" filtering. NULL legacy rows are excluded from open-work views by design (RFC O1).
• apply_completed_at — timestamp nullable, set when applicator finishes (success or fail).

Indexed on (form_schema_id, apply_status) and (organisation_id, apply_status) for dashboard queries.

2.3 form_submission_action_failures (WS-6)

Audit table for binding-pipeline failures (RFC §3 Q5). One row per listener invocation that failed, with retry / resolve / dismiss state fields. No organisation_id column — tenant scope flows via form_submission_id → form_submissions.organisation_id. Cascade-delete through the parent submission. Resolve and Dismiss are mutually exclusive workflows (RFC V2): a failure has at most one of resolved_at or dismissed_at.

Full DDL in SCHEMA.md §3.5.12.

3. Value objects and enums

App\FormBuilder\Bindings\ (final readonly classes):

• ResolvedBinding — output of session 2's BindingConflictResolver. One winning binding per (target_entity, target_attribute) group. Carries valueIsExplicit to distinguish "user explicitly cleared" from "field skipped by conditional logic" (RFC §3 Q7).
• BindingApplicationResult — result of applying one resolved binding. Sealed via succeeded() / failed() named constructors so consumers cannot synthesise impossible states.
• BindingPassResult — aggregate result of one applicator pass. applyStatus() maps to ApplyStatus enum per RFC §3 Q4 rules: empty applications → COMPLETED, all OK → COMPLETED, all failed → FAILED, mixed → PARTIAL.
• BindingTargetMeta — single config row from config/form_builder/binding_targets.php.

Enums in App\Enums\FormBuilder\:

• ApplyStatus (RFC §3 Q4) — PENDING|COMPLETED|PARTIAL|FAILED. Helpers: isTerminal(), isOpen(), label().
• DismissalReasonType (RFC §4 V2) — six cases. manually_resolved is intentionally absent: Resolve and Dismiss are different workflows.
• BindingTargetType (RFC §4 V1) — SCALAR|COLLECTION|RELATION. Storage shape only; PHP type and identity-key eligibility live on BindingTargetMeta.
• FormFieldBindingMergeStrategy (existing, WS-5a) — extended in WS-6 with nullWinnerBehaviour() and isValidForScalarTargets().

4. BindingTypeRegistry

App\FormBuilder\Bindings\BindingTypeRegistry is the single source of truth for the storage shape of binding-target attributes. Config-driven (config/form_builder/binding_targets.php), singleton-bound in AppServiceProvider.

Public surface:

• resolve(entity, attribute): BindingTargetMeta
• isKnown(entity, attribute): bool
• isIdentityKeyEligible(entity, attribute): bool
• entities(): list<string>
• attributesFor(entity): list<string>
• validateAppendStrategy(entity, attribute, strategy) — throws InvalidBindingTargetException when strategy=Append is paired with a non-COLLECTION target.

The registry is not name-suffix matching (e.g. "ends with _tags"). Convention-not-contract is rejected because it silently misclassifies attributes that don't follow the convention or accidentally match it.

5. PublishGuard framework

Per-purpose schema validation. FormSchemaService::publish() calls, in order:

1. assertRequiredBindingsPresent() (existing) — every required binding path on the purpose's required_bindings list is bound. Throws PurposeRequirementsNotMetException.
2. assertPublishGuardsSatisfied() (new) — every guard returned by the purpose's PurposeGuardProvider evaluates to passed. Throws PublishGuardViolationException carrying ALL violations sorted lexicographically by code().

Guard catalog

Class	code()	Universal?
RequiresIdentityKeyBinding(entity, attribute)	requires_identity_key_binding:{entity}:{attribute}	no
MaxOneIdentityKeyPerTargetEntity	max_one_identity_key_per_target_entity	yes
RequiresFieldType(type, minCount)	requires_field_type:{type}	no
SchemaHasLinkedEvent	schema_has_linked_event	sub-guard
TagCategoriesConfiguredOnAllPickers	tag_categories_configured_on_all_pickers	sub-guard
IdentityKeyBindingsOnlyInFirstSection	identity_key_bindings_only_in_first_section	yes
AppendStrategyRequiresCollectionTarget	append_strategy_requires_collection_target	yes
NoAmbiguousTrustLevels	no_ambiguous_trust_levels	yes
ConditionalRequirement(predicate, sub, code)	conditional:{caller-supplied}	composer

Per-purpose providers

Purpose	Provider	Purpose-specific guards
event_registration	EventRegistrationGuards	RequiresIdentityKeyBinding(person, email), RequiresFieldType(EMAIL,1), Conditional(AVAILABILITY_PICKER → SchemaHasLinkedEvent), Conditional(TAG_PICKER → TagCategoriesConfiguredOnAllPickers)
artist_advance	ArtistAdvanceGuards	(universal only — artist resolved via portal token)
supplier_intake	SupplierIntakeGuards	(universal only — company via production_request)
post_event_evaluation	PostEventEvaluationGuards	(universal only — person via auth)
incident_report	IncidentReportGuards	(universal only — anonymous-allowed)
signature_contract	SignatureContractGuards	(universal only — user via auth)
user_profile	UserProfileGuards	(universal only — user via auth)

Universal guards (MaxOneIdentityKeyPerTargetEntity, AppendStrategyRequiresCollectionTarget, NoAmbiguousTrustLevels, IdentityKeyBindingsOnlyInFirstSection) wire into every purpose. The section guard is a cheap no-op when section_level_submit=false, but remains active at publish time for schemas that flip it on later.

i18n message keys live in api/lang/nl/form_builder_publish_guards.php. Dutch only for v1.

6. Apply pipeline

6.1 Snapshot vs. live (RFC Q6)

Populated in session 2 — see RFC-WS-6.md §3 Q6.

6.2 Conflict resolution (RFC Q7)

Populated in session 2 — see RFC-WS-6.md §3 Q7.

6.3 Apply algorithm and merge-strategy null matrix (RFC V1, Q7)

Populated in session 2 — see RFC-WS-6.md §4 V1 + §3 Q7.

6.4 Person provisioning (RFC Q8)

Populated in session 2 — see RFC-WS-6.md §3 Q8.

6.5 Per-purpose subject resolution (RFC Q9)

Populated in session 2 — see RFC-WS-6.md §3 Q9.

6.6 Section-level apply stub (RFC Q10)

Populated in session 2 — see RFC-WS-6.md §3 Q10.

6.7 Activity log granularity (RFC Q12)

Populated in session 2 — see RFC-WS-6.md §3 Q12.

7. Failures and retry

7.1 Two-transaction pattern (RFC Q4)

Populated in session 2 — see RFC-WS-6.md §3 Q4.

7.2 Retry, resolve, dismiss flows (RFC V2)

Populated in session 2 — see RFC-WS-6.md §4 V2.

8. Multi-tenancy and security

8.1 FK-chain tenant resolution (RFC V3)

Populated in session 2 — see RFC-WS-6.md §4 V3.

8.2 IDOR class tests

Populated in session 3 — see RFC-WS-6.md §4 V3.

9. Listener chain

Populated in session 2 — see RFC-WS-6.md §3 Q1, Q2, Q3.

10. Out of scope (v1)

• Composite identity-key resolution (single-key only) — BACKLOG: FORM-BINDING-COMPOSITE-IDENTITY
• Library-binding runtime cascade — BACKLOG: FORM-LIBRARY-RESYNC
• Append on scalar targets — collection-only by design (RFC V1)
• Active section-level apply — stub only, activated when ARTIST_ADVANCE feature work begins (BACKLOG: ARTIST-ADV-SECTION-APPLY)
• Daily failure digest mailable — depends on notification framework
• Wall-clock concurrent load testing — BACKLOG: LOAD-TEST-FOUNDATION

11. Related docs

• RFC-WS-6.md — design decisions
• ARCH-FORM-BUILDER.md §17, §31
• ARCH-CONSOLIDATION-2026-04.md §6.1, §6.2
• SCHEMA.md §3.5.12