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/tests/Feature/FormBuilder/Bindings/FormFieldBindingMigrationTest.php

@@ -33,11 +33,12 @@ final class FormFieldBindingMigrationTest extends TestCase
 
     public function test_forward_migrations_backfill_rows_from_both_json_sources(): void
     {
-        // Roll back to pre-WS-5a state: 5 WS-5b migrations
-        // (drop-validation-cols, configs-backfill, create-configs,
-        // validation-rules-backfill, create-validation-rules) +
-        // 2 WS-5a migrations (drop-binding-cols, create-bindings) = 7.
-        $this->artisan('migrate:rollback', ['--step' => 7])->assertSuccessful();
+        // Roll back to pre-WS-5a state: 2 WS-5c migrations
+        // (create-conditional-logic-conditions, create-conditional-logic-groups) +
+        // 5 WS-5b migrations (drop-validation-cols, configs-backfill,
+        // create-configs, validation-rules-backfill, create-validation-rules) +
+        // 2 WS-5a migrations (drop-binding-cols, create-bindings) = 9.
+        $this->artisan('migrate:rollback', ['--step' => 9])->assertSuccessful();
         $this->assertFalse(Schema::hasTable('form_field_bindings'));
         $this->assertTrue(Schema::hasColumn('form_fields', 'binding'));
         $this->assertTrue(Schema::hasColumn('form_field_library', 'default_binding'));
@@ -98,8 +99,8 @@ final class FormFieldBindingMigrationTest extends TestCase
 
     public function test_rollback_reconstructs_json_and_drops_table(): void
     {
-        // Walk back the full WS-5b + WS-5a stack (7 migrations).
-        $this->artisan('migrate:rollback', ['--step' => 7])->assertSuccessful();
+        // Walk back the full WS-5c + WS-5b + WS-5a stack (9 migrations).
+        $this->artisan('migrate:rollback', ['--step' => 9])->assertSuccessful();
         [$fieldAId, , ] = $this->seedFieldsWithBindingJson();
         [$libAId, ] = $this->seedLibraryWithBindingJson();
 
@@ -109,11 +110,13 @@ final class FormFieldBindingMigrationTest extends TestCase
         $this->assertFalse(Schema::hasColumn('form_fields', 'binding'));
         $this->assertSame(5, DB::table('form_field_bindings')->count());
 
-        // Step back over all five WS-5b migrations in one go → restores the
-        // pre-WS-5b state (validation-rules and configs tables gone,
-        // validation_rules JSON columns reappear on source tables; binding
-        // contract intact).
-        $this->artisan('migrate:rollback', ['--step' => 5])->assertSuccessful();
+        // Step back over WS-5c (2 migrations) + WS-5b (5 migrations) in one
+        // go → restores the pre-WS-5b state (conditional-logic,
+        // validation-rules and configs tables gone, validation_rules JSON
+        // columns reappear on source tables; binding contract intact).
+        $this->artisan('migrate:rollback', ['--step' => 7])->assertSuccessful();
+        $this->assertFalse(Schema::hasTable('form_field_conditional_logic_groups'));
+        $this->assertFalse(Schema::hasTable('form_field_conditional_logic_conditions'));
         $this->assertFalse(Schema::hasTable('form_field_validation_rules'));
         $this->assertFalse(Schema::hasTable('form_field_configs'));
         $this->assertTrue(Schema::hasTable('form_field_bindings'));

api/tests/Feature/FormBuilder/ConditionalLogic/FormFieldConditionalLogicCascadeTest.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder\ConditionalLogic;
+
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormFieldConditionalLogicCondition;
+use App\Models\FormBuilder\FormFieldConditionalLogicGroup;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\Organisation;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\DB;
+use Tests\TestCase;
+
+final class FormFieldConditionalLogicCascadeTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_field_hard_delete_cascades_groups_and_conditions(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+
+        $root = FormFieldConditionalLogicGroup::factory()->forField($field)->create();
+        $child = FormFieldConditionalLogicGroup::factory()->nestedUnder($root, 0)->create();
+        FormFieldConditionalLogicCondition::factory()->inGroup($root, 0)->create();
+        FormFieldConditionalLogicCondition::factory()->inGroup($child, 0)->create();
+
+        $this->assertSame(2, FormFieldConditionalLogicGroup::query()->count());
+        $this->assertSame(2, FormFieldConditionalLogicCondition::query()->count());
+
+        // Hard delete via raw query bypasses SoftDeletes — exercises the
+        // DB-level `ON DELETE CASCADE` on `form_field_id`.
+        DB::table('form_fields')->where('id', $field->id)->delete();
+
+        $this->assertSame(0, FormFieldConditionalLogicGroup::query()->count());
+        $this->assertSame(0, FormFieldConditionalLogicCondition::query()->count());
+    }
+
+    public function test_field_soft_delete_cascades_via_observer(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+
+        $root = FormFieldConditionalLogicGroup::factory()->forField($field)->create();
+        FormFieldConditionalLogicCondition::factory()->inGroup($root, 0)->create();
+
+        $field->delete();
+
+        // Soft delete keeps the `form_fields` row (deleted_at set) but the
+        // cascade observer physically clears child rows — conditional-logic
+        // state is current state, not audit.
+        $this->assertNotNull($field->fresh()->deleted_at);
+        $this->assertSame(0, FormFieldConditionalLogicGroup::query()->count());
+        $this->assertSame(0, FormFieldConditionalLogicCondition::query()->count());
+    }
+
+    public function test_parent_group_delete_cascades_to_children_and_conditions(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+
+        $root = FormFieldConditionalLogicGroup::factory()->forField($field)->create();
+        $child = FormFieldConditionalLogicGroup::factory()->nestedUnder($root, 0)->create();
+        FormFieldConditionalLogicCondition::factory()->inGroup($root, 0)->create();
+        FormFieldConditionalLogicCondition::factory()->inGroup($child, 0)->create();
+
+        $this->assertSame(2, FormFieldConditionalLogicGroup::query()->count());
+        $this->assertSame(2, FormFieldConditionalLogicCondition::query()->count());
+
+        $root->delete();
+
+        $this->assertSame(0, FormFieldConditionalLogicGroup::query()->count());
+        $this->assertSame(0, FormFieldConditionalLogicCondition::query()->count());
+    }
+}

api/tests/Feature/FormBuilder/ConditionalLogic/FormFieldConditionalLogicConditionRelationTest.php

@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder\ConditionalLogic;
+
+use App\Enums\FormBuilder\FormFieldConditionalLogicConditionOperator;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormFieldConditionalLogicCondition;
+use App\Models\FormBuilder\FormFieldConditionalLogicGroup;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\Organisation;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+final class FormFieldConditionalLogicConditionRelationTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_condition_belongs_to_group(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+
+        $group = FormFieldConditionalLogicGroup::factory()->forField($field)->create();
+        $condition = FormFieldConditionalLogicCondition::factory()->inGroup($group)->create();
+
+        $this->assertSame($group->id, $condition->fresh()->group->id);
+    }
+
+    public function test_value_roundtrips_through_json_cast(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+        $group = FormFieldConditionalLogicGroup::factory()->forField($field)->create();
+
+        $stringValue = FormFieldConditionalLogicCondition::factory()
+            ->inGroup($group)
+            ->withOperator(FormFieldConditionalLogicConditionOperator::Equals, 'NL')
+            ->create();
+        $this->assertSame('NL', $stringValue->fresh()->value);
+
+        $arrayValue = FormFieldConditionalLogicCondition::factory()
+            ->inGroup($group)
+            ->withOperator(FormFieldConditionalLogicConditionOperator::In, ['a', 'b', 'c'])
+            ->create();
+        $this->assertSame(['a', 'b', 'c'], $arrayValue->fresh()->value);
+
+        $boolValue = FormFieldConditionalLogicCondition::factory()
+            ->inGroup($group)
+            ->withOperator(FormFieldConditionalLogicConditionOperator::Equals, true)
+            ->create();
+        $this->assertTrue($boolValue->fresh()->value);
+    }
+
+    public function test_valueless_operators_store_null(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+        $group = FormFieldConditionalLogicGroup::factory()->forField($field)->create();
+
+        $empty = FormFieldConditionalLogicCondition::factory()
+            ->inGroup($group)
+            ->withOperator(FormFieldConditionalLogicConditionOperator::Empty)
+            ->create();
+        $this->assertNull($empty->fresh()->value);
+
+        $notEmpty = FormFieldConditionalLogicCondition::factory()
+            ->inGroup($group)
+            ->withOperator(FormFieldConditionalLogicConditionOperator::NotEmpty)
+            ->create();
+        $this->assertNull($notEmpty->fresh()->value);
+    }
+
+    public function test_enum_catalogue_has_ten_operators(): void
+    {
+        // Parity check against ARCH §8 / Phase A seed-scan confirmed set.
+        $values = array_map(
+            fn (FormFieldConditionalLogicConditionOperator $case): string => $case->value,
+            FormFieldConditionalLogicConditionOperator::cases(),
+        );
+
+        sort($values);
+        $this->assertSame([
+            'contains',
+            'empty',
+            'equals',
+            'greater_than',
+            'in',
+            'less_than',
+            'not_contains',
+            'not_empty',
+            'not_equals',
+            'not_in',
+        ], $values);
+    }
+
+    public function test_field_slug_index_supports_reverse_lookup(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+        $group = FormFieldConditionalLogicGroup::factory()->forField($field)->create();
+
+        FormFieldConditionalLogicCondition::factory()
+            ->inGroup($group)
+            ->forFieldSlug('gate')
+            ->create();
+        FormFieldConditionalLogicCondition::factory()
+            ->inGroup($group)
+            ->forFieldSlug('region')
+            ->create();
+
+        $gateHits = FormFieldConditionalLogicCondition::query()
+            ->where('field_slug', 'gate')
+            ->count();
+        $this->assertSame(1, $gateHits);
+    }
+}

