feat(form-builder): form_field_conditional_logic_{groups,conditions} tables + OrganisationScope cap raise to 5

WS-5c commit 1 of 4 — relational infrastructure for the conditional-
logic tree that replaces form_fields.conditional_logic JSON (ARCH-
FORM-BUILDER §8; addendum Q3 WS-5c).

Tables: groups (nesting via parent_group_id) + conditions (leaves,
value JSON nullable for empty/not_empty). Simple FK to form_fields —
addendum Q3 explicitly excludes form_field_library from conditional_
logic scope, so no polymorphic morph here.

OrganisationScope cap raised 3 → 5 hops. The conditions chain is
4 hops (condition → group → field → schema → organisation_id column)
and the new cap gives headroom for future deeper trees without
denormalising form_field_id onto conditions.

Cascade observer (FormFieldChildTablesCascadeObserver) extended to
physically delete the new groups table on FormField delete (hard or
soft). Conditions cascade automatically via the group_id FK on the
groups table.

Factories: FormFieldConditionalLogicGroupFactory, FormFieldConditional
LogicConditionFactory, and FormFieldFactory::withConditionalLogic($tree)
for concise test fixtures.

Tests: 16 new under tests/Feature/FormBuilder/ConditionalLogic/
(relation, scope, cascade, enum catalogue). 3 new scope-cap tests in
ScopeLeakageTest verify 4/5-hop chains pass and 6-hop throws. Hardcoded
rollback step counts in WS-5a/b migration tests bumped for the 2 new
WS-5c migrations. Baseline 1104 → 1122 green (2988 → 3032 assertions).

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

api/app/Enums/FormBuilder/FormFieldConditionalLogicConditionOperator.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\FormBuilder;
+
+/**
+ * Comparison operator catalogue for relational conditional-logic leaves
+ * (ARCH-FORM-BUILDER §8, Phase A seed-scan confirmed catalogue parity
+ * with the frontend evaluator in
+ * `packages/form-schema/src/composables/useConditionalLogic.ts`).
+ *
+ * `Empty` / `NotEmpty` do not read the `value` column — the DB stores
+ * null for those rows. The service layer enforces this contract.
+ */
+enum FormFieldConditionalLogicConditionOperator: string
+{
+    case Equals = 'equals';
+    case NotEquals = 'not_equals';
+    case Contains = 'contains';
+    case NotContains = 'not_contains';
+    case In = 'in';
+    case NotIn = 'not_in';
+    case GreaterThan = 'greater_than';
+    case LessThan = 'less_than';
+    case Empty = 'empty';
+    case NotEmpty = 'not_empty';
+
+    /**
+     * Operators that do NOT consume `value`. Used by the service-layer
+     * shape validator and by the backfill migration's null-coercion.
+     *
+     * @return array<int, self>
+     */
+    public static function valuelessCases(): array
+    {
+        return [self::Empty, self::NotEmpty];
+    }
+
+    public function isValueless(): bool
+    {
+        return in_array($this, self::valuelessCases(), true);
+    }
+}

api/app/Enums/FormBuilder/FormFieldConditionalLogicGroupOperator.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\FormBuilder;
+
+/**
+ * Boolean group operator for relational conditional logic
+ * (ARCH-FORM-BUILDER §8). `All` ≡ AND, `Any` ≡ OR. Groups nest
+ * arbitrarily; Phase A seed-scan observed nesting depth ≤ 2 in the
+ * wild, well inside the OrganisationScope FK-chain cap.
+ */
+enum FormFieldConditionalLogicGroupOperator: string
+{
+    case All = 'all';
+    case Any = 'any';
+}

api/app/Exceptions/TenantScopeResolutionException.php

@@ -8,10 +8,10 @@ use RuntimeException;
 
 /**
  * Raised when OrganisationScope's FK-chain resolver walks past its max
- * hop limit (3 hops) without reaching a column-based strategy, or when
- * a chain's intermediate model returns an invalid tenantScopeStrategy()
- * shape. Indicates a misconfigured model — fail loud rather than silently
- * leak queries across tenants.
+ * hop limit (5 hops — raised from 3 in WS-5c) without reaching a
+ * column-based strategy, or when a chain's intermediate model returns
+ * an invalid tenantScopeStrategy() shape. Indicates a misconfigured
+ * model — fail loud rather than silently leak queries across tenants.
  */
 final class TenantScopeResolutionException extends RuntimeException
 {

api/app/Models/FormBuilder/FormField.php

@@ -119,6 +119,23 @@ final class FormField extends Model
         return $this->morphMany(FormFieldConfig::class, 'owner');
     }
 
