refactor(form-field): extract FormFieldChildTableMorphScope abstract base

Closes the WS-5 family follow-up tracked as
FORM-BUILDER-MORPH-SCOPE-BASE-CLASS in BACKLOG.md. Per addendum
§Q3 Uitvoering across WS-5a/b/c/d, base-class extraction was
deliberately deferred until all four concrete morph-scope siblings
existed and the "what actually varies" question could be answered
empirically.

The answer is: nothing. All four siblings —
FormFieldBindingScope (WS-5a), FormFieldValidationRuleScope (WS-5b),
FormFieldConfigScope (WS-5b commit 5), and FormFieldOptionScope
(WS-5d) — are byte-equal in their apply() and resolveOrganisationId()
methods (Phase A diff verification clean: zero lines diverging
across all three pairwise comparisons).

Approach:

  - New abstract class FormFieldChildTableMorphScope holds the full
    UNION-over-two-owner-chains scope logic with the morph alias
    literals extracted as private constants
    (OWNER_TYPE_FIELD, OWNER_TYPE_LIBRARY) for one-location-of-truth.
  - The four concrete scopes become marker subclasses
    (`final class X extends FormFieldChildTableMorphScope {}`) — class
    identity preserved so every existing
    `withoutGlobalScope(FormFieldXScope::class)` call site in cascade
    observers, backfill migrations, and platform super_admin paths
    continues to work unchanged. The 4 test call sites (in the four
    *ScopeTest classes) work without modification.
  - Helper visibility stays `private` per YAGNI. If a future sibling
    needs to vary the morph aliases or owner-chain, the helpers
    promote to `protected` at that point.
  - Stylistic refinement vs. the four originals: `Organisation` and
    `Event` in resolveOrganisationId() now use `use` statements at
    the top of the file instead of inline `\App\Models\…` FQNs.

Net diff:
  Pre:  4 concrete scope files at ~106 lines each (~424 lines total)
  Post: 4 marker subclasses at 20 lines (80 total) +
        1 abstract base at 125 lines = 205 lines total
  Saving: ~219 lines of duplication removed.

Tests: 1208 passed (3260 assertions) → 1208 passed (3260 assertions).
Identical — public behaviour unchanged.

Larastan: clean (no new errors beyond baseline).
Rector: 357 → 355 dry-run suggestions (small reduction from the
deduplication; no apply in this commit).

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

api/app/Models/Scopes/FormFieldBindingScope.php

@@ -4,103 +4,17 @@ declare(strict_types=1);
 
 namespace App\Models\Scopes;
 
-use App\Models\FormBuilder\FormField;
-use App\Models\FormBuilder\FormFieldLibrary;
-use App\Models\FormBuilder\FormSchema;
-use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Database\Eloquent\Model;
-use Illuminate\Database\Eloquent\Scope;
-
 /**
- * Multi-tenant isolation for `form_field_bindings`. The table has a
+ * Marker subclass — see FormFieldChildTableMorphScope for the full
- * polymorphic owner that points at either `form_field` or
+ * UNION-over-two-owner-chains scope logic.
- * `form_field_library`; `OrganisationScope` (Q2 FK-chain resolver) can't
- * walk a morph parent, so this scope does the equivalent UNION walk:
  *
- *   owner_id ∈ (
+ * The class identity is preserved so that existing
- *     SELECT id FROM form_fields
+ * `withoutGlobalScope(FormFieldBindingScope::class)` call sites in
- *       WHERE form_schema_id ∈ (SELECT id FROM form_schemas WHERE organisation_id = ?)
+ * cascade observers, backfill migrations, and platform super_admin
- *     UNION
+ * paths continue to work unchanged. The behaviour is identical
- *     SELECT id FROM form_field_library
+ * across all four siblings.
- *       WHERE organisation_id = ?
- *   )
  *
- * Organisation context resolution mirrors `OrganisationScope` — explicit
+ * History: WS-5a; ARCH-FORM-BUILDER §6.7 and
- * override via constructor, then the `organisation` / `event` route
+ * ARCH-CONSOLIDATION-ADDENDUM-2026-04-24.md §Q3 Uitvoering sections.
- * parameter fallbacks. CLI, queues, and unauthenticated flows skip the
- * scope (consistent with OrganisationScope).
- *
- * Escape hatch: callers that need cross-tenant reads use
- * `FormFieldBinding::withoutGlobalScope(FormFieldBindingScope::class)`.
  */
