refactor(form-field): resources + snapshot + validator read form_field_options

Atomic reader switch. All call paths that previously read
form_fields.options / form_field_library.options from the JSON column
now read through FormFieldOptionService::toJsonShape() via the
morphMany relation:

  - FormFieldResource + FormFieldLibraryResource +
    PublicFormSchemaResource emit the rich-shape array
  - FilterRegistryController emits rich shape uniformly (no flat-array
    carve-out for filter-UI compatibility — preflight scan confirmed
    zero portal/app consumers, S5 territory)
  - FormFieldRuleBuilder plucks values from the relation for in:options
    rule construction
  - FormSubmissionService::buildSnapshot writes rich-shape options into
    snapshots and strips translations.{locale}.options from each field's
    translations bag (defensive — commit 2 backfill already did the
    bulk strip)
  - Four FormFieldRequest variants accept array-of-spec-objects,
    validate shape in after() via FormFieldOptionService::assertSpecsValid,
    and hand off to FormFieldOptionService::replaceOptions for writes
  - FormFieldService::create + update extract option specs from the
    request data and route through the service after the FormField row
    is persisted

FormField and FormFieldLibrary $casts no longer include 'options'; the
JSON column is no longer cast. Options removed from $fillable on both
models so ::create() / ::fill() / mass assignment can no longer touch
the legacy column. Both models gain a getOptionsAttribute() accessor
that resolves $model->options to the eager-loaded morphMany collection
— required because Eloquent's getAttribute() prefers a real DB column
over a relation method, and the JSON column lives on the table until
WS-5d commit 5 drops it.

Activity log — dual emit per §6.7 / §17.4.2 / §17.6.3:
  - field.updated carries old.options / new.options diff via
    toJsonShape() reconstruction, byte-equal JSON compare to avoid
    cosmetic false positives. Field updates that don't touch options
    omit the key entirely
  - field.options_replaced emits inside replaceOptions() on FormField
    subject only; library subject writes silent (mirrors the WS-5b /
    WS-5c convention)

JSON columns (form_fields.options, form_field_library.options) remain
present but unread — column drops land atomically in commit 5.

Two pre-existing test fixtures that seeded options via the JSON column
(FormFieldApiTest + PublicFormValidationTest) migrated to the
spec-array path: FormField::factory()->withOptions([...]) where the
options live on the field, or explicit spec-array request bodies for
HTTP tests.

Tests: 1193 → 1206 green (+13 tests / +28 assertions).

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

api/tests/Feature/Api/V1/Public/FormBuilder/PublicFormValidationTest.php

@@ -55,15 +55,16 @@ final class PublicFormValidationTest extends TestCase
                 'is_required' => false,
                 'is_portal_visible' => true,
             ]);
-        FormField::factory()->create([
-            'form_schema_id' => $this->schema->id,
-            'field_type' => FormFieldType::SELECT->value,
-            'slug' => 'shirtmaat',
-            'label' => 'Shirtmaat',
-            'options' => ['S', 'M', 'L'],
-            'is_required' => false,
-            'is_portal_visible' => true,
-        ]);
+        FormField::factory()
+            ->withOptions(['S', 'M', 'L'])
+            ->create([
+                'form_schema_id' => $this->schema->id,
+                'field_type' => FormFieldType::SELECT->value,
+                'slug' => 'shirtmaat',
+                'label' => 'Shirtmaat',
+                'is_required' => false,
+                'is_portal_visible' => true,
+            ]);
     }
 
     public function test_email_rejects_bad_format(): void

api/tests/Feature/FormBuilder/FormFieldApiTest.php

@@ -44,7 +44,12 @@ final class FormFieldApiTest extends TestCase
             'field_type' => FormFieldType::SELECT->value,
             'slug' => 'shirtmaat',
             'label' => 'Shirtmaat',
