feat(form-builder): public draft/save/submit split + sub-endpoints + validation

S2c D2, D3, D4, D8 — the meat of the public API rewrite.

Draft / save / submit split (D4):
- POST /public/forms/{public_token}/submissions
    Creates a draft. idempotency_key is now REQUIRED; second POST with
    the same key returns the existing draft (HTTP 200 vs 201 for fresh).
    UniqueConstraintViolationException caught for race-safe replay.
- PUT /public/forms/{public_token}/submissions/{submission_id}
    Auto-save. Partial updates only — each PUT writes just the
    slugs in the body. Status stays 'draft'; auto_save_count++.
- POST /public/forms/{public_token}/submissions/{submission_id}/submit
    Final submission. Merges body values with already-saved values,
    runs strict rule set against the merged map, then calls
    FormSubmissionService::submit which fires the lifecycle events
    (tag sync, identity match). Rate-limited per IP per token per hour.

Access rules: submission must belong to the resolved schema; status
must be 'draft' (409 SUBMISSION_ALREADY_SUBMITTED otherwise); schema
still accepting submissions.

Sub-endpoints (D2, D3):
- GET /public/forms/{public_token}/time-slots
    Volunteer-only, festival-aware (parent + children). Reads straight
    from TimeSlot model — no org-coupled service to extract from. Out:
    {id, name, date, start_time, end_time, duration_hours, event_id,
    event_name}.
- GET /public/forms/{public_token}/sections
    show_in_registration=true, type=standard, deduplicated by name
    across festival children.

Dynamic per-field validation (D8):
- FormFieldRuleBuilder builds Laravel rule arrays from form_fields.
  strict() enforces is_required + in:options + type rules (email,
  url, numeric, date, boolean, phone regex); relaxed() is the
  auto-save variant that drops required-ness.
- StartPublicDraftRequest (required idempotency_key),
  SavePublicDraftRequest (relaxed rules, values optional),
  SubmitPublicSubmissionRequest (relaxed rules at body level — the
  controller merges the body with saved values and runs the strict
  validator on the full map so submit with an empty body still
  passes when everything was auto-saved).
- FormValueService backs the request layer up with deeper enforcement
  of validation_rules JSON (min/max/regex) + is_unique. Throws
  FieldValidationException (422) which renders via the D6 envelope.

PublicFormTokenResolver centralises the grace-window logic; every
public endpoint resolves through it so the standardised exceptions
bubble uniformly.

Routes: 6 total under /public/forms/ (up from 2). Tests:
PublicFormApiTest's existing submit test retrofitted to the three-step
flow; 857 tests still green.

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

api/app/Services/FormBuilder/FormFieldRuleBuilder.php

