feat(form-builder): wire PurposeGuardProvider per purpose (WS-6)

Adds PurposeGuardProvider as a parallel interface to PurposeDefinition
(value object stays untouched). Seven concrete providers, one per v1.0
purpose, each declaring its publish-guard list. Registry resolves and
caches providers via guards_class config key.

Universal guards (MaxOneIdentityKeyPerTargetEntity,
AppendStrategyRequiresCollectionTarget, NoAmbiguousTrustLevels,
IdentityKeyBindingsOnlyInFirstSection) wire into every purpose. The
section guard is a cheap no-op when section_level_submit=false.

ArtistAdvanceGuards omits RequiresIdentityKeyBinding because the
artist subject is resolved via portal token, not form data. Same
reasoning for supplier_intake (production_request) and the auth-based
purposes.

Includes a cross-cutting BindingTypeRegistryConsistencyTest that
verifies tasks 5/7/8 do not contradict each other (registry ↔ guards ↔
purpose required_bindings).

Refs: RFC-WS-6.md §3 (Q9, Q13)

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

api/app/FormBuilder/Purposes/Guards/ArtistAdvanceGuards.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Purposes\Guards;
+
+use App\FormBuilder\Bindings\BindingTypeRegistry;
+use App\FormBuilder\Publishing\AppendStrategyRequiresCollectionTarget;
+use App\FormBuilder\Publishing\IdentityKeyBindingsOnlyInFirstSection;
+use App\FormBuilder\Publishing\MaxOneIdentityKeyPerTargetEntity;
+use App\FormBuilder\Publishing\NoAmbiguousTrustLevels;
+use App\FormBuilder\Purposes\PurposeGuardProvider;
+
+final readonly class ArtistAdvanceGuards implements PurposeGuardProvider
+{
+    public function __construct(private BindingTypeRegistry $registry) {}
+
+    public function publishGuards(): array
+    {
+        return [
+            new MaxOneIdentityKeyPerTargetEntity(),
+            // Active for artist_advance — schemas may use section_level_submit
+            // (Guest List / Contacts / Production sections).
+            new IdentityKeyBindingsOnlyInFirstSection(),
+            new AppendStrategyRequiresCollectionTarget($this->registry),
+            new NoAmbiguousTrustLevels(),
+            // No RequiresIdentityKeyBinding — artist resolved via portal token.
+        ];
+    }
+}

api/app/FormBuilder/Purposes/Guards/EventRegistrationGuards.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Purposes\Guards;
+
+use App\Enums\FormBuilder\FormFieldType;
+use App\FormBuilder\Bindings\BindingTypeRegistry;
+use App\FormBuilder\Publishing\AppendStrategyRequiresCollectionTarget;
+use App\FormBuilder\Publishing\ConditionalRequirement;
+use App\FormBuilder\Publishing\IdentityKeyBindingsOnlyInFirstSection;
+use App\FormBuilder\Publishing\MaxOneIdentityKeyPerTargetEntity;
+use App\FormBuilder\Publishing\NoAmbiguousTrustLevels;
+use App\FormBuilder\Publishing\RequiresFieldType;
+use App\FormBuilder\Publishing\RequiresIdentityKeyBinding;
+use App\FormBuilder\Publishing\SchemaHasLinkedEvent;
+use App\FormBuilder\Publishing\TagCategoriesConfiguredOnAllPickers;
+use App\FormBuilder\Purposes\PurposeGuardProvider;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormSchema;
+
+final readonly class EventRegistrationGuards implements PurposeGuardProvider
+{
+    public function __construct(private BindingTypeRegistry $registry) {}
+
+    public function publishGuards(): array
+    {
+        return [
+            new RequiresIdentityKeyBinding('person', 'email'),
+            new MaxOneIdentityKeyPerTargetEntity(),
+            new RequiresFieldType(FormFieldType::EMAIL, 1),
+            new ConditionalRequirement(
+                predicate: $this->fieldTypePresent(FormFieldType::AVAILABILITY_PICKER),
+                subGuard: new SchemaHasLinkedEvent(),
+                code: 'availability_picker_requires_event',
+            ),
+            new ConditionalRequirement(
+                predicate: $this->fieldTypePresent(FormFieldType::TAG_PICKER),
+                subGuard: new TagCategoriesConfiguredOnAllPickers(),
+                code: 'tag_picker_requires_tag_categories',
+            ),
+            new AppendStrategyRequiresCollectionTarget($this->registry),
+            new NoAmbiguousTrustLevels(),
+            new IdentityKeyBindingsOnlyInFirstSection(),
+        ];
+    }
+
+    /**
+     * @return \Closure(FormSchema): bool
+     */
+    private function fieldTypePresent(FormFieldType $type): \Closure
+    {
+        $value = $type->value;
+
+        return static function (FormSchema $schema) use ($value): bool {
+            /** @var FormField $field */
+            foreach ($schema->fields as $field) {
+                if ($field->field_type === $value) {
+                    return true;
+                }
+            }
+
+            return false;
+        };
+    }
+}