api/tests/Feature/FormBuilder/ConditionalLogic/FormFieldConditionalLogicGroupRelationTest.php

@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder\ConditionalLogic;
+
+use App\Enums\FormBuilder\FormFieldConditionalLogicConditionOperator;
+use App\Enums\FormBuilder\FormFieldConditionalLogicGroupOperator;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormFieldConditionalLogicCondition;
+use App\Models\FormBuilder\FormFieldConditionalLogicGroup;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\Organisation;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+final class FormFieldConditionalLogicGroupRelationTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_field_has_many_conditional_logic_groups(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+
+        $root = FormFieldConditionalLogicGroup::factory()
+            ->forField($field)
+            ->withOperator(FormFieldConditionalLogicGroupOperator::All)
+            ->create();
+        FormFieldConditionalLogicGroup::factory()
+            ->nestedUnder($root, 0)
+            ->withOperator(FormFieldConditionalLogicGroupOperator::Any)
+            ->create();
+
+        $groups = $field->fresh()->conditionalLogicGroups;
+        $this->assertCount(2, $groups);
+    }
+
+    public function test_root_helper_returns_parentless_group(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+
+        $root = FormFieldConditionalLogicGroup::factory()->forField($field)->create();
+        FormFieldConditionalLogicGroup::factory()->nestedUnder($root, 0)->create();
+        FormFieldConditionalLogicGroup::factory()->nestedUnder($root, 1)->create();
+
+        $found = $field->fresh()->rootConditionalLogicGroup();
+        $this->assertNotNull($found);
+        $this->assertSame($root->id, $found->id);
+        $this->assertNull($found->parent_group_id);
+    }
+
+    public function test_group_relations_parent_and_children(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+
+        $root = FormFieldConditionalLogicGroup::factory()->forField($field)->create();
+        $child1 = FormFieldConditionalLogicGroup::factory()->nestedUnder($root, 0)->create();
+        $child2 = FormFieldConditionalLogicGroup::factory()->nestedUnder($root, 1)->create();
+
+        $this->assertSame($root->id, $child1->fresh()->parentGroup->id);
+        $childIds = $root->fresh()->childGroups->pluck('id')->sort()->values()->all();
+        $this->assertSame(collect([$child1->id, $child2->id])->sort()->values()->all(), $childIds);
+    }
+
+    public function test_group_has_many_conditions(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+
+        $group = FormFieldConditionalLogicGroup::factory()->forField($field)->create();
+        FormFieldConditionalLogicCondition::factory()->inGroup($group, 0)->create();
+        FormFieldConditionalLogicCondition::factory()->inGroup($group, 1)->create();
+
+        $this->assertCount(2, $group->fresh()->conditions);
+    }
+
+    public function test_operator_enum_casts_roundtrip(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+
+        $group = FormFieldConditionalLogicGroup::factory()
+            ->forField($field)
+            ->withOperator(FormFieldConditionalLogicGroupOperator::Any)
+            ->create();
+
+        $fresh = $group->fresh();
+        $this->assertSame(FormFieldConditionalLogicGroupOperator::Any, $fresh->operator);
+
+        $condition = FormFieldConditionalLogicCondition::factory()
+            ->inGroup($group)
+            ->withOperator(FormFieldConditionalLogicConditionOperator::GreaterThan, 18)
+            ->create();
+
+        $this->assertSame(
+            FormFieldConditionalLogicConditionOperator::GreaterThan,
+            $condition->fresh()->comparison_operator,
+        );
+        $this->assertSame(18, $condition->fresh()->value);
+    }
+}