-final class FormFieldBindingScope implements Scope
+final class FormFieldBindingScope extends FormFieldChildTableMorphScope {}
-{
-    public function __construct(
-        private readonly ?string $organisationId = null,
-    ) {}
-
-    public function apply(Builder $builder, Model $model): void
-    {
-        $orgId = $this->resolveOrganisationId();
-        if ($orgId === null) {
-            return;
-        }
-
-        $fieldIds = FormField::query()
-            ->withoutGlobalScope(OrganisationScope::class)
-            ->whereIn(
-                'form_schema_id',
-                FormSchema::query()
-                    ->withoutGlobalScope(OrganisationScope::class)
-                    ->where('organisation_id', $orgId)
-                    ->select('id'),
-            )
-            ->select('id');
-
-        $libraryIds = FormFieldLibrary::query()
-            ->withoutGlobalScope(OrganisationScope::class)
-            ->where('organisation_id', $orgId)
-            ->select('id');
-
-        $table = $model->getTable();
-
-        $builder->where(function (Builder $outer) use ($table, $fieldIds, $libraryIds): void {
-            $outer->where(function (Builder $q) use ($table, $fieldIds): void {
-                $q->where("$table.owner_type", 'form_field')
-                    ->whereIn("$table.owner_id", $fieldIds);
-            })->orWhere(function (Builder $q) use ($table, $libraryIds): void {
-                $q->where("$table.owner_type", 'form_field_library')
-                    ->whereIn("$table.owner_id", $libraryIds);
-            });
-        });
-    }
-
-    private function resolveOrganisationId(): ?string
-    {
-        if ($this->organisationId !== null) {
-            return $this->organisationId;
-        }
-
-        $route = request()->route();
-        if ($route === null) {
-            return null;
-        }
-
-        $org = $route->parameter('organisation');
-
-        if ($org instanceof \App\Models\Organisation) {
-            return $org->id;
-        }
-
-        if (is_string($org) && $org !== '') {
-            return $org;
-        }
-
-        $event = $route->parameter('event');
-        if ($event instanceof \App\Models\Event) {
-            return $event->organisation_id;
-        }
-
-        return null;
-    }
-}

api/app/Models/Scopes/FormFieldChildTableMorphScope.php

@@ -0,0 +1,125 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models\Scopes;
+
+use App\Models\Event;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormFieldLibrary;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\Organisation;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Scope;
+
+/**
+ * Shared base for the four polymorphic morph-scope siblings on the
+ * form-field child tables (form_field_bindings,
+ * form_field_validation_rules, form_field_configs, form_field_options).
+ *
+ * Each child table holds rows owned via (owner_type, owner_id) where
+ * owner_type ∈ {form_field, form_field_library}. This scope enforces
+ * organisation-tenancy on those rows by resolving the request's
+ * organisation context and constraining the visible rows to:
+ *
+ *   owner_id ∈ (
+ *     SELECT id FROM form_fields
+ *       WHERE form_schema_id ∈ (
+ *         SELECT id FROM form_schemas WHERE organisation_id = ?
+ *       )
+ *     UNION
+ *     SELECT id FROM form_field_library
+ *       WHERE organisation_id = ?
+ *   )
+ *
+ * Concrete subclasses are marker classes — they exist solely to preserve
+ * class identity for `Model::withoutGlobalScope(SubclassName::class)`
+ * call sites in cascade observers, backfill migrations, and platform
+ * super_admin escape paths.
+ *
+ * If a future sibling needs to vary the morph aliases or the
+ * owner-chain, the relevant private helpers can be promoted to
+ * protected and overridden — but YAGNI applies until that need
+ * concretely materialises.
+ *
+ * Background: addendum §Q3 WS-5a/b/c/d Uitvoering tracked the
+ * extraction-deferral discipline ("premature abstraction from N is
+ * still premature when sibling N+1 is about to land"). All four
+ * concrete implementations exist; this class is the answer to
+ * "what actually varies" — nothing.
+ */
+abstract class FormFieldChildTableMorphScope implements Scope
+{
+    private const OWNER_TYPE_FIELD = 'form_field';
+    private const OWNER_TYPE_LIBRARY = 'form_field_library';
+
+    public function __construct(
+        private readonly ?string $organisationId = null,
+    ) {}
+
+    public function apply(Builder $builder, Model $model): void
+    {
+        $orgId = $this->resolveOrganisationId();
+        if ($orgId === null) {
+            return;
+        }
+
+        $fieldIds = FormField::query()
+            ->withoutGlobalScope(OrganisationScope::class)
+            ->whereIn(
+                'form_schema_id',
+                FormSchema::query()
+                    ->withoutGlobalScope(OrganisationScope::class)
+                    ->where('organisation_id', $orgId)
+                    ->select('id'),
+            )
+            ->select('id');
+
+        $libraryIds = FormFieldLibrary::query()
+            ->withoutGlobalScope(OrganisationScope::class)
+            ->where('organisation_id', $orgId)
+            ->select('id');
+
+        $table = $model->getTable();
+
+        $builder->where(function (Builder $outer) use ($table, $fieldIds, $libraryIds): void {
+            $outer->where(function (Builder $q) use ($table, $fieldIds): void {
+                $q->where("$table.owner_type", self::OWNER_TYPE_FIELD)
+                    ->whereIn("$table.owner_id", $fieldIds);
+            })->orWhere(function (Builder $q) use ($table, $libraryIds): void {
+                $q->where("$table.owner_type", self::OWNER_TYPE_LIBRARY)
+                    ->whereIn("$table.owner_id", $libraryIds);
+            });
+        });
+    }
+
+    private function resolveOrganisationId(): ?string
+    {
+        if ($this->organisationId !== null) {
+            return $this->organisationId;
+        }
+
+        $route = request()->route();
+        if ($route === null) {
+            return null;
+        }
+
+        $org = $route->parameter('organisation');
+
+        if ($org instanceof Organisation) {
+            return $org->id;
+        }
+
+        if (is_string($org) && $org !== '') {
+            return $org;
+        }
+
+        $event = $route->parameter('event');
+        if ($event instanceof Event) {
+            return $event->organisation_id;
+        }
+
+        return null;
+    }
+}