api/app/FormBuilder/Purposes/Guards/IncidentReportGuards.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Purposes\Guards;
+
+use App\FormBuilder\Bindings\BindingTypeRegistry;
+use App\FormBuilder\Publishing\AppendStrategyRequiresCollectionTarget;
+use App\FormBuilder\Publishing\IdentityKeyBindingsOnlyInFirstSection;
+use App\FormBuilder\Publishing\MaxOneIdentityKeyPerTargetEntity;
+use App\FormBuilder\Publishing\NoAmbiguousTrustLevels;
+use App\FormBuilder\Purposes\PurposeGuardProvider;
+
+final readonly class IncidentReportGuards implements PurposeGuardProvider
+{
+    public function __construct(private BindingTypeRegistry $registry) {}
+
+    public function publishGuards(): array
+    {
+        return [
+            new MaxOneIdentityKeyPerTargetEntity(),
+            new AppendStrategyRequiresCollectionTarget($this->registry),
+            new NoAmbiguousTrustLevels(),
+            new IdentityKeyBindingsOnlyInFirstSection(),
+            // Anonymous-allowed — no identity key required.
+        ];
+    }
+}

api/app/FormBuilder/Purposes/Guards/PostEventEvaluationGuards.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Purposes\Guards;
+
+use App\FormBuilder\Bindings\BindingTypeRegistry;
+use App\FormBuilder\Publishing\AppendStrategyRequiresCollectionTarget;
+use App\FormBuilder\Publishing\IdentityKeyBindingsOnlyInFirstSection;
+use App\FormBuilder\Publishing\MaxOneIdentityKeyPerTargetEntity;
+use App\FormBuilder\Publishing\NoAmbiguousTrustLevels;
+use App\FormBuilder\Purposes\PurposeGuardProvider;
+
+final readonly class PostEventEvaluationGuards implements PurposeGuardProvider
+{
+    public function __construct(private BindingTypeRegistry $registry) {}
+
+    public function publishGuards(): array
+    {
+        return [
+            new MaxOneIdentityKeyPerTargetEntity(),
+            new AppendStrategyRequiresCollectionTarget($this->registry),
+            new NoAmbiguousTrustLevels(),
+            new IdentityKeyBindingsOnlyInFirstSection(),
+            // Person resolved via auth.
+        ];
+    }
+}

api/app/FormBuilder/Purposes/Guards/SignatureContractGuards.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Purposes\Guards;
+
+use App\FormBuilder\Bindings\BindingTypeRegistry;
+use App\FormBuilder\Publishing\AppendStrategyRequiresCollectionTarget;
+use App\FormBuilder\Publishing\IdentityKeyBindingsOnlyInFirstSection;
+use App\FormBuilder\Publishing\MaxOneIdentityKeyPerTargetEntity;
+use App\FormBuilder\Publishing\NoAmbiguousTrustLevels;
+use App\FormBuilder\Purposes\PurposeGuardProvider;
+
+final readonly class SignatureContractGuards implements PurposeGuardProvider
+{
+    public function __construct(private BindingTypeRegistry $registry) {}
+
+    public function publishGuards(): array
+    {
+        return [
+            new MaxOneIdentityKeyPerTargetEntity(),
+            new AppendStrategyRequiresCollectionTarget($this->registry),
+            new NoAmbiguousTrustLevels(),
+            new IdentityKeyBindingsOnlyInFirstSection(),
+            // User resolved via auth.
+        ];
+    }
+}

api/app/FormBuilder/Purposes/Guards/SupplierIntakeGuards.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Purposes\Guards;
+
+use App\FormBuilder\Bindings\BindingTypeRegistry;
+use App\FormBuilder\Publishing\AppendStrategyRequiresCollectionTarget;
+use App\FormBuilder\Publishing\IdentityKeyBindingsOnlyInFirstSection;
+use App\FormBuilder\Publishing\MaxOneIdentityKeyPerTargetEntity;
+use App\FormBuilder\Publishing\NoAmbiguousTrustLevels;
+use App\FormBuilder\Purposes\PurposeGuardProvider;
+
+final readonly class SupplierIntakeGuards implements PurposeGuardProvider
+{
+    public function __construct(private BindingTypeRegistry $registry) {}
+
+    public function publishGuards(): array
+    {
+        return [
+            new MaxOneIdentityKeyPerTargetEntity(),
+            new AppendStrategyRequiresCollectionTarget($this->registry),
+            new NoAmbiguousTrustLevels(),
+            new IdentityKeyBindingsOnlyInFirstSection(),
+            // No RequiresIdentityKeyBinding — company resolved via production_request.
+        ];
+    }
+}