-            'options' => ['XS', 'S', 'M', 'L'],
+            'options' => [
+                ['value' => 'XS', 'label' => 'XS', 'sort_order' => 0],
+                ['value' => 'S', 'label' => 'S', 'sort_order' => 1],
+                ['value' => 'M', 'label' => 'M', 'sort_order' => 2],
+                ['value' => 'L', 'label' => 'L', 'sort_order' => 3],
+            ],
         ]);
 
         $response->assertCreated();

api/tests/Feature/FormBuilder/Options/FormFieldOptionsActivityLogTest.php

@@ -0,0 +1,149 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder\Options;
+
+use App\Enums\FormBuilder\FormFieldType;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormFieldLibrary;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\Organisation;
+use App\Services\FormBuilder\FormFieldOptionService;
+use App\Services\FormBuilder\FormFieldService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Spatie\Activitylog\Models\Activity;
+use Tests\TestCase;
+
+/**
+ * Dual-emit pattern for option changes per ARCH §17.6.3 (mirrors the
+ * §8.6 / §17.4.2 convention from WS-5b/c): every options change on a
+ * FormField emits both `field.updated` (carrying the old/new diff in
+ * its payload) and `field.options_replaced` (semantic event from
+ * FormFieldOptionService::replaceOptions). FormFieldLibrary writes are
+ * silent.
+ */
+final class FormFieldOptionsActivityLogTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_field_updated_payload_contains_options_diff_when_options_change(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()
+            ->withOptions(['a', 'b'])
+            ->create([
+                'form_schema_id' => $schema->id,
+                'field_type' => FormFieldType::SELECT->value,
+                'slug' => 'colour',
+                'label' => 'Colour',
+            ]);
+
+        // Suppress prior activity (factory creation) and re-bound the
+        // window for assertion clarity.
+        Activity::query()->delete();
+
+        app(FormFieldService::class)->update($field, [
+            'options' => [
+                ['value' => 'a', 'label' => 'A', 'sort_order' => 0],
+                ['value' => 'b', 'label' => 'b', 'sort_order' => 1],
+                ['value' => 'c', 'label' => 'c', 'sort_order' => 2],
+            ],
+        ]);
+
+        $event = Activity::query()
+            ->where('subject_type', 'form_field')
+            ->where('subject_id', $field->id)
+            ->where('description', 'field.updated')
+            ->first();
+        $this->assertNotNull($event);
+        $payload = $event->properties->toArray();
+        $this->assertArrayHasKey('options', $payload['old']);
+        $this->assertArrayHasKey('options', $payload['new']);
+        $this->assertSame(
+            [
+                ['value' => 'a', 'label' => 'a', 'sort_order' => 0],
+                ['value' => 'b', 'label' => 'b', 'sort_order' => 1],
+            ],
+            $payload['old']['options'],
+        );
+        $this->assertSame(
+            [
+                ['value' => 'a', 'label' => 'A', 'sort_order' => 0],
+                ['value' => 'b', 'label' => 'b', 'sort_order' => 1],
+                ['value' => 'c', 'label' => 'c', 'sort_order' => 2],
+            ],
+            $payload['new']['options'],
+        );
+    }
+
+    public function test_field_updated_payload_omits_options_key_when_only_label_changed(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()
+            ->withOptions(['a', 'b'])
+            ->create([
+                'form_schema_id' => $schema->id,
+                'field_type' => FormFieldType::SELECT->value,
+                'slug' => 'choice',
+                'label' => 'Old',
+            ]);
+
+        Activity::query()->delete();
+
+        app(FormFieldService::class)->update($field, [
+            'label' => 'New',
+        ]);
+
+        $event = Activity::query()
+            ->where('subject_type', 'form_field')
+            ->where('subject_id', $field->id)
+            ->where('description', 'field.updated')
+            ->first();
+        $this->assertNotNull($event);
+        $payload = $event->properties->toArray();
+        $this->assertArrayNotHasKey('options', $payload['old']);
+        $this->assertArrayNotHasKey('options', $payload['new']);
+    }
+
+    public function test_options_replaced_emits_on_form_field_subject(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()->create([
+            'form_schema_id' => $schema->id,
+            'field_type' => FormFieldType::SELECT->value,
+        ]);
+
+        Activity::query()->delete();
+
+        app(FormFieldOptionService::class)->replaceOptions($field, [
+            ['value' => 'x', 'label' => 'X', 'sort_order' => 0],
+        ]);
+
+        $this->assertNotNull(Activity::query()
+            ->where('subject_type', 'form_field')
+            ->where('subject_id', $field->id)
+            ->where('description', 'field.options_replaced')
+            ->first());
+    }
+
+    public function test_options_replaced_silent_on_library_subject(): void
+    {
+        $org = Organisation::factory()->create();
+        $library = FormFieldLibrary::factory()->create(['organisation_id' => $org->id]);
+
+        Activity::query()->delete();
+
+        app(FormFieldOptionService::class)->replaceOptions($library, [
+            ['value' => 'x', 'label' => 'X', 'sort_order' => 0],
+        ]);
+
+        $this->assertNull(Activity::query()
+            ->where('subject_type', 'form_field_library')
+            ->where('description', 'field.options_replaced')
+            ->first());
+    }
+}