api/app/Models/Scopes/FormFieldConfigScope.php

@@ -4,99 +4,17 @@ declare(strict_types=1);
 
 namespace App\Models\Scopes;
 
-use App\Models\FormBuilder\FormField;
-use App\Models\FormBuilder\FormFieldLibrary;
-use App\Models\FormBuilder\FormSchema;
-use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Database\Eloquent\Model;
-use Illuminate\Database\Eloquent\Scope;
-
 /**
- * Third sibling in the form-field-child-table scope family, after
+ * Marker subclass — see FormFieldChildTableMorphScope for the full
- * `FormFieldBindingScope` (WS-5a) and `FormFieldValidationRuleScope`
+ * UNION-over-two-owner-chains scope logic.
- * (WS-5b commit 1). Identical UNION-over-two-owner-chains shape:
  *
- *   owner_id ∈ (
+ * The class identity is preserved so that existing
- *     SELECT id FROM form_fields
+ * `withoutGlobalScope(FormFieldConfigScope::class)` call sites in
- *       WHERE form_schema_id ∈ (SELECT id FROM form_schemas WHERE organisation_id = ?)
+ * cascade observers, backfill migrations, and platform super_admin
- *     UNION
+ * paths continue to work unchanged. The behaviour is identical
- *     SELECT id FROM form_field_library
+ * across all four siblings.
- *       WHERE organisation_id = ?
- *   )
  *
- * Base-class extraction between the three siblings is deliberately
+ * History: WS-5b commit 5; ARCH-FORM-BUILDER §17.5.3 and
- * deferred to WS-5d (where `form_field_options` lands and the fourth
+ * ARCH-CONSOLIDATION-ADDENDUM-2026-04-24.md §Q3 Uitvoering sections.
- * concrete implementation may clarify what truly varies). Premature
- * abstraction from three is still premature.
  */
-final class FormFieldConfigScope implements Scope
+final class FormFieldConfigScope extends FormFieldChildTableMorphScope {}
-{
-    public function __construct(
-        private readonly ?string $organisationId = null,
-    ) {}
-
-    public function apply(Builder $builder, Model $model): void
-    {
-        $orgId = $this->resolveOrganisationId();
-        if ($orgId === null) {
-            return;
-        }
-
-        $fieldIds = FormField::query()
-            ->withoutGlobalScope(OrganisationScope::class)
-            ->whereIn(
-                'form_schema_id',
-                FormSchema::query()
-                    ->withoutGlobalScope(OrganisationScope::class)
-                    ->where('organisation_id', $orgId)
-                    ->select('id'),
-            )
-            ->select('id');
-
-        $libraryIds = FormFieldLibrary::query()
-            ->withoutGlobalScope(OrganisationScope::class)
-            ->where('organisation_id', $orgId)
-            ->select('id');
-
-        $table = $model->getTable();
-
-        $builder->where(function (Builder $outer) use ($table, $fieldIds, $libraryIds): void {
-            $outer->where(function (Builder $q) use ($table, $fieldIds): void {
-                $q->where("$table.owner_type", 'form_field')
-                    ->whereIn("$table.owner_id", $fieldIds);
-            })->orWhere(function (Builder $q) use ($table, $libraryIds): void {
-                $q->where("$table.owner_type", 'form_field_library')
-                    ->whereIn("$table.owner_id", $libraryIds);
-            });
-        });
-    }
-
-    private function resolveOrganisationId(): ?string
-    {
-        if ($this->organisationId !== null) {
-            return $this->organisationId;
-        }
-
-        $route = request()->route();
-        if ($route === null) {
-            return null;
-        }
-
-        $org = $route->parameter('organisation');
-
-        if ($org instanceof \App\Models\Organisation) {
-            return $org->id;
-        }
-
-        if (is_string($org) && $org !== '') {
-            return $org;
-        }
-
-        $event = $route->parameter('event');
-        if ($event instanceof \App\Models\Event) {
-            return $event->organisation_id;
-        }
-
-        return null;
-    }
-}