+    public function conditionalLogicGroups(): HasMany
+    {
+        return $this->hasMany(FormFieldConditionalLogicGroup::class, 'form_field_id');
+    }
+
+    /**
+     * The tree root: the group with `parent_group_id IS NULL`. Fields
+     * without any conditional logic return null. Only one root is
+     * supported per field — enforced by the service layer's `replaceLogic`.
+     */
+    public function rootConditionalLogicGroup(): ?FormFieldConditionalLogicGroup
+    {
+        return $this->conditionalLogicGroups()
+            ->whereNull('parent_group_id')
+            ->first();
+    }
+
     /**
      * Nuanced activity log (ARCH §17.1; S1 Phase 4b). Callers choose which
      * events are worth logging — e.g. created/deleted/restored, field_type

api/app/Models/FormBuilder/FormFieldConditionalLogicCondition.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models\FormBuilder;
+
+use App\Enums\FormBuilder\FormFieldConditionalLogicConditionOperator;
+use App\Models\Scopes\OrganisationScope;
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * A leaf of the relational conditional-logic tree — one comparison
+ * of `(field_slug, operator, value)` against the current form values
+ * (ARCH-FORM-BUILDER §8).
+ *
+ * `value` is JSON nullable: scalar for most operators, array for
+ * `in`/`not_in`, null for `empty`/`not_empty`. Shape validation is
+ * enforced at the service layer (`FormFieldConditionalLogicService
+ * ::assertSpecsValid`), not the DB.
+ *
+ * Multi-tenancy chain is 4 hops (condition → group → field → schema →
+ * organisation_id column) — inside the WS-5c raised cap of 5.
+ */
+final class FormFieldConditionalLogicCondition extends Model
+{
+    use HasFactory;
+    use HasUlids;
+
+    protected $table = 'form_field_conditional_logic_conditions';
+
+    protected static function booted(): void
+    {
+        static::addGlobalScope(new OrganisationScope());
+    }
+
+    /** @return array{via: class-string, fk: string} */
+    public static function tenantScopeStrategy(): array
+    {
+        return ['via' => FormFieldConditionalLogicGroup::class, 'fk' => 'group_id'];
+    }
+
+    protected $fillable = [
+        'group_id',
+        'field_slug',
+        'comparison_operator',
+        'value',
+        'sort_order',
+    ];
+
+    /** @var array<string, string> */
+    protected $casts = [
+        'comparison_operator' => FormFieldConditionalLogicConditionOperator::class,
+        'value' => 'array',
+        'sort_order' => 'int',
+    ];
+
+    public function group(): BelongsTo
+    {
+        return $this->belongsTo(FormFieldConditionalLogicGroup::class, 'group_id');
+    }
+}

api/app/Models/FormBuilder/FormFieldConditionalLogicGroup.php

@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models\FormBuilder;
+
+use App\Enums\FormBuilder\FormFieldConditionalLogicGroupOperator;
+use App\Models\Scopes\OrganisationScope;
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+/**
+ * A node in the relational conditional-logic tree for a form field
+ * (ARCH-FORM-BUILDER §8). The root group carries the outer boolean
+ * operator (`all` / `any`); nested sub-groups link via
+ * `parent_group_id`. Leaves live in `FormFieldConditionalLogicCondition`.
+ *
+ * Multi-tenancy uses the Q2 declarative FK-chain resolver via
+ * `tenantScopeStrategy()`. The chain (group → field → schema →
+ * organisation_id) is 3 hops — comfortably inside the cap (5 hops as of
+ * WS-5c).
+ */
+final class FormFieldConditionalLogicGroup extends Model
+{
+    use HasFactory;
+    use HasUlids;
+
+    protected $table = 'form_field_conditional_logic_groups';
+
+    protected static function booted(): void
+    {
+        static::addGlobalScope(new OrganisationScope());
+    }
+
+    /** @return array{via: class-string, fk: string} */
+    public static function tenantScopeStrategy(): array
+    {
+        return ['via' => FormField::class, 'fk' => 'form_field_id'];
+    }
+
+    protected $fillable = [
+        'form_field_id',
+        'parent_group_id',
+        'operator',
+        'sort_order',
+    ];
+
+    /** @var array<string, string> */
+    protected $casts = [
+        'operator' => FormFieldConditionalLogicGroupOperator::class,
+        'sort_order' => 'int',
+    ];
+
+    public function formField(): BelongsTo
+    {
+        return $this->belongsTo(FormField::class, 'form_field_id');
+    }
+
+    public function parentGroup(): BelongsTo
+    {
+        return $this->belongsTo(self::class, 'parent_group_id');
+    }
+
+    public function childGroups(): HasMany
+    {
+        return $this->hasMany(self::class, 'parent_group_id');
+    }
+
+    public function conditions(): HasMany
+    {
+        return $this->hasMany(FormFieldConditionalLogicCondition::class, 'group_id');
+    }
+}