api/tests/Feature/FormBuilder/ConditionalLogic/FormFieldConditionalLogicScopeTest.php

@@ -0,0 +1,103 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder\ConditionalLogic;
+
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormFieldConditionalLogicCondition;
+use App\Models\FormBuilder\FormFieldConditionalLogicGroup;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\Organisation;
+use App\Models\Scopes\OrganisationScope;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Routing\Route;
+use Tests\TestCase;
+
+/**
+ * Verifies that the OrganisationScope FK-chain resolver (Q2 declarative
+ * strategy) keeps groups AND conditions tenant-isolated. Groups resolve
+ * at 3 hops (group → field → schema → organisation_id); conditions at 4
+ * (condition → group → field → schema → organisation_id). The latter
+ * only fits after WS-5c raised the cap from 3 to 5.
+ */
+final class FormFieldConditionalLogicScopeTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_scope_isolates_groups_per_organisation(): void
+    {
+        [$orgA, $fieldA] = $this->seedOrgWithLogic();
+        [$orgB, $fieldB] = $this->seedOrgWithLogic();
+
+        $this->withOrgRoute($orgA);
+        $fieldIdsA = FormFieldConditionalLogicGroup::query()->pluck('form_field_id')->unique()->values()->all();
+        $this->assertSame([$fieldA->id], $fieldIdsA);
+
+        $this->withOrgRoute($orgB);
+        $fieldIdsB = FormFieldConditionalLogicGroup::query()->pluck('form_field_id')->unique()->values()->all();
+        $this->assertSame([$fieldB->id], $fieldIdsB);
+    }
+
+    public function test_scope_isolates_conditions_per_organisation(): void
+    {
+        [$orgA, $fieldA] = $this->seedOrgWithLogic();
+        $this->seedOrgWithLogic();
+
+        $this->withOrgRoute($orgA);
+        $this->assertSame(
+            1,
+            FormFieldConditionalLogicCondition::query()
+                ->where('field_slug', 'gate')
+                ->count(),
+        );
+    }
+
+    public function test_without_global_scope_exposes_cross_org(): void
+    {
+        [$orgA] = $this->seedOrgWithLogic();
+        $this->seedOrgWithLogic();
+
+        $this->withOrgRoute($orgA);
+
+        $this->assertSame(1, FormFieldConditionalLogicGroup::query()->count());
+        $this->assertSame(
+            2,
+            FormFieldConditionalLogicGroup::query()
+                ->withoutGlobalScope(OrganisationScope::class)
+                ->count(),
+        );
+
+        $this->assertSame(1, FormFieldConditionalLogicCondition::query()->count());
+        $this->assertSame(
+            2,
+            FormFieldConditionalLogicCondition::query()
+                ->withoutGlobalScope(OrganisationScope::class)
+                ->count(),
+        );
+    }
+
+    /** @return array{0:Organisation,1:FormField} */
+    private function seedOrgWithLogic(): array
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create(['form_schema_id' => $schema->id]);
+
+        $root = FormFieldConditionalLogicGroup::factory()->forField($field)->create();
+        FormFieldConditionalLogicCondition::factory()
+            ->inGroup($root)
+            ->forFieldSlug('gate')
+            ->create();
+
+        return [$org, $field];
+    }
+
+    private function withOrgRoute(Organisation $org): void
+    {
+        $route = new Route(['GET'], '/_test', static fn () => null);
+        $route->bind(request());
+        $route->setParameter('organisation', $org);
+        request()->setRouteResolver(static fn () => $route);
+    }
+}