api/app/Models/Scopes/FormFieldOptionScope.php

@@ -4,104 +4,17 @@ declare(strict_types=1);
 
 namespace App\Models\Scopes;
 
-use App\Models\FormBuilder\FormField;
-use App\Models\FormBuilder\FormFieldLibrary;
-use App\Models\FormBuilder\FormSchema;
-use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Database\Eloquent\Model;
-use Illuminate\Database\Eloquent\Scope;
-
 /**
- * Fourth and final sibling in the form-field-child-table scope family,
+ * Marker subclass — see FormFieldChildTableMorphScope for the full
- * after `FormFieldBindingScope` (WS-5a),
+ * UNION-over-two-owner-chains scope logic.
- * `FormFieldValidationRuleScope` and `FormFieldConfigScope` (WS-5b).
  *
- * Identical UNION-over-two-owner-chains shape:
+ * The class identity is preserved so that existing
+ * `withoutGlobalScope(FormFieldOptionScope::class)` call sites in
+ * cascade observers, backfill migrations, and platform super_admin
+ * paths continue to work unchanged. The behaviour is identical
+ * across all four siblings.
  *
- *   owner_id ∈ (
+ * History: WS-5d; ARCH-FORM-BUILDER §17.6.3 and
- *     SELECT id FROM form_fields
+ * ARCH-CONSOLIDATION-ADDENDUM-2026-04-24.md §Q3 Uitvoering sections.
- *       WHERE form_schema_id ∈ (SELECT id FROM form_schemas WHERE organisation_id = ?)
- *     UNION
- *     SELECT id FROM form_field_library
- *       WHERE organisation_id = ?
- *   )
- *
- * Now that all four concrete implementations exist, base-class
- * extraction across the family is the logical follow-up — deferred to
- * a separate work package per addendum §17.4.3 / §17.5.3 / §17.6.3.
- *
- * Escape hatch: `FormFieldOption::withoutGlobalScope(FormFieldOptionScope::class)`
- * for cascade observers, backfill migrations, and platform super_admin
- * paths.
  */
-final class FormFieldOptionScope implements Scope
+final class FormFieldOptionScope extends FormFieldChildTableMorphScope {}
-{
-    public function __construct(
-        private readonly ?string $organisationId = null,
-    ) {}
-
-    public function apply(Builder $builder, Model $model): void
-    {
-        $orgId = $this->resolveOrganisationId();
-        if ($orgId === null) {
-            return;
-        }
-
-        $fieldIds = FormField::query()
-            ->withoutGlobalScope(OrganisationScope::class)
-            ->whereIn(
-                'form_schema_id',
-                FormSchema::query()
-                    ->withoutGlobalScope(OrganisationScope::class)
-                    ->where('organisation_id', $orgId)
-                    ->select('id'),
-            )
-            ->select('id');
-
-        $libraryIds = FormFieldLibrary::query()
-            ->withoutGlobalScope(OrganisationScope::class)
-            ->where('organisation_id', $orgId)
-            ->select('id');
-
-        $table = $model->getTable();
-
-        $builder->where(function (Builder $outer) use ($table, $fieldIds, $libraryIds): void {
-            $outer->where(function (Builder $q) use ($table, $fieldIds): void {
-                $q->where("$table.owner_type", 'form_field')
-                    ->whereIn("$table.owner_id", $fieldIds);
-            })->orWhere(function (Builder $q) use ($table, $libraryIds): void {
-                $q->where("$table.owner_type", 'form_field_library')
-                    ->whereIn("$table.owner_id", $libraryIds);
-            });
-        });
-    }
-
-    private function resolveOrganisationId(): ?string
-    {
-        if ($this->organisationId !== null) {
-            return $this->organisationId;
-        }
-
-        $route = request()->route();
-        if ($route === null) {
-            return null;
-        }
-
-        $org = $route->parameter('organisation');
-
-        if ($org instanceof \App\Models\Organisation) {
-            return $org->id;
-        }
-
-        if (is_string($org) && $org !== '') {
-            return $org;
-        }
-
-        $event = $route->parameter('event');
-        if ($event instanceof \App\Models\Event) {
-            return $event->organisation_id;
-        }
-
-        return null;
-    }
-}