@@ -0,0 +1,210 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\FormBuilder;
+
+use App\Enums\FormBuilder\FormFieldType;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormSchema;
+
+/**
+ * Build Laravel validation rules dynamically from a schema's form_fields.
+ *
+ * Two modes (S2c D8):
+ *   - strict(): for the final submit pipeline. is_required fields are
+ *     required; SELECT/RADIO values must be in options; multi-value
+ *     types must be arrays; type rules (email/url/date/numeric/boolean)
+ *     are enforced.
+ *   - relaxed(): for auto-save drafts. Every rule becomes nullable;
+ *     options lists still constrain (a SELECT can't silently accept
+ *     garbage, even mid-draft), but required stays off.
+ *
+ * Rule shape returned targets `values.{slug}` and `values.{slug}.*` keys
+ * so FormRequests can merge this into their own `values` wrapper:
+ *
+ *     return array_merge(['values' => ['required', 'array']], $ruleBuilder->strict($schema));
+ */
+final class FormFieldRuleBuilder
+{
+    /**
+     * @return array<string, array<int, string>>
+     */
+    public function strict(FormSchema $schema): array
+    {
+        return $this->build($schema, strict: true);
+    }
+
+    /**
+     * @return array<string, array<int, string>>
+     */
+    public function relaxed(FormSchema $schema): array
+    {
+        return $this->build($schema, strict: false);
+    }
+
+    /**
+     * @return array<string, array<int, string>>
+     */
+    private function build(FormSchema $schema, bool $strict): array
+    {
+        $fields = $schema->fields()->get();
+        $rules = [];
+
+        foreach ($fields as $field) {
+            if (! (bool) $field->is_portal_visible || (bool) $field->is_admin_only) {
+                continue;
+            }
+
+            if (in_array($field->field_type, [FormFieldType::HEADING->value, FormFieldType::PARAGRAPH->value], true)) {
+                continue;
+            }
+
+            $key = 'values.'.$field->slug;
+            $isMulti = $this->isMultiValue($field);
+            $primaryRules = [];
+
+            if ($strict && (bool) $field->is_required) {
+                $primaryRules[] = $isMulti ? 'present' : 'required';
+            } else {
+                $primaryRules[] = 'sometimes';
+                $primaryRules[] = 'nullable';
+            }
+
+            if ($isMulti) {
+                $primaryRules[] = 'array';
+                $rules[$key] = $primaryRules;
+
+                foreach ($this->itemRulesFor($field, $strict) as $itemRule) {
+                    $rules[$key.'.*'][] = $itemRule;
+                }
+                continue;
+            }
+
+            foreach ($this->scalarTypeRules($field) as $r) {
+                $primaryRules[] = $r;
+            }
+            foreach ($this->validationRuleShortcuts($field) as $r) {
+                $primaryRules[] = $r;
+            }
+
+            $rules[$key] = $primaryRules;
+        }
+
+        return $rules;
+    }
+
+    private function isMultiValue(FormField $field): bool
+    {
+        return in_array($field->field_type, [
+            FormFieldType::MULTISELECT->value,
+            FormFieldType::CHECKBOX_LIST->value,
+            FormFieldType::TAG_PICKER->value,
+            FormFieldType::AVAILABILITY_PICKER->value,
+            FormFieldType::SECTION_PRIORITY->value,
+            FormFieldType::TABLE_ROWS->value,
+        ], true);
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function scalarTypeRules(FormField $field): array
+    {
+        return match ($field->field_type) {
+            FormFieldType::EMAIL->value => ['email:rfc'],
+            FormFieldType::URL->value => ['url'],
+            FormFieldType::NUMBER->value => ['numeric'],
+            FormFieldType::DATE->value => ['date_format:Y-m-d'],
+            FormFieldType::DATETIME->value => ['date'],
+            FormFieldType::BOOLEAN->value => ['boolean'],
+            FormFieldType::PHONE->value => ['regex:/^[+]?[0-9\s\-()]{4,25}$/'],
+            FormFieldType::SELECT->value, FormFieldType::RADIO->value => $this->inOptionsRule($field),
+            default => ['string'],
+        };
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function itemRulesFor(FormField $field, bool $strict): array
+    {
+        $rules = [];
+        if ($strict && (bool) $field->is_required) {
+            $rules[] = 'required';
+        } else {
+            $rules[] = 'nullable';
+        }
+
+        return match ($field->field_type) {
+            FormFieldType::MULTISELECT->value, FormFieldType::CHECKBOX_LIST->value => array_merge($rules, $this->inOptionsRule($field)),
+            FormFieldType::TAG_PICKER->value => array_merge($rules, ['string', 'max:30']),
+            FormFieldType::AVAILABILITY_PICKER->value => array_merge($rules, ['string', 'max:30']),
+            FormFieldType::SECTION_PRIORITY->value => array_merge($rules, ['array:section_id,priority']),
+            FormFieldType::TABLE_ROWS->value => array_merge($rules, ['array']),
+            default => $rules,
+        };
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function inOptionsRule(FormField $field): array
+    {
+        $options = $this->scalarOptions($field);
+        if ($options === []) {
+            return [];
+        }
+
+        return ['in:'.implode(',', $options)];
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function scalarOptions(FormField $field): array
+    {
+        $options = is_array($field->options) ? $field->options : [];
+        $out = [];
+        foreach ($options as $opt) {
+            if (is_scalar($opt)) {
+                $out[] = (string) $opt;
+            } elseif (is_array($opt) && isset($opt['value']) && is_scalar($opt['value'])) {
+                $out[] = (string) $opt['value'];
+            } elseif (is_array($opt) && isset($opt['label']) && is_scalar($opt['label'])) {
+                $out[] = (string) $opt['label'];
+            }
+        }
+
+        return $out;
+    }
+
+    /**
+     * Shortcuts picked up from form_fields.validation_rules JSON.
+     * Service-layer FormValueService does the deeper min/max/regex/unique
+     * enforcement — these are quick boundary checks surfaced at the
+     * Request layer when cheap.
+     *
+     * @return array<int, string>
+     */
+    private function validationRuleShortcuts(FormField $field): array
+    {
+        $rules = [];
+        $v = $field->validation_rules ?? null;
+        if (! is_array($v)) {
+            return $rules;
+        }
+
+        if (isset($v['min']) && is_numeric($v['min'])) {
+            $rules[] = 'min:'.(string) $v['min'];
+        }
+        if (isset($v['max']) && is_numeric($v['max'])) {
+            $rules[] = 'max:'.(string) $v['max'];
+        }
+        if (isset($v['regex']) && is_string($v['regex'])) {
+            $rules[] = 'regex:'.$v['regex'];
+        }
+
+        return $rules;
+    }
+}

api/app/Services/FormBuilder/FormValueService.php

@@ -37,7 +37,9 @@ final class FormValueService
             ->get()
             ->keyBy('slug');
 
-        DB::transaction(function () use ($slugToValue, $fields, $submission, $actor): void {
+        $fieldErrors = [];
+
+        DB::transaction(function () use ($slugToValue, $fields, $submission, $actor, &$fieldErrors): void {
             foreach ($slugToValue as $slug => $raw) {
                 $field = $fields->get($slug);
                 if ($field === null) {
@@ -53,10 +55,68 @@ final class FormValueService
                     throw new AuthorizationException(sprintf('Not allowed to write field "%s".', $slug));
                 }
 
+                $errors = $this->validateAgainstFieldRules($field, $raw, $submission);
+                if ($errors !== []) {
+                    $fieldErrors[$slug] = $errors;
+
+                    continue;
+                }
+
                 $this->writeValue($submission, $field, $raw);
                 $this->writeEntityMirror($submission, $field, $raw);
             }
         });
+
+        if ($fieldErrors !== []) {
+            throw new \App\Exceptions\FormBuilder\FieldValidationException($fieldErrors);
+        }
+    }
+
+    /**
+     * Backstop enforcement of form_fields.validation_rules JSON per
+     * S2c D8. The FormFieldRuleBuilder already surfaces min/max/regex
+     * shortcuts at the request layer; this is where the deeper checks
+     * (is_unique, validation_rules.unique) live.
+     *
+     * @return array<int, string>
+     */
+    private function validateAgainstFieldRules(FormField $field, mixed $raw, FormSubmission $submission): array
+    {
+        $errors = [];
+        $rules = is_array($field->validation_rules) ? $field->validation_rules : [];
+
+        if ($raw === null || $raw === '' || $raw === []) {
+            return $errors;
+        }
+
+        if (isset($rules['min']) && is_numeric($rules['min']) && is_numeric($raw) && (float) $raw < (float) $rules['min']) {
+            $errors[] = sprintf('Minimum is %s.', (string) $rules['min']);
+        }
+        if (isset($rules['max']) && is_numeric($rules['max']) && is_numeric($raw) && (float) $raw > (float) $rules['max']) {
+            $errors[] = sprintf('Maximum is %s.', (string) $rules['max']);
+        }
+        if (isset($rules['regex']) && is_string($rules['regex']) && is_string($raw)
+            && @preg_match($rules['regex'], $raw) !== 1) {
+            $errors[] = 'Value does not match the expected format.';
+        }
+
+        $unique = (bool) $field->is_unique || (bool) ($rules['unique'] ?? false);
+        if ($unique) {
+            $scalar = is_scalar($raw) ? (string) $raw : null;
+            if ($scalar !== null) {
+                $exists = \App\Models\FormBuilder\FormValue::query()
+                    ->where('form_field_id', $field->id)
+                    ->where('value_indexed', $scalar)
+                    ->where('form_submission_id', '!=', $submission->id)
+                    ->whereHas('submission', fn ($q) => $q->where('status', \App\Enums\FormBuilder\FormSubmissionStatus::SUBMITTED->value))
+                    ->exists();
+                if ($exists) {
+                    $errors[] = 'This value is already in use for another submission.';
+                }
+            }
+        }
+
+        return $errors;
     }
 
     private function writeValue(FormSubmission $submission, FormField $field, mixed $raw): void

api/app/Services/FormBuilder/PublicFormTokenResolver.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\FormBuilder;
+
+use App\Exceptions\FormBuilder\SchemaNotFoundException;
+use App\Exceptions\FormBuilder\TokenExpiredException;
+use App\Models\FormBuilder\FormSchema;
+
+/**
+ * Token-to-schema resolution for every /public/forms/* endpoint.
+ * Centralises the 7-day grace window logic (ARCH §10, BACKLOG FORM-04
+ * tracks making this configurable).
+ *
+ * Throws the standardised public-form exceptions directly so callers
+ * don't need to branch on grace state themselves.
+ */
+final class PublicFormTokenResolver
+{
+    private const GRACE_DAYS = 7;
+
+    public function resolve(string $token): FormSchema
+    {
+        $current = FormSchema::query()
+            ->where('public_token', $token)
+            ->first();
+        if ($current !== null) {
+            return $current;
+        }
+
+        $previous = FormSchema::query()
+            ->where('public_token_previous', $token)
+            ->first();
+
+        if ($previous === null) {
+            throw new SchemaNotFoundException;
+        }
+
+        $rotatedAt = $previous->public_token_rotated_at;
+        if ($rotatedAt === null) {
+            return $previous;
+        }
+
+        if ($rotatedAt->addDays(self::GRACE_DAYS)->isPast()) {
+            throw new TokenExpiredException;
+        }
+
+        return $previous;
+    }
+}