api/tests/Feature/FormBuilder/Configs/FormFieldConfigBackfillAndDropTest.php

@@ -27,9 +27,10 @@ final class FormFieldConfigBackfillAndDropTest extends TestCase
 
     public function test_backfill_translates_tag_categories_and_storage_disk(): void
     {
-        // Roll back 5 WS-5b migrations to get the pre-WS-5b state where
-        // the JSON column still exists on form_fields / form_field_library.
-        $this->artisan('migrate:rollback', ['--step' => 5])->assertSuccessful();
+        // Roll back 2 WS-5c migrations + 5 WS-5b migrations = 7, to get the
+        // pre-WS-5b state where the JSON column still exists on form_fields
+        // / form_field_library.
+        $this->artisan('migrate:rollback', ['--step' => 7])->assertSuccessful();
         $this->assertTrue(Schema::hasColumn('form_fields', 'validation_rules'));
 
         $fieldId = $this->seedField([

api/tests/Feature/FormBuilder/ValidationRules/FormFieldValidationRuleBackfillTest.php

@@ -31,14 +31,13 @@ final class FormFieldValidationRuleBackfillTest extends TestCase
 
     public function test_forward_migration_backfills_rows_with_field_type_dispatch(): void
     {
-        // Roll back: backfill + create-table. Brings us to a state where
-        // form_fields.validation_rules exists but form_field_validation_rules
-        // table does not.
-        // Roll back all WS-5b migrations to reach the pre-WS-5b state
-        // (validation_rules JSON column present; no relational tables for
-        // WS-5b). Step count: drop-cols + configs-backfill + create-configs
-        // + validation-rules-backfill + create-validation-rules = 5.
-        $this->artisan('migrate:rollback', ['--step' => 5])->assertSuccessful();
+        // Roll back: 2 WS-5c migrations (create-conditional-logic-conditions,
+        // create-conditional-logic-groups) + 5 WS-5b migrations
+        // (drop-cols + configs-backfill + create-configs +
+        // validation-rules-backfill + create-validation-rules) = 7.
+        // Brings us to the pre-WS-5b state: validation_rules JSON column
+        // present, no relational tables for WS-5b.
+        $this->artisan('migrate:rollback', ['--step' => 7])->assertSuccessful();
         $this->assertFalse(Schema::hasTable('form_field_validation_rules'));
         $this->assertTrue(Schema::hasColumn('form_fields', 'validation_rules'));
 
@@ -99,7 +98,7 @@ final class FormFieldValidationRuleBackfillTest extends TestCase
         // (validation_rules JSON column present; no relational tables for
         // WS-5b). Step count: drop-cols + configs-backfill + create-configs
         // + validation-rules-backfill + create-validation-rules = 5.
-        $this->artisan('migrate:rollback', ['--step' => 5])->assertSuccessful();
+        $this->artisan('migrate:rollback', ['--step' => 7])->assertSuccessful();
 
         $fieldId = $this->seedFieldWithJson([
             'field_type' => 'TAG_PICKER',
@@ -123,7 +122,7 @@ final class FormFieldValidationRuleBackfillTest extends TestCase
         // (validation_rules JSON column present; no relational tables for
         // WS-5b). Step count: drop-cols + configs-backfill + create-configs
         // + validation-rules-backfill + create-validation-rules = 5.
-        $this->artisan('migrate:rollback', ['--step' => 5])->assertSuccessful();
+        $this->artisan('migrate:rollback', ['--step' => 7])->assertSuccessful();
 
         $fieldId = $this->seedFieldWithJson([
             'field_type' => 'TEXT',
@@ -150,7 +149,7 @@ final class FormFieldValidationRuleBackfillTest extends TestCase
         // (validation_rules JSON column present; no relational tables for
         // WS-5b). Step count: drop-cols + configs-backfill + create-configs
         // + validation-rules-backfill + create-validation-rules = 5.
-        $this->artisan('migrate:rollback', ['--step' => 5])->assertSuccessful();
+        $this->artisan('migrate:rollback', ['--step' => 7])->assertSuccessful();
 
         $this->seedFieldWithJson([
             'field_type' => 'TEXT',
@@ -167,7 +166,7 @@ final class FormFieldValidationRuleBackfillTest extends TestCase
         // (validation_rules JSON column present; no relational tables for
         // WS-5b). Step count: drop-cols + configs-backfill + create-configs
         // + validation-rules-backfill + create-validation-rules = 5.
-        $this->artisan('migrate:rollback', ['--step' => 5])->assertSuccessful();
+        $this->artisan('migrate:rollback', ['--step' => 7])->assertSuccessful();
 
         $this->seedFieldWithJson([
             'field_type' => 'BOOLEAN',
@@ -186,7 +185,7 @@ final class FormFieldValidationRuleBackfillTest extends TestCase
         // full-back-then-full-forward cycle — rolling back all WS-5b
         // migrations restores the pre-WS-5b state (columns present on
         // source tables; validation rules relational table gone).
-        $this->artisan('migrate:rollback', ['--step' => 5])->assertSuccessful();
+        $this->artisan('migrate:rollback', ['--step' => 7])->assertSuccessful();
         [$numberId] = $this->seedFields();
 
         $this->artisan('migrate')->assertSuccessful();
@@ -201,7 +200,7 @@ final class FormFieldValidationRuleBackfillTest extends TestCase
 
         // Roll back WS-5b fully → column reappears and carries canonical JSON
         // reconstructed from the relational rows.
-        $this->artisan('migrate:rollback', ['--step' => 5])->assertSuccessful();
+        $this->artisan('migrate:rollback', ['--step' => 7])->assertSuccessful();
         $this->assertTrue(Schema::hasColumn('form_fields', 'validation_rules'));
 
         $field = DB::table('form_fields')->where('id', $numberId)->first();

api/tests/Feature/MultiTenancy/ScopeLeakageTest.php

@@ -454,31 +454,106 @@ final class ScopeLeakageTest extends TestCase
         $this->assertSame(1, PersonIdentityMatch::query()->count());
     }
 
-    public function test_resolver_raises_on_over_deep_chain(): void
+    public function test_resolver_resolves_four_hop_chain_within_cap(): void
     {
-        // Construct a synthetic 5-hop chain by subclassing on the fly:
-        // A → B → C → D → E (column). The resolver caps at 3 hops and
-        // must raise TenantScopeResolutionException.
-        $fiveHopModel = new class extends Model {
-            protected $table = 'form_value_options';
-            public static function tenantScopeStrategy(): array
-            {
-                return ['via' => FiveHopLevel2::class, 'fk' => 'form_value_id'];
-            }
-        };
+        // 4 via-hops + terminal column = legitimate tree inside the cap.
+        // Build the query and assert no exception; the SQL references every
+        // intermediate table, proving the walker reached the terminal.
+        $scope = new OrganisationScope($this->orgA->id);
+        $builder = (new FourHopLevel1())::query();
 
-        $scope = new OrganisationScope('01HZ01HZ01HZ01HZ01HZ01HZ01');
-        $builder = $fiveHopModel::query();
+        $scope->apply($builder, new FourHopLevel1());
+
+        $sql = $builder->toSql();
+        $this->assertStringContainsString('form_value_options', $sql);
+        $this->assertStringContainsString('form_values', $sql);
+        $this->assertStringContainsString('form_submissions', $sql);
+        $this->assertStringContainsString('form_schemas', $sql);
+        $this->assertStringContainsString('organisation_id', $sql);
+    }
+
+    public function test_resolver_resolves_five_hop_chain_at_cap(): void
+    {
+        // 5 via-hops + terminal column — right at the cap ceiling.
+        $scope = new OrganisationScope($this->orgA->id);
+        $builder = (new FiveHopLevel1())::query();
+
+        $scope->apply($builder, new FiveHopLevel1());
+
+        $this->assertStringContainsString('organisation_id', $builder->toSql());
+    }
+
+    public function test_resolver_raises_when_chain_exceeds_cap(): void
+    {
+        // 6 via-hops — one past the cap of 5. Must raise.
+        $scope = new OrganisationScope($this->orgA->id);
+        $builder = (new SevenHopLevel1())::query();
 
         $this->expectException(TenantScopeResolutionException::class);
-        $scope->apply($builder, $fiveHopModel);
+        $scope->apply($builder, new SevenHopLevel1());
     }
 }
 
 /**
- * Synthetic chain model for the over-deep-chain test — four levels
- * above a terminal column, so resolver walks past its cap.
+ * Synthetic chain models for the scope-cap tests. Tables referenced
+ * exist in the schema so query compilation succeeds; the intermediate
+ * relations are never actually executed in these tests (we assert on
+ * compiled SQL, not on rows).
+ *
+ * FourHopLevel1 → Level2 → Level3 → Level4 (terminal column).
+ * FiveHopLevel1 → Level2 → Level3 → Level4 → Level5 (terminal column).
+ * SevenHopLevel1 → ... → Level7 (terminal column) — exceeds cap=5.
  */
+final class FourHopLevel1 extends Model
+{
+    protected $table = 'form_value_options';
+
+    public static function tenantScopeStrategy(): array
+    {
+        return ['via' => FourHopLevel2::class, 'fk' => 'form_value_id'];
+    }
+}
+
+final class FourHopLevel2 extends Model
+{
+    protected $table = 'form_values';
+
+    public static function tenantScopeStrategy(): array
+    {
+        return ['via' => FourHopLevel3::class, 'fk' => 'form_submission_id'];
+    }
+}
+
+final class FourHopLevel3 extends Model
+{
+    protected $table = 'form_submissions';
+
+    public static function tenantScopeStrategy(): array
+    {
+        return ['via' => FourHopLevel4::class, 'fk' => 'form_schema_id'];
+    }
+}
+
+final class FourHopLevel4 extends Model
+{
+    protected $table = 'form_schemas';
+
+    public static function tenantScopeStrategy(): array
+    {
+        return ['column' => 'organisation_id'];
+    }
+}
+
+final class FiveHopLevel1 extends Model
+{
+    protected $table = 'form_value_options';
+
+    public static function tenantScopeStrategy(): array
+    {
+        return ['via' => FiveHopLevel2::class, 'fk' => 'form_value_id'];
+    }
+}
+
 final class FiveHopLevel2 extends Model
 {
     protected $table = 'form_values';
@@ -505,16 +580,86 @@ final class FiveHopLevel4 extends Model
 
     public static function tenantScopeStrategy(): array
     {
-        return ['via' => FiveHopLevel5::class, 'fk' => 'organisation_id'];
+        return ['via' => FiveHopLevel5::class, 'fk' => 'id'];
     }
 }
 
 final class FiveHopLevel5 extends Model
 {
-    protected $table = 'organisations';
+    protected $table = 'form_schemas';
 
     public static function tenantScopeStrategy(): array
     {
-        return ['column' => 'id'];
+        return ['column' => 'organisation_id'];
+    }
+}
+
+final class SevenHopLevel1 extends Model
+{
+    protected $table = 'form_value_options';
+
+    public static function tenantScopeStrategy(): array
+    {
+        return ['via' => SevenHopLevel2::class, 'fk' => 'form_value_id'];
+    }
+}
+
+final class SevenHopLevel2 extends Model
+{
+    protected $table = 'form_values';
+
+    public static function tenantScopeStrategy(): array
+    {
+        return ['via' => SevenHopLevel3::class, 'fk' => 'form_submission_id'];
+    }
+}
+
+final class SevenHopLevel3 extends Model
+{
+    protected $table = 'form_submissions';
+
+    public static function tenantScopeStrategy(): array
+    {
+        return ['via' => SevenHopLevel4::class, 'fk' => 'form_schema_id'];
+    }
+}
+
+final class SevenHopLevel4 extends Model
+{
+    protected $table = 'form_schemas';
+
+    public static function tenantScopeStrategy(): array
+    {
+        return ['via' => SevenHopLevel5::class, 'fk' => 'id'];
+    }
+}
+
+final class SevenHopLevel5 extends Model
+{
+    protected $table = 'form_schemas';
+
+    public static function tenantScopeStrategy(): array
+    {
+        return ['via' => SevenHopLevel6::class, 'fk' => 'id'];
+    }
+}
+
+final class SevenHopLevel6 extends Model
+{
+    protected $table = 'form_schemas';
+
+    public static function tenantScopeStrategy(): array
+    {
+        return ['via' => SevenHopLevel7::class, 'fk' => 'id'];
+    }
+}
+
+final class SevenHopLevel7 extends Model
+{
+    protected $table = 'form_schemas';
+
+    public static function tenantScopeStrategy(): array
+    {
+        return ['column' => 'organisation_id'];
     }
 }