api/app/Models/Scopes/OrganisationScope.php

@@ -26,9 +26,15 @@ use Illuminate\Database\Eloquent\Scope;
  *         ['column' => 'organisation_id']  — direct scope column, OR
  *         ['via' => ParentModel::class, 'fk' => 'parent_id']  — walk to parent
  *       The resolver recurses through parents until it hits a column strategy
- *       or the legacy $organisationScopeColumn bridge. Cap at 3 hops; deeper
+ *       or the legacy $organisationScopeColumn bridge. Cap at 5 hops; deeper
  *       chains raise TenantScopeResolutionException.
  *
+ *       Cap raised from 3 to 5 in WS-5c (2026-04-26). Legitimate relational
+ *       trees — `form_field_conditional_logic_conditions → group → field →
+ *       schema → org` — exceed the original limit. Raising to 5 accommodates
+ *       this without denormalising `form_field_id` onto conditions (which
+ *       would introduce drift risk).
+ *
  *   (b) Legacy column property (pre-addendum — still supported so Person,
  *       Event, FestivalSection, etc. need not migrate in this work package):
  *       `public string $organisationScopeColumn = 'organisation_id'
@@ -43,7 +49,7 @@ use Illuminate\Database\Eloquent\Scope;
  */
 final class OrganisationScope implements Scope
 {
-    private const MAX_CHAIN_HOPS = 3;
+    private const MAX_CHAIN_HOPS = 5;
 
     public function __construct(
         private readonly ?string $organisationId = null,

api/app/Observers/FormBuilder/FormFieldChildTablesCascadeObserver.php

@@ -10,22 +10,28 @@ use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Schema;
 
 /**
- * Cascades physical deletion of child rows in the three relational tables
+ * Cascades physical deletion of child rows in the relational tables
  * that hang off `form_fields` / `form_field_library`:
  *
- *   - `form_field_bindings`            (WS-5a)
- *   - `form_field_validation_rules`    (WS-5b)
- *   - `form_field_configs`             (WS-5b expansion; added in commit 5)
+ *   - `form_field_bindings`                       (WS-5a)
+ *   - `form_field_validation_rules`               (WS-5b)
+ *   - `form_field_configs`                        (WS-5b commit 5)
+ *   - `form_field_conditional_logic_groups`       (WS-5c — FormField only,
+ *                                                  per addendum Q3: library
+ *                                                  is explicitly out of
+ *                                                  scope for conditional_logic)
+ *
+ * The conditions sibling table cascades automatically via the `group_id`
+ * FK on the groups table — no direct entry here.
  *
  * Children represent current state (not historical intent) — physically
  * deleted even when the owner is only soft-deleted, per addendum Q3: no
  * child table in this family carries a soft-delete semantic of its own.
  *
  * Renamed from `FormFieldBindingsCascadeObserver` during WS-5b commit 1.
- * The `Schema::hasTable` guard on the validation-rules cleanup keeps the
- * observer safe when this code runs against a database where commit 1's
- * migration has not yet been applied (e.g. during the migration step
- * itself, where the observer is registered before the table exists).
+ * The `Schema::hasTable` guard keeps the observer safe when this code
+ * runs against a database where a later migration has not yet been
+ * applied (e.g. during the migration step itself).
  */
 final class FormFieldChildTablesCascadeObserver
 {
@@ -52,5 +58,14 @@ final class FormFieldChildTablesCascadeObserver
                 ->where('owner_id', $ownerId)
                 ->delete();
         }
+
+        // Conditional-logic groups only apply to FormField (addendum Q3:
+        // library mirror is out of scope). Condition rows cascade via
+        // the group_id FK on the conditions table.
+        if ($owner instanceof FormField && Schema::hasTable('form_field_conditional_logic_groups')) {
+            DB::table('form_field_conditional_logic_groups')
+                ->where('form_field_id', $ownerId)
+                ->delete();
+        }
     }
 }