api/tests/Feature/FormBuilder/Options/FormFieldOptionsSnapshotAndStrictRequestTest.php

@@ -0,0 +1,166 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder\Options;
+
+use App\Enums\FormBuilder\FormFieldType;
+use App\Enums\FormBuilder\FormPurpose;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\Organisation;
+use App\Services\FormBuilder\FormSubmissionService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+/**
+ * Snapshot embedding parity (FormSubmissionService::buildSnapshot) +
+ * FormRequest strict validator coverage for the spec-array shape. Both
+ * land at WS-5d commit 3.
+ */
+final class FormFieldOptionsSnapshotAndStrictRequestTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_submission_snapshot_embeds_rich_shape_options(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create([
+            'organisation_id' => $org->id,
+            'snapshot_mode' => 'on_submit',
+            'is_published' => true,
+            'public_token' => (string) \Illuminate\Support\Str::ulid(),
+        ]);
+        FormField::factory()
+            ->withOptions(['XS', 'S', 'M'])
+            ->create([
+                'form_schema_id' => $schema->id,
+                'field_type' => FormFieldType::SELECT->value,
+                'slug' => 'shirtmaat',
+                'label' => 'Shirtmaat',
+            ]);
+
+        $service = app(FormSubmissionService::class);
+        $draft = $service->createDraft($schema, null, null, []);
+        $service->submit($draft, null);
+
+        $snapshot = $draft->fresh()->schema_snapshot;
+        $this->assertIsArray($snapshot);
+        $field = collect($snapshot['fields'])->firstWhere('slug', 'shirtmaat');
+        $this->assertSame(
+            [
+                ['value' => 'XS', 'label' => 'XS', 'sort_order' => 0],
+                ['value' => 'S', 'label' => 'S', 'sort_order' => 1],
+                ['value' => 'M', 'label' => 'M', 'sort_order' => 2],
+            ],
+            $field['options'],
+        );
+    }
+
+    public function test_submission_snapshot_does_not_emit_locale_options_in_field_translations(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create([
+            'organisation_id' => $org->id,
+            'snapshot_mode' => 'on_submit',
+            'is_published' => true,
+            'public_token' => (string) \Illuminate\Support\Str::ulid(),
+        ]);
+        FormField::factory()
+            ->withOptions([
+                ['value' => 'a', 'label' => 'A', 'sort_order' => 0, 'translations' => ['nl' => 'AA']],
+            ])
+            ->create([
+                'form_schema_id' => $schema->id,
+                'field_type' => FormFieldType::SELECT->value,
+                'slug' => 'choice',
+                'label' => 'Choice',
+                // Per-locale label kept; the legacy {locale}.options[] is
+                // dead post-WS-5d.
+                'translations' => ['nl' => ['label' => 'Keuze']],
+            ]);
+
+        $service = app(FormSubmissionService::class);
+        $draft = $service->createDraft($schema, null, null, []);
+        $service->submit($draft, null);
+
+        $snapshot = $draft->fresh()->schema_snapshot;
+        $field = collect($snapshot['fields'])->firstWhere('slug', 'choice');
+        if (is_array($field['translations'] ?? null)) {
+            foreach ($field['translations'] as $locale => $bag) {
+                $this->assertArrayNotHasKey('options', is_array($bag) ? $bag : [], "locale {$locale} kept legacy options key");
+            }
+        }
+    }
+
+    public function test_form_field_request_rejects_missing_value_in_spec(): void
+    {
+        $org = Organisation::factory()->create();
+        $admin = \App\Models\User::factory()->create();
+        $org->users()->attach($admin, ['role' => 'org_admin']);
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        \Laravel\Sanctum\Sanctum::actingAs($admin);
+
+        $response = $this->postJson("/api/v1/organisations/{$org->id}/forms/schemas/{$schema->id}/fields", [
+            'field_type' => FormFieldType::SELECT->value,
+            'slug' => 'choice',
+            'label' => 'Choice',
+            'options' => [
+                ['label' => 'A', 'sort_order' => 0],
+            ],
+        ]);
+
+        $response->assertStatus(422);
+        $response->assertJsonValidationErrors(['options.0.value']);
+    }
+
+    public function test_form_field_request_rejects_duplicate_values_in_spec(): void
+    {
+        $org = Organisation::factory()->create();
+        $admin = \App\Models\User::factory()->create();
+        $org->users()->attach($admin, ['role' => 'org_admin']);
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        \Laravel\Sanctum\Sanctum::actingAs($admin);
+
+        $response = $this->postJson("/api/v1/organisations/{$org->id}/forms/schemas/{$schema->id}/fields", [
+            'field_type' => FormFieldType::SELECT->value,
+            'slug' => 'choice',
+            'label' => 'Choice',
+            'options' => [
+                ['value' => 'dup', 'label' => 'A', 'sort_order' => 0],
+                ['value' => 'dup', 'label' => 'B', 'sort_order' => 1],
+            ],
+        ]);
+
+        $response->assertStatus(422);
+        $response->assertJsonValidationErrors(['options']);
+    }
+
+    public function test_form_field_request_accepts_valid_spec(): void
+    {
+        $org = Organisation::factory()->create();
+        $admin = \App\Models\User::factory()->create();
+        $org->users()->attach($admin, ['role' => 'org_admin']);
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        \Laravel\Sanctum\Sanctum::actingAs($admin);
+
+        $response = $this->postJson("/api/v1/organisations/{$org->id}/forms/schemas/{$schema->id}/fields", [
+            'field_type' => FormFieldType::SELECT->value,
+            'slug' => 'choice',
+            'label' => 'Choice',
+            'options' => [
+                ['value' => 'red', 'label' => 'Red', 'sort_order' => 0],
+                ['value' => 'green', 'label' => 'Green', 'sort_order' => 1, 'translations' => ['nl' => 'Groen']],
+            ],
+        ]);
+
+        $response->assertCreated();
+        $this->assertSame(
+            [
+                ['value' => 'red', 'label' => 'Red', 'sort_order' => 0],
+                ['value' => 'green', 'label' => 'Green', 'sort_order' => 1, 'translations' => ['nl' => 'Groen']],
+            ],
+            $response->json('data.options'),
+        );
+    }
+}