api/app/Models/Scopes/FormFieldValidationRuleScope.php

@@ -4,99 +4,17 @@ declare(strict_types=1);
 
 namespace App\Models\Scopes;
 
-use App\Models\FormBuilder\FormField;
-use App\Models\FormBuilder\FormFieldLibrary;
-use App\Models\FormBuilder\FormSchema;
-use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Database\Eloquent\Model;
-use Illuminate\Database\Eloquent\Scope;
-
 /**
- * Multi-tenant isolation for `form_field_validation_rules`. Sibling to
+ * Marker subclass — see FormFieldChildTableMorphScope for the full
- * `FormFieldBindingScope` — the two share the same UNION shape over the
+ * UNION-over-two-owner-chains scope logic.
- * polymorphic owner's two possible parents (`form_field → form_schema →
- * organisation_id` ∪ `form_field_library → organisation_id`).
  *
- * Duplicate code with `FormFieldBindingScope` is acknowledged; base-class
+ * The class identity is preserved so that existing
- * extraction is deferred to WS-5d per the architect addendum Q3 decision:
+ * `withoutGlobalScope(FormFieldValidationRuleScope::class)` call sites
- * premature abstraction from two is still premature, and WS-5d adds a
+ * in cascade observers, backfill migrations, and platform super_admin
- * third sibling that will make what truly varies visible.
+ * paths continue to work unchanged. The behaviour is identical
+ * across all four siblings.
  *
- * Organisation context resolution mirrors `OrganisationScope` — explicit
+ * History: WS-5b; ARCH-FORM-BUILDER §17.4.3 and
- * override via constructor, then `organisation` / `event` route parameter
+ * ARCH-CONSOLIDATION-ADDENDUM-2026-04-24.md §Q3 Uitvoering sections.
- * fallbacks. CLI, queues, and unauthenticated flows skip the scope.
- *
- * Escape hatch:
- * `FormFieldValidationRule::withoutGlobalScope(FormFieldValidationRuleScope::class)`.
  */
-final class FormFieldValidationRuleScope implements Scope
+final class FormFieldValidationRuleScope extends FormFieldChildTableMorphScope {}
-{
-    public function __construct(
-        private readonly ?string $organisationId = null,
-    ) {}
-
-    public function apply(Builder $builder, Model $model): void
-    {
-        $orgId = $this->resolveOrganisationId();
-        if ($orgId === null) {
-            return;
-        }
-
-        $fieldIds = FormField::query()
-            ->withoutGlobalScope(OrganisationScope::class)
-            ->whereIn(
-                'form_schema_id',
-                FormSchema::query()
-                    ->withoutGlobalScope(OrganisationScope::class)
-                    ->where('organisation_id', $orgId)
-                    ->select('id'),
-            )
-            ->select('id');
-
-        $libraryIds = FormFieldLibrary::query()
-            ->withoutGlobalScope(OrganisationScope::class)
-            ->where('organisation_id', $orgId)
-            ->select('id');
-
-        $table = $model->getTable();
-
-        $builder->where(function (Builder $outer) use ($table, $fieldIds, $libraryIds): void {
-            $outer->where(function (Builder $q) use ($table, $fieldIds): void {
-                $q->where("$table.owner_type", 'form_field')
-                    ->whereIn("$table.owner_id", $fieldIds);
-            })->orWhere(function (Builder $q) use ($table, $libraryIds): void {
-                $q->where("$table.owner_type", 'form_field_library')
-                    ->whereIn("$table.owner_id", $libraryIds);
-            });
-        });
-    }
-
-    private function resolveOrganisationId(): ?string
-    {
-        if ($this->organisationId !== null) {
-            return $this->organisationId;
-        }
-
-        $route = request()->route();
-        if ($route === null) {
-            return null;
-        }
-
-        $org = $route->parameter('organisation');
-
-        if ($org instanceof \App\Models\Organisation) {
-            return $org->id;
-        }
-
-        if (is_string($org) && $org !== '') {
-            return $org;
-        }
-
-        $event = $route->parameter('event');
-        if ($event instanceof \App\Models\Event) {
-            return $event->organisation_id;
-        }
-
-        return null;
-    }
-}