api/app/FormBuilder/Purposes/Guards/UserProfileGuards.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Purposes\Guards;
+
+use App\FormBuilder\Bindings\BindingTypeRegistry;
+use App\FormBuilder\Publishing\AppendStrategyRequiresCollectionTarget;
+use App\FormBuilder\Publishing\IdentityKeyBindingsOnlyInFirstSection;
+use App\FormBuilder\Publishing\MaxOneIdentityKeyPerTargetEntity;
+use App\FormBuilder\Publishing\NoAmbiguousTrustLevels;
+use App\FormBuilder\Purposes\PurposeGuardProvider;
+
+final readonly class UserProfileGuards implements PurposeGuardProvider
+{
+    public function __construct(private BindingTypeRegistry $registry) {}
+
+    public function publishGuards(): array
+    {
+        return [
+            new MaxOneIdentityKeyPerTargetEntity(),
+            new AppendStrategyRequiresCollectionTarget($this->registry),
+            new NoAmbiguousTrustLevels(),
+            new IdentityKeyBindingsOnlyInFirstSection(),
+            // User resolved via auth.
+        ];
+    }
+}

api/app/FormBuilder/Purposes/PurposeGuardProvider.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Purposes;
+
+use App\FormBuilder\Publishing\PublishGuard;
+
+/**
+ * RFC-WS-6 §3 (Q13) — parallel interface to PurposeDefinition.
+ *
+ * The value object stays untouched (it's a frozen contract); guards
+ * live here so a new purpose can be added by composing two artifacts:
+ *   1. a PurposeDefinition entry in config/form_builder/purposes.php
+ *   2. a class implementing PurposeGuardProvider
+ */
+interface PurposeGuardProvider
+{
+    /** @return list<PublishGuard> */
+    public function publishGuards(): array;
+}

api/app/FormBuilder/Purposes/PurposeRegistry.php

@@ -13,6 +13,12 @@ final class PurposeRegistry
     /** @var array<string, PurposeDefinition>|null */
     private ?array $cache = null;
 
+    /** @var array<string, class-string<PurposeGuardProvider>>|null */
+    private ?array $guardClassCache = null;
+
+    /** @var array<string, PurposeGuardProvider> */
+    private array $guardProviderCache = [];
+
     public function __construct(private readonly ConfigRepository $config) {}
 
     /** @return array<string, PurposeDefinition> keyed by slug */
@@ -26,6 +32,7 @@ final class PurposeRegistry
         $raw = (array) $this->config->get('form_builder.purposes', []);
 
         $definitions = [];
+        $guardClasses = [];
         foreach ($raw as $slug => $attrs) {
             $mode = $attrs['default_submission_mode'] ?? null;
             if (! $mode instanceof FormSubmissionMode) {
@@ -34,6 +41,13 @@ final class PurposeRegistry
                 );
             }
 
+            $guardsClass = $attrs['guards_class'] ?? null;
+            if (! is_string($guardsClass) || ! is_subclass_of($guardsClass, PurposeGuardProvider::class)) {
+                throw new \InvalidArgumentException(
+                    "Purpose '{$slug}' has invalid guards_class; expected class-string implementing PurposeGuardProvider."
+                );
+            }
+
             $definitions[(string) $slug] = new PurposeDefinition(
                 slug: (string) $slug,
                 label: (string) ($attrs['label'] ?? ''),
@@ -42,11 +56,34 @@ final class PurposeRegistry
                 allowsPublicAccess: (bool) ($attrs['allows_public_access'] ?? false),
                 requiredBindings: array_values((array) ($attrs['required_bindings'] ?? [])),
             );
+            $guardClasses[(string) $slug] = $guardsClass;
         }
 
+        $this->guardClassCache = $guardClasses;
+
         return $this->cache = $definitions;
     }
 
+    public function guardProviderFor(string $slug): PurposeGuardProvider
+    {
+        if (! $this->has($slug)) {
+            throw Exceptions\PurposeNotFoundException::forSlug($slug);
+        }
+
+        if (isset($this->guardProviderCache[$slug])) {
+            return $this->guardProviderCache[$slug];
+        }
+
+        /** @var array<string, class-string<PurposeGuardProvider>> $classes */
+        $classes = $this->guardClassCache ?? [];
+        $class = $classes[$slug];
+
+        /** @var PurposeGuardProvider $instance */
+        $instance = resolve($class);
+
+        return $this->guardProviderCache[$slug] = $instance;
+    }
+
     public function get(string $slug): PurposeDefinition
     {
         $all = $this->all();