api/tests/Feature/FormBuilder/Options/FormFieldResourceOptionsTest.php

@@ -0,0 +1,126 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder\Options;
+
+use App\Enums\FormBuilder\FormFieldType;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormFieldLibrary;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\Organisation;
+use App\Services\FormBuilder\FormFieldOptionService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+/**
+ * Resource-layer parity for the WS-5d rich-shape options array. Every
+ * resource that previously emitted flat-string-array options now emits
+ * the relational rich shape via FormFieldOptionService::toJsonShape().
+ */
+final class FormFieldResourceOptionsTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_form_field_resource_emits_rich_shape_options(): void
+    {
+        $org = Organisation::factory()->create();
+        $admin = \App\Models\User::factory()->create();
+        $org->users()->attach($admin, ['role' => 'org_admin']);
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        FormField::factory()
+            ->withOptions([
+                ['value' => 'red', 'label' => 'Red', 'sort_order' => 0, 'translations' => ['nl' => 'Rood']],
+                ['value' => 'green', 'label' => 'Green', 'sort_order' => 1],
+            ])
+            ->create([
+                'form_schema_id' => $schema->id,
+                'field_type' => FormFieldType::SELECT->value,
+                'slug' => 'colour',
+                'label' => 'Colour',
+            ]);
+
+        \Laravel\Sanctum\Sanctum::actingAs($admin);
+
+        $response = $this->getJson("/api/v1/organisations/{$org->id}/forms/schemas/{$schema->id}/fields");
+
+        $response->assertOk();
+        $emitted = collect($response->json('data'))->firstWhere('slug', 'colour');
+        $this->assertSame(
+            [
+                ['value' => 'red', 'label' => 'Red', 'sort_order' => 0, 'translations' => ['nl' => 'Rood']],
+                ['value' => 'green', 'label' => 'Green', 'sort_order' => 1],
+            ],
+            $emitted['options'],
+        );
+    }
+
+    public function test_form_field_resource_emits_null_options_for_option_less_field_type(): void
+    {
+        $org = Organisation::factory()->create();
+        $admin = \App\Models\User::factory()->create();
+        $org->users()->attach($admin, ['role' => 'org_admin']);
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        FormField::factory()->create([
+            'form_schema_id' => $schema->id,
+            'field_type' => FormFieldType::TEXT->value,
+            'slug' => 'name',
+            'label' => 'Name',
+        ]);
+
+        \Laravel\Sanctum\Sanctum::actingAs($admin);
+
+        $response = $this->getJson("/api/v1/organisations/{$org->id}/forms/schemas/{$schema->id}/fields");
+
+        $response->assertOk();
+        $emitted = collect($response->json('data'))->firstWhere('slug', 'name');
+        $this->assertNull($emitted['options']);
+    }
+
+    public function test_library_resource_emits_rich_shape_options(): void
+    {
+        $org = Organisation::factory()->create();
+        $admin = \App\Models\User::factory()->create();
+        $org->users()->attach($admin, ['role' => 'org_admin']);
+        $library = FormFieldLibrary::factory()
+            ->withOptions(['a', 'b'])
+            ->create(['organisation_id' => $org->id]);
+
+        \Laravel\Sanctum\Sanctum::actingAs($admin);
+
+        $response = $this->getJson("/api/v1/organisations/{$org->id}/forms/field-library/{$library->id}");
+
+        $response->assertOk();
+        $this->assertSame(
+            [
+                ['value' => 'a', 'label' => 'a', 'sort_order' => 0],
+                ['value' => 'b', 'label' => 'b', 'sort_order' => 1],
+            ],
+            $response->json('data.options'),
+        );
+    }
+
+    public function test_to_json_shape_is_byte_equal_to_resource_output(): void
+    {
+        $org = Organisation::factory()->create();
+        $schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
+        $field = FormField::factory()
+            ->withOptions(['x', 'y', 'z'])
+            ->create([
+                'form_schema_id' => $schema->id,
+                'field_type' => FormFieldType::RADIO->value,
+            ]);
+
+        $service = app(FormFieldOptionService::class);
+        $shape = $service->toJsonShape($service->optionsFor($field));
+
+        $this->assertSame(
+            [
+                ['value' => 'x', 'label' => 'x', 'sort_order' => 0],
+                ['value' => 'y', 'label' => 'y', 'sort_order' => 1],
+                ['value' => 'z', 'label' => 'z', 'sort_order' => 2],
+            ],
+            $shape,
+        );
+    }
+}